> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a task
> POST /v1/contents/generations/tasks — submit a Seedance video generation. Native Seedance request body, forwarded verbatim.
`POST /v1/contents/generations/tasks` submits a video generation task. The request body is **shape-identical to the native Seedance video API** — Aurous forwards it to the provider verbatim, including any parameters not listed here, so future provider fields keep working. A credit ceiling is held on your team balance and reported on the `Aurous-Credits-Held` response header.
* **Scope:** `write`
* **Auth:** `X-Api-Key: al_live_…` or `Authorization: Bearer al_live_…`
* **Content-Type:** `application/json`
* **Max body size:** 64 MB (base64 data-URIs are accepted inline)
```bash cURL theme={null}
curl https://api.aurous-labs.com/v1/contents/generations/tasks \
-H "X-Api-Key: al_live_…" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"content": [{"type": "text", "text": "A kitten yawns at the camera"}],
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}'
```
## Response
**HTTP 200** — provider parity (not `201`). The body is exactly the task id, and nothing else:
```json theme={null}
{ "id": "vid_01J9Z3K7Q0XY2ABCDEFGHJKMNP" }
```
Billing information rides on **headers only** — the body is never modified:
| Header | Meaning |
| --------------------- | ------------------------------------------------------------------------------ |
| `Aurous-Credits-Held` | Credit ceiling reserved for this task (released or settled at terminal state). |
| `Aurous-Request-Id` | Correlation id for support. |
Poll the returned id at [`GET /v1/contents/generations/tasks/{id}`](/api-reference/seedance/retrieve-task) until it reaches a terminal state.
## `model`
The `model` field accepts a Seedance model id or one of its aliases. Aliases are the friendly names; both resolve to the same model.
| Alias | Resolutions | Notes |
| ------------------- | --------------------- | ------------------------------------------- |
| `seedance-2.0` | 480p, 720p, 1080p, 4k | Full-resolution tier. 4k is this tier only. |
| `seedance-2.0-fast` | 480p, 720p | Faster, lower cost. No 1080p/4k. |
| `seedance-2.0-mini` | 480p, 720p | Lowest cost. No 1080p/4k. |
The full provider model ids (e.g. `dreamina-seedance-2-0-260128`) are also accepted verbatim, so copy-pasted provider tutorial code runs unchanged. See [Models & pricing](/api-reference/seedance/models-and-pricing) for live rates and capabilities via [`GET /v1/models`](/api-reference/openapi#tag/models).
An unknown model, an endpoint-style id, or a missing/empty `model` returns **`404 model_not_found`**.
List available models with [`GET /v1/models`](/api-reference/openapi#tag/models)
and pass a model id or alias — never an endpoint id.
## `content[]`
`content` is a non-empty array of items. Each item is one of four types, and image / video / audio items carry a `role`:
| Item `type` | `role` values | URL forms accepted |
| ----------- | ---------------------------------------------- | ------------------------------------------ |
| `text` | — | plain prompt text |
| `image_url` | `first_frame`, `last_frame`, `reference_image` | `https://…` URL **or** base64 data-URI |
| `video_url` | `reference_video` | `https://…` URL only (no base64 for video) |
| `audio_url` | `reference_audio` | `https://…` URL **or** base64 data-URI |
```json theme={null}
{
"model": "seedance-2.0",
"content": [
{ "type": "text", "text": "She turns toward the camera and smiles" },
{ "type": "image_url", "role": "first_frame", "image_url": { "url": "https://…/frame.jpg" } }
]
}
```
### Generation modes
Beyond plain **text-to-video** (a single `text` item), visual inputs select one of three **mutually exclusive** modes:
1. **First-frame** — one `image_url` with `role: first_frame`. Animate forward from a starting frame.
2. **First + last frame** — a `first_frame` plus a `last_frame` image. Interpolate between two frames.
3. **Multimodal reference** — up to **9 reference images**, **3 reference videos** (each 2–15 s, ≤15 s total), and **3 reference audio** clips (≤15 s total). Audio never rides alone — it must accompany another input.
That is the **"up to 12 reference files"** budget: 9 images + 3 videos + up to 3 audio refs.
Aurous does **not** re-validate per-model rules — durations, resolution
support, role combinations, and mode exclusivity are enforced by the provider,
which returns its `400` verbatim. Duplicating those rules here would only drift
from them. We read (never rewrite) `resolution`, `duration`, `ratio`, and whether
any `video_url` item is present, purely to price the credit hold.
### Input constraints
| Input | Limit |
| ------------------ | ------------- |
| Image file | ≤ 30 MB each |
| Video file | ≤ 200 MB each |
| Audio file | ≤ 15 MB each |
| Whole request body | ≤ 64 MB |
Reference videos must be passed as `https://` URLs — base64 inline is accepted for images and audio, but not for video. The provider enforces format, dimension, frame-rate, and duration rules on each file and returns a verbatim error if one is rejected; see [Errors](#errors).
### References with people
Reference images and videos may contain real people. When you pass a person or face reference, the task is **accepted immediately** — you get a `vid_…` handle right away — and the reference is prepared automatically before generation begins. A task with such a reference may sit in `queued` a little longer while that preparation completes, then proceeds through `running` to `succeeded` like any other task. No extra fields or steps are required on your side; poll the task id as usual. If a reference ultimately can't be used, the task settles `failed` with a plain reason.
For identity-consistent video that reuses the **same** person across many renders, the managed [characters](/api-reference/characters/create-character) path on [`POST /v1/videos`](/api-reference/videos/create-video) remains the richer option.
## Parameters
All parameters below are optional; defaults are the Seedance defaults. Per-model support is noted where it differs.
| Parameter | Type | Default | Notes |
| ------------------------- | --------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolution` | `"480p" \| "720p" \| "1080p" \| "4k"` | `"720p"` | **1080p and 4k are `seedance-2.0` only** (4k is 10-bit HEVC). |
| `ratio` | `"16:9" \| "4:3" \| "1:1" \| "3:4" \| "9:16" \| "21:9" \| "adaptive"` | `"adaptive"` | Output aspect ratio. |
| `duration` | integer `4`–`15`, or `-1` | `5` | Output length in seconds. `-1` lets the model pick. `frames` is not supported on this family. |
| `generate_audio` | boolean | `true` | Generate a mono audio track. Does not change the price. |
| `watermark` | boolean | `false` | Burn a watermark into the output. |
| `callback_url` | string | — | HTTPS URL that receives an **unsigned** `{ event, data }` completion callback (a prompt to fetch status). See [Differences → Callbacks](/api-reference/seedance/differences#callbacks). |
| `return_last_frame` | boolean | `false` | Also return the final frame as a PNG (an Aurous streaming URL, valid \~24 h). |
| `execution_expires_after` | integer seconds `3600`–`259200` | `172800` (48 h) | How long the task may sit before the provider expires it. |
| `priority` | integer `0`–`9` | — | Reorders your own queued tasks. `seedance-2.0` family only. |
| `safety_identifier` | string ≤ 64 chars | — | Your per-end-user tag. Namespaced per team upstream, **echoed back unchanged** on retrieve. See [Differences](/api-reference/seedance/differences#safety-identifier). |
`seed` and `camera_fixed` are **not supported** by the Seedance 2.0 family. `service_tier` is fixed to the online tier for this family. Unknown parameters are forwarded to the provider untouched.
## Errors
Non-2xx responses fall into three classes. Knowing which class you are in tells you whether to fix the request, retry, or contact support.
### 1. Aurous pre-dispatch gates
Conditions Aurous checks **before** the request reaches the provider. These use Aurous **snake\_case** codes inside the standard envelope `{"error":{ "type", "code", "message", "param", "doc_url", "request_id" }}`.
| Code | HTTP | When |
| ------------------------------------------------------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`model_not_found`](/errors#model_not_found) | 404 | Unknown model, an endpoint-style id, or a **missing/empty** `model` field. |
| [`invalid_request`](/errors#invalid_request) | 400 | Malformed body, empty/invalid `content[]`, unsupported content type, or an unsupported resolution for the resolved model. |
| [`balance_too_low`](/errors#balance_too_low) | 402 | Team balance is below the required credit ceiling (the message names the ceiling). |
| [`insufficient_scope`](/errors#insufficient_scope) | 403 | The API key lacks the `write` scope. |
| [`payload_too_large`](/errors#payload_too_large) | 413 | Request body exceeds 64 MB. |
| [`too_many_requests`](/errors#too_many_requests) | 429 | Per-team request rate exceeded. `Retry-After` echoed. |
| [`concurrency_limit_exceeded`](/errors#concurrency_limit_exceeded) | 429 | Too many non-terminal raw tasks in flight for your team (default cap **5**). Count-based — **no** `Retry-After`; retry once an in-flight task finishes, or cancel a queued/pending task. |
| [`idempotency_key_in_use`](/errors#idempotency_key_in_use) | 409 | Same `Idempotency-Key` reused with a different body. |
If your code switches on the provider's PascalCase error codes
(`InvalidParameter`, `MissingParameter`, …), you will meet these Aurous
snake\_case codes **first**, because they fire before the provider is called.
The envelope is a strict superset of the provider's `{"error":{"code","message"}}`.
See [Differences → Error envelope](/api-reference/seedance/differences#error-envelope).
### 2. Provider request-faults (forwarded verbatim)
Problems with the request that only the provider can detect — e.g. `InvalidParameter`, `MissingParameter`, and output content checks (`Output*SensitiveContentDetected`, including their `.PolicyViolation` variants). These are returned with the **provider's exact status and body**. This is the point of the raw surface: you get the provider's own validation, unmodified.
Input references containing real people are the exception: rather than surfacing as an error, they are prepared automatically and the task continues (see [References with people](#references-with-people)).
### 3. Account / infrastructure faults (remapped)
Faults on the Aurous side of the connection that you cannot fix and that would leak our account posture are remapped:
| Result | HTTP | Meaning |
| ---------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
| [`provider_unavailable`](/errors#provider_unavailable) | 503 | A known upstream/account condition. `Retry-After: 30` echoed. Retry with backoff. |
| [`provider_unknown_error`](/errors#provider_unknown_error) | 502 | An upstream error our mapping table does not yet recognize. Engineering is alerted; treat as transient. |
See the [Errors](/errors) catalog for the full envelope, the `request_id` support workflow, and retry guidance.