Accepted is not completed
POST /api/v1/tasks returns HTTP 202 after acceptance. Its receipt contains taskId, status, statusUrl, pollAfterSeconds and replayed. Poll GET /api/v1/tasks/{taskId} or call get_task until terminal is true.
Single and batch results
| Field | Meaning |
|---|---|
operation | Business operation selected at submission |
status | Current aggregate state |
terminal | Whether all media items have finished |
progress | Total, processing, completed and failed item counts |
items | Individual media task states, assets and actionable errors |
assets | Ready successful files available for download or reuse |
webhook | Delivery status, stable event ID and attempt count |
Direction animation and sound effects can contain multiple media items. Batch NPC currently uses one media generation for the whole cast; NPC count and media-item count differ.
Before a terminal callback event is created, webhook.status and webhook.eventId are null, including tasks without a callback. Delivery states are pending, delivered and failed. These fields describe callback delivery, not generation progress.
Terminal states
A complete success is completed. A batch with both successes and failures is partially_completed. A complete failure is failed or the reported parameter failure state. Never infer completion from elapsed time or from only one finished batch item.
Recovery
When a response is lost, recover the original request with the same idempotency key. When polling fails temporarily, keep the same task ID and back off. A terminal failure can be reviewed for a deliberate new request; an unknown provider submission must first be reconciled by the existing workflow.