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.

​
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.