API reference

Generations

Create and inspect generation jobs.

6 min read

POST /v1/generations

Submit a new generation job. The call returns immediately with a generationId — poll GET /v1/generations/:id until status is completed or failed.

FieldTypeDescription
promptstringRequired. Text prompt for the generation.
modelIdstringRequired. One of the model IDs returned by /v1/generation-options.
attachmentsarrayOptional. Input / reference media as URLs. See below.
aspectRatiostringOptional. e.g. "16:9", "9:16", "1:1". Omit for audio.
optionsobjectModel-specific options — resolution, duration, modelVoiceId, gender, format, …

The public API is URL-only. There are no assetId attachments and no asset uploads — pass publicly-fetchable URLs for input media, and you'll get back URLs in the response (not mirrored to your asset library).

attachments[] shape

FieldTypeDescription
urlstringPublic URL to the input media. Server fetches it on your behalf.
rolestring"input" (primary subject), "reference" (style / context), or "last" (end frame, video only).

When a model supports multiple inputs, the prompt can reference them positionally as @1, @2, … in the order they appear in the array.

Example request

1curl -X POST $BASE_URL/v1/generations \
2  -H "x-api-key: $SIXART_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "prompt": "A futuristic city with neon lights at sunset",
6  "modelId": "nano-banana",
7  "attachments": [],
8  "aspectRatio": "16:9",
9  "options": { "resolution": "1K" }
10}'

Example response

1{
2  "success": 1,
3  "data": {
4    "generationId": "5cf0e4be-...",
5    "status": "queued"
6  }
7}

GET /v1/generations/:id

Fetch the current status of a generation. status is one of queued, running, completed, failed. Poll every ~2 seconds until terminal.

Request

1curl $BASE_URL/v1/generations/$GENERATION_ID \
2  -H "x-api-key: $SIXART_KEY"

Response

1{
2  "success": 1,
3  "data": {
4    "generationId": "5cf0e4be-...",
5    "status": "completed",
6    "outputs": [
7      {
8        "url": "https://cdn.sixart.dev/...",
9        "width": 1664,
10        "height": 928
11      }
12    ]
13  }
14}

Output URLs are signed and may expire. Mirror anything you want to keep to your own storage.