API docs · Tasks
Async tasks & statuses
State machine, failure codes and request fields.
POST /v1/videos/generations returns 202 with the task object as soon as validation passes. Failures after acceptance never change the 202 already returned; they appear only in the task object's error field. When the account or key reaches its limit on tasks in progress at once, the API returns 429 rate_limited (Retry-After: 10).
Task statuses
| status | Description |
|---|---|
| Queued | Accepted and waiting to be processed |
| Preparing | Preparing input assets on the processing channel |
| Generating | Generating |
| Recovering | The current channel ran into a problem and the platform is resuming on another channel; the task ID stays the same |
| Reconciling | Verifying the final upstream result to avoid duplicate generation or duplicate charges |
| Finalizing | Saving the result and settling the charge |
| Succeeded | Succeeded; result contains the video URL. Terminal |
| Failed | Failed; error contains the failure code and message. Terminal |
Only succeeded and failed are terminal. Do not rely on the order of intermediate statuses: the platform may skip some, or go from running back to recovering during recovery.
Failure codes
| error.code | What to do |
|---|---|
no_available_channel | No processing route is currently available on this site. Resubmit later with a new idempotency key. |
upstream_status_unknown | The platform could not confirm the generation result. Check the charge breakdown, then resubmit with a new idempotency key. |
task_deadline_exceeded | The task did not finish within the processing time limit. Reduce the duration or resolution and resubmit. |
content_rejected | The prompt or generated content failed content moderation. Revise it before resubmitting; the same content will fail again. |
asset_rejected | An input asset failed moderation or format checks. Replace it and try again. |
invalid_parameter | Unsupported parameter combination. Check resolution, ratio, duration and input counts against the model capabilities. |
account_suspended | Your account has been suspended. Contact our operations team. |
result_unavailable | The generated result could not be retrieved. Resubmit the task. |
internal_error | Internal platform error. Try again later; if it keeps happening, contact us with the request ID. |
Request fields
| Field | Description |
|---|---|
model | Required. Model ID; must be in the key's allowlist and enabled for your account (otherwise 403 permission_denied) |
prompt | Prompt; required for text-to-video without any inputs. See the capabilities for the maximum length |
inputs | Array of input assets { type, asset_id, role }, up to 20; first and last frames cannot be combined with reference roles |
duration | Required. Duration in seconds; where the capabilities allow it, pass -1 to let the model decide |
resolution / ratio | Required. Resolution and aspect ratio; see the capabilities for allowed values |
max_budget | Optional per-task budget cap (amount string); returns 402 quota_exceeded if the reserve ceiling exceeds it |
callback_url | Optional; receives a webhook when the task reaches a terminal status |
metadata | Optional string key-value pairs, returned as-is; up to 32 entries, keys ≤ 64 characters, values ≤ 512 characters, 8 KiB in total |
provider_options | Optional model-specific parameters (flat key-value pairs, such as seed); see the capabilities for available keys and types. Values are booleans, integers or strings of up to 32 characters |
fallback_models | Optional cross-model fallback: if no channel can run the requested model, these models are tried in order (up to 3). Billed at the model actually used; the reserve covers the most expensive candidate; model_used in the response names the model that ran |
allow_fallback | Optional; true uses the platform default fallback chain for the model (default_fallbacks in the model list). Omit or false for no fallback |
Result fields
Once a task succeeds, result contains video_url, last_frame_url, url_expires_at and retained_until; see Result retention for how long they stay valid. If your account is set up to return the upstream URL, it also includes upstream_video_url and upstream_url_expires_at (the upstream URL is usually valid for 24 hours after generation completes).
Reference image + reference audio
POST https://cn-api.aitoken.tools/v1/videos/generations
{
"model": "seedance-2.0-standard",
"prompt": "The subject looks into the camera and smiles, background blurred",
"inputs": [
{ "type": "image", "asset_id": "asset_xxx", "role": "reference_image" },
{ "type": "audio", "asset_id": "asset_yyy", "role": "reference_audio" }
],
"duration": 8,
"resolution": "1080p",
"ratio": "9:16",
"max_budget": "30.000000",
"callback_url": "https://example.com/hooks/video",
"metadata": { "order_id": "A-1001" }
}