Lifecycle
A job moves through these statuses:succeeded, failed, and timeout are terminal — stop polling once you see
one. On succeeded, the result is available on the status response (an images
array for image jobs, a video_url for video jobs, an audio_url for music and
sound-effect jobs).
Video jobs also report video_codec. Most outputs are H.264, but a few
high-definition tiers deliver H.265 (HEVC), which does not play in every browser —
see video output format.
Timing and prompt
Image, video and audio status responses report three times:started_at minus created_at is the time spent waiting in the queue, and
completed_at minus started_at is the generation time. Status responses also
return the job’s prompt exactly as you submitted it.
Create, then poll
Image, video, and audio jobs are all created at per-model endpoints (POST /v1/images/{model-name}, POST /v1/videos/{model-name},
POST /v1/audios/{model-name}), then polled at the matching status endpoint.
Job ids are opaque — treat them as strings and poll each at its own type’s status
endpoint (
/v1/images/{id}, /v1/videos/{id}, or /v1/audios/{id}). A reasonable
polling interval is every few seconds — images and sound effects typically finish in
seconds, music and video in a few minutes.Output retention
Generated files are kept for 24 hours after the job is created. A succeeded job’s status response gives that time asexpires_at, and expired says whether it
has passed.
- Download URLs are signed, and each is valid for at least 6 hours. Call the status
endpoint again for fresh URLs at any time before
expires_at. - After
expires_atthe files are deleted:expiredistrueand the response returns no URLs (imagesis empty, andvideo_urlandaudio_urlare absent). - To keep an output, download it before
expires_at, or open the request in the Requests tab of the developer console and choose Save to assets.
Errors
Errors share one envelope so you can branch ontype and code (the exception is
content moderation blocks, which use a flatter shape — see below):
Content moderation blocks
When a prompt or input image is blocked by content moderation, the request fails with 400 and a response carrying a stablerestriction_reason you can branch
on. The block is about the request’s content, not your account or key — reword the
prompt or change the input media and retry: