Get Result

Endpoint

GET https://aircube.ai/api/v3/status/{id}

Retrieves the current status of a generation. When the status is completed, the response includes a signed URL to download the output.

Path parameters

Parameter	Type	Description
`id`	string	The generation ID returned from the submit endpoint

Request headers

Header	Value
`Authorization`	`Bearer sk-your-api-key`

Response

Status: 200 OK

Processing

{
  "success": true,
  "data": {
    "id": "gen_abc123def456",
    "status": "processing",
    "model": "Seedream 5.0 Pro",
    "type": "image",
    "output_url": null,
    "created_at": "2025-01-15T12:00:00.000Z"
  }
}

Completed

{
  "success": true,
  "data": {
    "id": "gen_abc123def456",
    "status": "completed",
    "model": "Seedream 5.0 Pro",
    "type": "image",
    "output_url": "https://r2.aircube.dev/assets/gen_abc123def456.png?X-Amz-Signature=...",
    "created_at": "2025-01-15T12:00:00.000Z"
  }
}

Failed

{
  "success": true,
  "data": {
    "id": "gen_abc123def456",
    "status": "failed",
    "model": "Seedream 5.0 Pro",
    "type": "image",
    "output_url": null,
    "created_at": "2025-01-15T12:00:00.000Z"
  }
}

Status values

Status	Description
`queued`	Request received and waiting to be processed
`processing`	Currently being generated by the AI model
`completed`	Generation successful — `output_url` contains the result
`failed`	Generation failed — credits are automatically refunded

Output URL

When the status is completed, the output_url field contains a signed URL for downloading the output:

Valid for 7 days from the time of generation
Hosted on Cloudflare R2 storage
Download the file before the URL expires

Recommended polling strategy

Different generation types take different amounts of time. Use these intervals as a starting point:

Type	Recommended interval
Image	3 seconds
Video	5 seconds
Audio	3 seconds

Always set a maximum number of retries or a timeout to avoid polling indefinitely.

Error responses

Status	Code	When
401	`UNAUTHORIZED`	Missing or invalid API key
404	`NOT_FOUND`	Generation ID not found or missing
500	`INTERNAL_ERROR`	Failed to retrieve status

Examples

cURL

curl https://aircube.ai/api/v3/status/gen_abc123def456 \
  -H "Authorization: Bearer $AIRCUBE_API_KEY"

Python polling loop

import os
import time
import requests

API_KEY = os.environ["AIRCUBE_API_KEY"]

def poll_result(generation_id, interval=3, max_attempts=60):
    """Poll for a generation result until completed or failed."""
    url = f"https://aircube.ai/api/v3/status/{generation_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        result = response.json()
        status = result["data"]["status"]

        if status == "completed":
            return result["data"]["output_url"]
        elif status == "failed":
            raise Exception("Generation failed")

        time.sleep(interval)

    raise TimeoutError("Polling timed out")

JavaScript polling loop

const API_KEY = process.env.AIRCUBE_API_KEY;

async function pollResult(generationId, interval = 3000, maxAttempts = 60) {
  const url = `https://aircube.ai/api/v3/status/${generationId}`;
  const headers = { Authorization: `Bearer ${API_KEY}` };

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(url, { headers });
    const result = await response.json();
    const status = result.data.status;

    if (status === "completed") {
      return result.data.output_url;
    } else if (status === "failed") {
      throw new Error("Generation failed");
    }

    await new Promise((r) => setTimeout(r, interval));
  }

  throw new Error("Polling timed out");
}

On this page