Poll tasks and download every usable output

A create response is not a finished animation

POST /animations returns HTTP 202 with a task ID and Retry-After. Persist that ID before doing anything else. A response accepted into the queue is not proof that production has completed.

Poll GET /animations/{id}. Prefer the server's Retry-After value (currently typically five seconds), add bounded backoff for transient errors, and use an overall deadline. Do not create another task just because polling is slow. The current public workflow is polling-based, not webhook-based.

States and stages

stage identifies video_generation or animation_export when relevant. progress is a value between 0 and 1, not a guaranteed time estimate. A task can advance between polls without emitting every intermediate state.

credits.quoted, credits.held, and credits.charged describe different accounting states. Do not treat the initial quoted value as the final charge or add all three together.

Partial outputs matter

A one-click task can generate a usable source video and then fail during export. Always read outputs at a terminal state, even if status is not succeeded.

Download each available asset, record the task error and missing requested formats, then report partial success accurately. Retry only the operation actually needed; an existing source video can be exported through /animation-exports without regenerating the motion.

Download securely

Each asset has id, format, mime_type, byte_size, download_url, and download_expires_at.

1. Save a task or asset ID for durable application state.
2. Use the returned signed URL to download the bytes.
3. Do not attach the API Bearer header to the signed URL or a redirected storage host.
4. Save to an application-chosen filename and verify the download completed.
5. If the link expired, call GET /assets/{asset_id} with your API key to request a fresh link.

Links are normally short-lived; use download_expires_at instead of a hard-coded lifetime. Asset lookup does not restore an asset that is no longer available under storage or retention policy.

Treat signed URLs as temporary credentials: do not publish them in logs, analytics, issue trackers, or AI conversation transcripts.

Cancellation

Use POST /animations/{id}/cancel for the owned task. Cancellation is best effort and may return an intermediate state. Poll to a terminal result; completion can win a race with cancellation.

Production already performed can remain charged. Unspent holds can be released; inspect the returned credit usage rather than promising a full refund.

Review before exporting: two-step flow

Use POST /video-generations and poll GET /video-generations/{id} to obtain the video asset. After review, create an export with source_video_asset_id, selection, and export settings at POST /animation-exports, then poll GET /animation-exports/{id}.

Quote and use an idempotency key for each new paid create operation. A source asset ID and task ID are different resources; do not swap them. The quickstart example demonstrates the simpler one-click lifecycle.