Submit Generation

Endpoint

POST https://aircube.ai/api/v3/{provider}/{model}/{task}

Submits an asynchronous generation request. Returns immediately with a generation ID that you use to poll for the result.

Path parameters

The URL path after /api/v3/ is split into segments:

Segment	Description	Example
`provider`	Model provider or family prefix	`seedream-v5.0-pro`, `kling-v3.0-std`
`model`	Model variant (optional for some models)	`edit-2511`, `standard`
`task`	Generation task type	`text-to-image`, `image-to-video`

If only two segments are provided (e.g. /api/v3/seedream-v5.0-pro/text-to-image), the first is the model and the second is the task. The task determines the output type:

Contains video → output type is video
Contains audio, music, speech, or tts → output type is audio
All others → output type is image

Example URLs

POST /api/v3/seedream-v5.0-pro/text-to-image
POST /api/v3/gpt-image-2/text-to-image
POST /api/v3/kling-v3.0-std/image-to-video
POST /api/v3/seedance-2.0/image-to-video
POST /api/v3/qwen3-tts/text-to-speech
POST /api/v3/qwen-image/edit-2511/image-editing

Request headers

Header	Value
`Authorization`	`Bearer sk-your-api-key`
`Content-Type`	`application/json`

Request body

All fields are optional — the required fields depend on the model and task.

Field	Type	Description
`prompt`	string	Text description for the generation
`image`	string	URL of a single input image (downloaded automatically)
`images`	string[]	URLs of up to 2 input images
`reference_images`	string[]	URLs of up to 9 reference images
`reference_videos`	string[]	URLs of up to 3 reference videos
`reference_audios`	string[]	URLs of up to 3 reference audios
`aspect_ratio`	string	Output aspect ratio, e.g. `"16:9"`, `"1:1"`, `"9:16"`
`resolution`	string	Output resolution, e.g. `"1024x1024"`
`duration`	string	Video duration in seconds, e.g. `"5"`, `"10"`
`quality`	string	Quality level: `"low"`, `"medium"`, or `"high"`
`count`	number	Number of outputs to generate (1–4)
`output_format`	string	Output format: `"png"`, `"jpeg"`, or `"webp"`
`voice`	string	Voice ID for text-to-speech models

Input media handling

When you provide URLs in image, images, reference_images, reference_videos, or reference_audios, AirCube automatically downloads the media and stores it for processing. Supported formats:

Images: jpg, jpeg, png, webp, gif
Videos: mp4, webm, mkv
Audio: mp3, wav, m4a

Response

Status: 202 Accepted

{
  "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"
  }
}

Field	Type	Description
`id`	string	Unique generation ID — use this to poll for results
`status`	string	Always `"processing"` on submission
`model`	string	Resolved display name of the model
`type`	string	`"image"`, `"video"`, or `"audio"`
`output_url`	null	Always `null` initially; populated when completed
`created_at`	string	ISO 8601 timestamp

Error responses

Status	Code	When
400	`VALIDATION_ERROR`	Invalid JSON body, missing required fields, or invalid media URL
401	`UNAUTHORIZED`	Missing or invalid API key
402	`PAYMENT_REQUIRED`	Insufficient credit balance
403	`FORBIDDEN`	API key is disabled or expired
404	`NOT_FOUND`	Model not found or task not supported
429	`RATE_LIMITED`	Rate limit exceeded

See Error Codes for the full error reference.

Examples

cURL

curl -X POST https://aircube.ai/api/v3/seedream-v5.0-pro/text-to-image \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cyberpunk cityscape at night, neon reflections on wet streets",
    "aspect_ratio": "16:9",
    "quality": "high"
  }'

Python

import os
import requests

response = requests.post(
    "https://aircube.ai/api/v3/seedream-v5.0-pro/text-to-image",
    headers={
        "Authorization": f"Bearer {os.environ['AIRCUBE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "a cyberpunk cityscape at night, neon reflections on wet streets",
        "aspect_ratio": "16:9",
        "quality": "high",
    },
)

data = response.json()
print(data["data"]["id"])  # Use this ID to poll for results

JavaScript

const response = await fetch(
  "https://aircube.ai/api/v3/seedream-v5.0-pro/text-to-image",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AIRCUBE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "a cyberpunk cityscape at night, neon reflections on wet streets",
      aspect_ratio: "16:9",
      quality: "high",
    }),
  }
);

const { data } = await response.json();
console.log(data.id); // Use this ID to poll for results

What happens next

After submitting, your request is queued for processing. Credits are charged immediately — if the generation fails, credits are automatically refunded.

Use the generation id from the response to poll for results.

Submit Generation

On this page