Generation result — Clipia Documentation

Fetch the finished generation with links to its media. While the job is queued or running, the call returns 202 — try again later.

Playground

Use a test key here

Paste a clipia_test_… key into the form below: it charges no credits and calls no models, and the response has the same shape. The form keeps the key in this browser, so never enter a live clipia_live_… key here: it is a server-side secret. See Sandbox.

GET

/v1/requests/{request_id}

Authorization

headerAuthorizationBearer <token>

API key in the Authorization header with the Bearer scheme, the primary form. Generated clients add the Bearer prefix themselves, and in the playground the field already contains it: type the key after it. The playground keeps the key in this browser, so use a test key for trials:

Authorization: Bearer <CLIPIA_API_KEY>

The same key is also accepted with the Key scheme (Authorization: Key <key>, the word Key in any case) and in the separate X-Api-Key header (the apiKeyHeader scheme); use whichever form suits you, the server tells them apart. The key is created in the developer console (clipia.ai/developer, "API keys" tab) and shown only once. Format: clipia_live_… (live), clipia_test_… (sandbox).

Sandbox / test mode. A key with the clipia_test_… prefix works in the sandbox: submit charges no credits and starts no real generation; it instantly returns status: COMPLETED with a deterministic mock result (a fixed sample asset on media.clipia.ai). The cost field shows the estimated cost, but it is not charged. Webhooks arrive through the same signed mechanism (HMAC-SHA256). This mode is meant for debugging an integration before you switch to a live key.

Path Parameters

request_id*string

ID of the generation request returned by submit.

Formatuuid

Response Body

Terminal result. For COMPLETED it contains output; for FAILED, a sanitized error.

application/json

response

request_id*string

Generation request ID.

Formatuuid

status*GenerationStatus

Generation status in the queue. CANCELED is terminal: a generation can be canceled outside the public API (for example, from the Clipia web interface); the public API has no cancel endpoint, but status can return CANCELED, so the client must treat it as final.

Value in"IN_QUEUE""IN_PROGRESS""COMPLETED""FAILED""CANCELED"

model*string

Slug of the model that ran the generation.

output*

Generation result. For images: images: [{ url, original_url? }] (url is an optimized WebP for display; original_url is the full-size PNG/JPG original for download, when available); for video: video: { url, original_url?, thumbnail_url? } (thumbnail_url is a static cover frame, not available for every model); for audio (TTS, music): audio: { url, format? } and audios: [{ url, format? }]. Music models return several track variants per request: audios contains all of them, audio is the first one (the first item of audios matches audio). All media URLs point to the media.clipia.ai CDN.

The response has no width, height or duration fields: read the dimensions and duration from the file itself. original_url and thumbnail_url are not always filled in, so treat them as optional.

cost*number

Generation cost in credits. While the request is in progress, this is the reserve; after completion, the amount actually charged. With FAILED and CANCELED, the reserve is refunded and the field equals 0.

created_at*string

Request creation time (ISO 8601).

Formatdate-time

completed_at?string

Generation completion time (ISO 8601).

Formatdate-time

error?

Error details (only when status = FAILED). Sanitized.

warnings?array<>

Warnings about request execution: the server deviated from the input parameters so that the request could complete. Currently there is one reason, audio_dropped (the video is created without sound). The field is present only when there is something to warn about, and it does not come with FAILED and CANCELED. These warnings are not yet known when the request is accepted, so the creation response does not contain them.

Itemsitems <= 20

curl -X GET "https://example.com/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b"

{  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",  "status": "COMPLETED",  "model": "nano-banana-2",  "output": {    "images": [      {        "url": "https://media.clipia.ai/works/8f3a1c7e.webp",        "original_url": "https://media.clipia.ai/works/8f3a1c7e.png"      }    ]  },  "cost": 12,  "created_at": "2026-06-01T12:00:00Z",  "completed_at": "2026-06-01T12:00:18Z"}

GET /v1/requests/:id returns the result with an output field and status 200 once the job reaches a terminal status (COMPLETED, FAILED or CANCELED). All links point to the media.clipia.ai CDN. No extra key permission is needed.

GET/v1/requests/:id

Request

Prop

Type

curl https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b \
  -H "Authorization: Bearer $CLIPIA_KEY"

Image

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "COMPLETED",
  "model": "nano-banana-2",
  "output": {
    "images": [
      {
        "url": "https://media.clipia.ai/....webp",
        "original_url": "https://media.clipia.ai/....png"
      }
    ]
  },
  "cost": 12,
  "created_at": "2026-10-09T12:00:00Z",
  "completed_at": "2026-10-09T12:00:18Z"
}

output.images is an array. url is an optimized WebP copy for display; original_url is the full-quality source file. Only the first image in the array has original_url.

Video

{
  "request_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "COMPLETED",
  "model": "seedance-2-fast-i2v",
  "output": {
    "video": {
      "url": "https://media.clipia.ai/....mp4",
      "original_url": "https://media.clipia.ai/....mp4",
      "thumbnail_url": "https://media.clipia.ai/....webp"
    }
  },
  "cost": 40,
  "created_at": "2026-10-09T12:00:00Z",
  "completed_at": "2026-10-09T12:00:42Z"
}

output.video is an object with url. The original_url and thumbnail_url (a preview frame) fields may be missing.

Audio

{
  "output": {
    "audio": { "url": "https://media.clipia.ai/....mp3", "format": "mp3" },
    "audios": [
      { "url": "https://media.clipia.ai/....mp3", "format": "mp3" },
      { "url": "https://media.clipia.ai/...-2.mp3", "format": "mp3" }
    ]
  }
}

output.audio is the first track and output.audios lists every variant: music models return several tracks per run, text-to-speech returns one. The first element of audios equals audio. format is the file format taken from the URL extension (mp3, wav) and may be absent.

No dimensions or duration

The response has no width, height or duration fields — neither live nor in the sandbox. If you need them, read them from the file itself.

Response fields

Prop

Type

Warnings

If sound was requested but the audio track did not pass the model's safety check, the server retries the generation once without sound. The request finishes as COMPLETED, and the response additionally carries a warnings array:

{
  "status": "COMPLETED",
  "output": { "video": { "url": "https://media.clipia.ai/....mp4" } },
  "warnings": [
    {
      "code": "audio_dropped",
      "parameter": "generate_audio",
      "message": "The audio track did not pass the model's safety check, so the video is generated without sound. The price of the request is unchanged."
    }
  ]
}

The cost of the request does not change. warnings is omitted when there is nothing to report, and for FAILED and CANCELED. The same array comes with the 202 response and with the request status while the silent video is still being generated. This is the only reason so far; treat an unfamiliar code as "the parameter was not applied".

Generation error codes

With status: "FAILED", the error object carries a code from a closed dictionary — it tells the client whether a retry makes sense. error.message is in English: a ready-made phrase about the reason when the server recognizes it, otherwise neutral text for the code, usually Generation failed. Please retry or contact support.; it has no names of internal systems. Credits for a FAILED job are always refunded.

`error.code`	Meaning	Retry
`generation_failed`	generic generation failure, the default	yes
`content_moderated`	the request was rejected by content moderation	pointless with the same input
`invalid_input`	the model did not accept the input: size, format, parameters	fix the request
`model_unavailable`	the model is temporarily unavailable	later
`timeout`	the generation did not finish in time	yes
`rate_limited`	the model is overloaded	after a pause
`insufficient_credits`	not enough credits at charge time	after topping up
`result_unavailable`	the result was produced but not stored or not reachable	yes
`empty_result`	the model returned an empty result	yes, or change the request
`canceled`	canceled by the user or the system	—

The failure webhook uses the same dictionary. The list may grow: treat an unknown code as generation_failed.

Response codes

HTTP	When	Body
`200`	`COMPLETED`	result with `output`
`200`	`FAILED`	`error: { code, message }`, `code` from the dictionary above, `generation_failed` by default; `cost: 0`
`200`	`CANCELED`	terminal response, `output` is usually empty, `cost: 0`
`202`	`IN_QUEUE` / `IN_PROGRESS`	`{ request_id, status }` — try again later
`400`	malformed ID	`message: invalid_request_id`
`404`	no such request	`code: not_found`, `message: request_not_found`

202 is expected

202 only appears while the job is unfinished. FAILED and CANCELED are final responses with status 200. On FAILED, the reserved credits are refunded in full. error.code is usually generation_failed (codes are lowercase snake_case), and error.message is in English: a ready-made phrase about the reason when the server recognizes it, otherwise neutral text for the code; it has no internal details. Branch on status and error.code, not on the message text.

PlaygroundCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Done (image)

Done (video)

Done (video, sound removed)

Error (credits refunded)

RequestCopy Anchor Link

ImageCopy Anchor Link

VideoCopy Anchor Link

AudioCopy Anchor Link

Response fieldsCopy Anchor Link

WarningsCopy Anchor Link

Generation error codesCopy Anchor Link

Response codesCopy Anchor Link