Retrieve a task

GET /v1/contents/generations/tasks/{id} returns the full task object. Poll it until status reaches a terminal state. The response body is shape-identical to the native Seedance task object — the same fields, with task ids as Aurous-native vid_… identifiers and two fields normalized back to what you sent (see Normalization).

Scope: read
Auth: X-Api-Key: al_live_… or Authorization: Bearer al_live_…

cURL

curl https://api.aurous-labs.com/v1/contents/generations/tasks/vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP \
  -H "X-Api-Key: al_live_…"

Response

{
  "id": "vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP",
  "model": "seedance-2.0",
  "status": "succeeded",
  "error": null,
  "created_at": 1731948000,
  "updated_at": 1731948042,
  "content": {
    "video_url": "https://api.aurous-labs.com/v1/contents/generations/tasks/vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP/output?token=…",
    "last_frame_url": "https://api.aurous-labs.com/v1/contents/generations/tasks/vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP/output/last_frame?token=…"
  },
  "seed": 123456,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "generate_audio": true,
  "safety_identifier": "your-original-value",
  "priority": 0,
  "draft": false,
  "draft_task_id": null,
  "service_tier": "online",
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 108000,
    "total_tokens": 108000
  }
}

Fields

Field	Type	Notes
`id`	string	The `vid_…` task id.
`model`	string	The canonical model id you targeted (normalized).
`status`	enum	See Status.
`error`	object \| null	`{ "code", "message" }` on a failed task; `null` otherwise.
`created_at` / `updated_at`	integer	Unix seconds.
`content`	object	`{ "video_url", "last_frame_url"? }` on success. Both are Aurous streaming URLs — the bytes are proxied through Aurous, so they point at Aurous endpoints (`…/v1/contents/generations/tasks/{id}/output[/last_frame]?token=…`), never an upstream storage host. Valid ~24 h — download what you want to keep. `last_frame_url` present only if you passed `return_last_frame: true`.
`seed`	integer	Seed the model selected. Returned only — `seed` is not a settable input on the 2.0 family (see Create a task → parameters).
`resolution`	string	Output resolution.
`ratio`	string	Output aspect ratio.
`duration` or `frames`	integer	The delivered length. One of the two is present.
`framespersecond`	integer	Output frame rate (24 for this family).
`generate_audio`	boolean	Whether an audio track was generated.
`safety_identifier`	string	Your original value, echoed back unchanged (see Normalization).
`priority`	integer	Queue priority you set.
`draft` / `draft_task_id`	boolean / string	Draft-mode fields (not used by the 2.0 family).
`service_tier`	string	`online` for this family.
`execution_expires_after`	integer	Seconds the task may sit before expiring.
`usage`	object	`{ "completion_tokens", "total_tokens" }`. This is the billing basis — see Billing. For video models input tokens are always 0, so `total_tokens == completion_tokens`.

Status

`status`	Terminal?	Meaning
`queued`	no	Accepted, waiting for a worker.
`running`	no	Generating.
`succeeded`	yes	Done. `content.video_url` is populated.
`failed`	yes	Generation failed. `error` carries the reason. Charged 0.
`expired`	yes	Task sat past `execution_expires_after` and was expired by the provider. Charged 0.
`cancelled`	yes	You cancelled it while queued. Charged 0 (full refund).

Poll until status is one of the four terminal values. A comfortable interval is ~10–15 seconds; a queued task may sit for a while (up to your execution_expires_after), so back off rather than hammering. A task whose content includes a person reference can spend a little extra time in queued while that reference is prepared — no different to poll for.

Billing

Billing on the raw surface is hold-then-settle, and rides on headers — the body is never modified.

On create, a credit ceiling is held and reported on Aurous-Credits-Held.
At success, the charge settles on usage.completion_tokens — the actual metered tokens the provider reports. The settled amount appears on the Aurous-Credits-Charged header of a terminal retrieve, and as a line item in GET /v1/usage.
You are charged only on success. failed, expired, and (queued) cancelled tasks charge 0 and release the hold in full.

Header (terminal retrieve)	Meaning
`Aurous-Credits-Charged`	The exact credits deducted (present once `status: succeeded`).
`Aurous-Request-Id`	Correlation id for support.

When you pass an explicit duration, a fixed ratio, and no reference video, the held ceiling equals the final charge exactly — there is nothing to reconcile. For a video-input task the hold assumes the maximum 15 s of reference footage (we never fetch your clip to measure it), so the held ceiling is an upper bound and the settled charge is typically lower. See Models & pricing for the full math.

Normalization

Two fields are restored to what you sent, so the response reflects your own inputs:

model — returned as the canonical model id/alias you targeted.
safety_identifier — returned as your original value (it is namespaced per team upstream for abuse attribution, then restored on the way out).

Everything else in the task object is the provider’s, verbatim.

Read-through and retention

Non-terminal tasks are read live from the provider on each retrieve, so you always see the current status.
Terminal tasks are served from Aurous’s stored copy.

Retention delta. Aurous keeps your task records queryable past the provider’s 7-day history purge — a superset of the native API. The video_url and last_frame_url are Aurous streaming URLs (the bytes are proxied through Aurous), and they still expire ~24 hours after the video was generated, so the record remains readable but its media links go stale. Download what you want to keep.

Errors

Code	HTTP	When
`resource_not_found`	404	Unknown id, another team’s task, or a deleted task. Indistinguishable by design (no cross-team leakage).
`insufficient_scope`	403	The API key lacks the `read` scope.

A vid_… id that belongs to a non-raw generation is not addressable here and returns 404 — the raw surface and the /v1/videos surface never cross-resolve ids.

Get started

Guides

Concepts

API Reference

Resources

Response

Fields

Status

Billing

Normalization

Read-through and retention

Errors

​Response

​Fields

​Status

​Billing

​Normalization

​Read-through and retention

​Errors

Response

Fields

Status

Billing

Normalization

Read-through and retention

Errors