Skip to main content
Generation is asynchronous. You submit a job, receive an id immediately, then poll until the job reaches a terminal state.

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 as expires_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_at the files are deleted: expired is true and the response returns no URLs (images is empty, and video_url and audio_url are 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 on type 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 stable restriction_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: