> For the complete documentation index, see [llms.txt](https://bountyv.gitbook.io/vdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bountyv.gitbook.io/vdocs/frontier-passthrough/frontier-seedance.md).

# Seedance 2.0

BytePlus Dreamina Seedance 2.0 with its **full native multimodal reference surface** — images, motion reference videos, and reference audio. The video and audio roles aren't reachable anywhere else on the public API.

```
POST /api/v1/frontier/seedance
GET  /api/v1/frontier/seedance/{id}
```

Asynchronous: submit returns a `generation_id` immediately and charges up front; poll until the clip is ready. A failure observed on poll refunds in full.

## Authentication

```
Authorization: Bearer sk_live_...
```

## Request

**Content-Type:** `application/json`

| Field                                   | Type      | Required | Default          | Description                                                                                                |
| --------------------------------------- | --------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `prompt`                                | string    | ✅        | —                | The scene. References are addressed positionally as "Image 1", "Video 1", "Audio 1", … in submission order |
| `image_urls`                            | string\[] | —        | —                | Up to 9 reference images                                                                                   |
| `video_urls`                            | string\[] | —        | —                | Up to 3 motion reference videos                                                                            |
| `audio_urls`                            | string\[] | —        | —                | Up to 3 reference audio tracks (music or voice bed)                                                        |
| `image_url` / `video_url` / `audio_url` | string    | —        | —                | Singular forms of the above                                                                                |
| `tier`                                  | string    | —        | `"pro"`          | `"pro"` \| `"fast"` \| `"mini"` — see [Tiers](#tiers)                                                      |
| `ratio`                                 | string    | —        | provider default | `"9:16"`, `"16:9"`, `"1:1"`, …                                                                             |
| `duration`                              | integer   | —        | provider default | Clip length in seconds                                                                                     |
| `generate_audio`                        | boolean   | —        | `true`           | Let the model generate an audio track                                                                      |
| `watermark`                             | boolean   | —        | `false`          | Provider watermark                                                                                         |

### Tiers

`tier` selects which Seedance 2.0 model renders the clip. All three take the same request body and the same reference budget; they differ in render time and in what a long clip costs.

| Tier            | Use it for                                                             |
| --------------- | ---------------------------------------------------------------------- |
| `pro` (default) | Best fidelity. A render typically takes a couple of minutes            |
| `fast`          | Same surface, quicker, and materially cheaper on longer clips          |
| `mini`          | The lightest and cheapest tier. Caps at 720p; best value on long clips |

An unrecognised `tier` returns `400` with the accepted values in `supported_tiers`; it is **not** silently treated as `pro`, because the tier determines what the call costs. Case is ignored, so `"Pro"` is fine.

`mini` runs on a smaller capacity pool than `pro` and `fast`. If you submit a burst of renders concurrently on `mini`, some may come back `502` — nothing is charged for those, so retry them or spread the submissions out.

### References must be public URLs

Unlike the image routes, Seedance references must be **public `https://` URLs** — ModelArk fetches them itself, so a `data:` URL or base64 blob is rejected with `400`. Use [signed uploads](/vdocs/account/uploads-sign.md) to host your own files first.

Caps: 9 images, 3 videos, 3 audio, and **12 reference files in total** across all three. Each is checked before anything is charged.

## Response — submit

```json
{
  "generation_id": "gJ8nP3kQ2m",
  "status": "pending",
  "poll_url": "/api/v1/frontier/seedance/gJ8nP3kQ2m",
  "model": "Seedance 2.0",
  "tier": "pro",
  "reference_images": 2,
  "reference_videos": 1,
  "reference_audio": 0,
  "charged_cents": 89,
  "balance_cents": 4711
}
```

## Polling

```
GET /api/v1/frontier/seedance/{id}
```

| Response                                                                | Meaning                                       |
| ----------------------------------------------------------------------- | --------------------------------------------- |
| `{ "status": "pending" }`                                               | Still rendering — poll again                  |
| `{ "status": "completed", "video": "https://…", "generation_id": "…" }` | Done. `video` is a time-limited signed URL    |
| `{ "status": "failed", "error": "…", "refunded_cents": 89 }`            | Failed; the up-front charge has been refunded |

A `failed` result arrives with HTTP `200` — it's a render outcome, not a transport error. Poll every few seconds; `pro` renders typically take a couple of minutes.

## Example

Drive a scene with a motion reference video and a music bed:

```bash
curl -X POST https://substance-api.com/api/v1/frontier/seedance \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character in Image 1 performs the routine in Video 1, timed to Audio 1",
    "image_urls": ["https://example.com/character.png"],
    "video_urls": ["https://example.com/motion.mp4"],
    "audio_urls": ["https://example.com/track.mp3"],
    "tier": "pro",
    "ratio": "9:16",
    "duration": 6
  }'
```

Then poll:

```bash
curl https://substance-api.com/api/v1/frontier/seedance/gJ8nP3kQ2m \
  -H "Authorization: Bearer sk_live_..."
```

## Errors

| Status | Meaning                                                                                                                                                                                                               |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing `prompt`, an unknown `tier` (`supported_tiers` included), a non-https reference, or a cap exceeded (`max_reference_images` / `max_reference_videos` / `max_reference_audio` / `max_reference_files` included) |
| `402`  | Balance below the call price                                                                                                                                                                                          |
| `403`  | Your account doesn't have the `video` product enabled, or the job belongs to another account (on poll)                                                                                                                |
| `404`  | Unknown `generation_id` (on poll)                                                                                                                                                                                     |
| `502`  | ModelArk rejected the submission. **Nothing is charged** — the charge only lands after a successful submit                                                                                                            |
| `503`  | The pipeline is disabled                                                                                                                                                                                              |

## Pricing

From **$1.59** per clip, charged on submit and refunded in full if the render fails.

Seedance bills per output **second** upstream (\~$0.15/s at 720p on `pro`), so the price scales with `duration` rather than staying flat — a 15-second `pro` clip costs several times a 4-second one to produce. Indicative charges:

| Tier   | 4s    | 5s    | 10s   | 15s   |
| ------ | ----- | ----- | ----- | ----- |
| `pro`  | $1.59 | $1.59 | $3.06 | $4.60 |
| `fast` | $1.59 | $1.59 | $2.44 | $3.66 |
| `mini` | $1.59 | $1.59 | $1.59 | $2.28 |

Tier changes what a long clip costs, not the short ones — everything up to about 5 seconds sits on the $1.59 floor whichever tier you pick, so there's no saving in dropping to `mini` for a short clip. Past that they separate: `mini` holds the floor all the way to 10 seconds and is roughly half of `pro` at 15.

The exact amount is always returned as `charged_cents` on submit, and a `402` names the `required_cents` before anything is submitted.

Bills on `images.img2video.seedance`. See [Credits & pricing](/vdocs/account/credits.md).

SFW only — see [Frontier Passthrough → Content policy](/vdocs/frontier-passthrough/frontier-overview.md#content-policy).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bountyv.gitbook.io/vdocs/frontier-passthrough/frontier-seedance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.