Skip to main content
APIPod image and video generation is asynchronous. A create request returns quickly with a public task_id; generation continues after that HTTP request finishes.

​
Lifecycle

An internal finalization stage is exposed as processing, so clients never need to handle a separate finalizing state.

​
All-in-one Seedance family names

seedance-2.5, seedance-2.0, seedance-2.0-fast, and seedance-2.0-mini are all-in-one model IDs: one model covers every scenario, and the scenario is inferred from the request materials: Pin the interpretation of image_urls with the top-level role field: first_last_frame treats 1–2 images as the first frame plus an optional last frame, and reference_images treats all images as reference images regardless of count. first_last_frame cannot be combined with reference videos or audios. Scenario-specific model IDs (seedance-2.5-i2v, seedance-2.5-r2v, …) remain available when you want the scenario pinned by the model itself. Reference video duration is billed together with the output duration on all 2.x models.

​
Polling endpoints

Status queries are scoped to the authenticated account. A task from another account is not returned.

​
Polling strategy

  • Start with a short delay, then use bounded exponential backoff with jitter.
  • Stop immediately on a terminal status.
  • Honor Retry-After when the API supplies it.
  • Persist the task_id before beginning background polling.
  • Set an application deadline appropriate for the selected model; do not assume every model completes within the same duration.
  • Treat an empty result as not yet deliverable even if an upstream operation has finished; APIPod keeps finalizing media before exposing it as completed.

​
Image and video error fields

Image status responses can expose error_code and error_message in data. Video status responses expose the client-safe message as error. Webhooks use error and optional error_code. Always branch on status before reading result or error fields.

​
Usage and cost on completion

Both status endpoints and completion webhooks attach a usage object when a task reaches completed, containing the final amount charged (usage.cost, in USD) plus token counts when the upstream provider reports them. It is absent for non-terminal and failed tasks, so record cost from the terminal response or callback.

Use webhooks

Receive terminal task results without continuous polling.

Handle errors

Normalize HTTP, synchronous, and asynchronous failures.