Tasks and Callbacks

Query asynchronous work, process terminal callbacks, and control Seedance tasks safely.

Query a task

GET /v1/tasks/{taskId}
Authorization: Bearer $API_KEY

All asynchronous video protocols support the common lookup path. Seedance also supports its native alias:

GET /v1/contents/generations/tasks/{taskId}

curl "http://127.0.0.1:11113/v1/tasks/9dcf8ab2-c4b7-42be-a516-597223897b99" -H "Authorization: Bearer $API_KEY"

A task is visible only to an API key for the same wallet that created it. A missing task and a task owned by another wallet both return 404 task_not_found to prevent ID probing.

Native response shapes

The query endpoint returns the latest pre-rendered response in the creation protocol. It does not wrap every provider in another generic task schema.

Creation protocol	Public task ID field	Progress or terminal fields
xAI video	`request_id`	`status`, `progress`, `video`, `error`, `usage`
Gemini Omni Interactions	`id`	`status`, `steps`, `usage`
Gemini Veo	`name`	`done`, then `response` or `error`
Seedance	`id`	`status`, `content`, `usage`, provider-compatible metadata

Every ID in a public snapshot is the platform task ID. Upstream task IDs and internal routing identity are never exposed. A callback body and a GET response for the same terminal task are byte-compatible snapshots.

Polling

Poll with a bounded interval, such as 5–10 seconds for video work, and apply backoff for transport failures. Task lookup is read-only and safe to retry.

Stop polling when the native response reaches a terminal outcome:

Protocol	Running	Success	Failure or expiration
xAI	`pending`	`done`	`failed`, `expired`
Omni	`queued`, `in_progress`	`completed`	`failed`, `incomplete`, `budget_exceeded`, `cancelled`
Veo	`done: false`	`done: true` with generated samples	`done: true` with an error or no accepted sample
Seedance	`queued`, `running`	`succeeded`	`failed`, `cancelled`, `expired`

Transient task-backend failures return 503; retain the task ID and retry instead of creating the model task again.

Terminal callbacks

Add a top-level callback_url to a supported asynchronous creation request. The platform sends the same terminal snapshot returned by GET as an HTTP POST body.

POST /your/callback?token=unguessable
Content-Type: application/json
Idempotency-Key: 9dcf8ab2-c4b7-42be-a516-597223897b99

Callback delivery is at least once. Deduplicate with the platform task ID or the outbound Idempotency-Key; that header applies only to callback delivery and does not make incoming model calls idempotent.

Delivery behavior:

Settlement and terminal persistence complete before delivery starts.
Each attempt has a 10-second timeout.
Any 2xx response is successful.
A failed first attempt is retried after approximately 10 seconds, 1 minute, and 10 minutes, for at most four attempts in total.
Delivery failure never changes task settlement; polling remains available.

Callback URL requirements

The URL must use http or https and be syntactically valid when the task is created.
Delivery refuses loopback, private, link-local, cloud metadata, and other non-public addresses after DNS resolution.
Redirects are not followed.
Until a signed callback-verification contract is published, include an unguessable token in the URL and validate it on receipt.
Return a 2xx only after durably recording or idempotently processing the task ID.

Cancel or delete a Seedance task

DELETE /v1/contents/generations/tasks/{taskId}
Authorization: Bearer $API_KEY

This control path is specific to Seedance-compatible tasks.

Current state	Behavior
`queued`	Cancels upstream work and updates the public snapshot to cancelled.
`running`	Returns `409`; running work cannot be deleted through this endpoint.
`cancelled`	Returns `409`.
`succeeded`, `failed`, or `expired`	Deletes the upstream task resource and removes the public Redis lookup snapshot.

Deleting a terminal resource does not remove platform billing records, request logs, persisted task history, or retained media evidence. A later GET can return 404 even though those operational and financial records remain.

curl -X DELETE "http://127.0.0.1:11113/v1/contents/generations/tasks/9dcf8ab2-c4b7-42be-a516-597223897b99" -H "Authorization: Bearer $API_KEY"

A successful Seedance delete returns HTTP 200 with an empty JSON object:

{}

Creation retry safety

Incoming model calls reject Idempotency-Key. If a creation POST disconnects after it may have reached the upstream, do not automatically submit the same work again. Retain any returned platform task ID; if no ID was returned, surface the ambiguous outcome to the application rather than risking a duplicate billable task.