# Seedance 2.0

Seedance 2.0 is ByteDance's video generation model (Dreamina Seedance 2.0). Send the official ModelArk task body to `POST /v1/videos/generations`, keep the returned task ID, and read the finished video from `GET /v1/tasks/{id}`. Images, videos and audio go in `content` as URLs.

## Model IDs

| Model ID                     | Resolutions           | Notes                   |
| ---------------------------- | --------------------- | ----------------------- |
| `dreamina-seedance-2-0`      | 480p, 720p, 1080p, 4K | Full model              |
| `dreamina-seedance-2-0-fast` | 480p, 720p            | Lower price per second  |
| `dreamina-seedance-2-0-mini` | 480p, 720p            | Lowest price per second |

All three IDs accept the same parameters. See the [pricing page](https://toklab.ai/pricing) for current prices.

## Quick example

```bash
curl https://api.toklab.ai/v1/videos/generations \
  -H "Authorization: Bearer $TOKLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'
```

```python
import os
import requests

response = requests.post(
    "https://api.toklab.ai/v1/videos/generations",
    headers={"Authorization": f"Bearer {os.environ['TOKLAB_API_KEY']}"},
    json={
        "model": "dreamina-seedance-2-0",
        "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
        "generate_audio": True,
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]
```

```javascript
const response = await fetch('https://api.toklab.ai/v1/videos/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKLAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'dreamina-seedance-2-0',
    content: [{ type: 'text', text: 'A red paper boat drifts across a calm pond at sunrise, slow dolly-in' }],
    resolution: '720p',
    ratio: '16:9',
    duration: 5,
    generate_audio: true,
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();
```

```go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "strings"
    "time"
)

func main() {
    body := strings.NewReader(`{
      "model": "dreamina-seedance-2-0",
      "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5,
      "generate_audio": true
    }`)
    req, err := http.NewRequest("POST", "https://api.toklab.ai/v1/videos/generations", body)
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + os.Getenv("TOKLAB_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 60 * time.Second}
    res, err := client.Do(req)
    if err != nil { panic(err) }
    defer res.Body.Close()
    if res.StatusCode != http.StatusOK { panic(res.Status) }
    var task struct { ID string `json:"id"` }
    if err := json.NewDecoder(res.Body).Decode(&task); err != nil { panic(err) }
    fmt.Println(task.ID)
}
```

## Endpoint

```text
POST https://api.toklab.ai/v1/videos/generations
```

| Header        | Value                 |
| ------------- | --------------------- |
| Authorization | `Bearer YOUR_API_KEY` |
| Content-Type  | `application/json`    |

The body is the official ModelArk "create a video generation task" request body; this is the same endpoint every TokLab video model uses. The response is the new task (`id`, `status: "processing"`), not the finished video. Keep API keys in server-side code.

## Parameters

| Name                      | Type      | Required | Default    | Notes                                                                                                 |
| ------------------------- | --------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `model`                   | string    | Yes      | —          | One of the three model IDs above.                                                                     |
| `content`                 | object\[] | Yes      | —          | The prompt and media; see below.                                                                      |
| `resolution`              | enum      | No       | `720p`     | `480p`, `720p`, `1080p`, `4k`; the Fast and Mini IDs accept `480p` and `720p` only.                   |
| `ratio`                   | enum      | No       | `adaptive` | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`.                                              |
| `duration`                | integer   | No       | `5`        | 4–15 seconds, or `-1` to let the model choose.                                                        |
| `generate_audio`          | boolean   | No       | `true`     | Generate sound with the video.                                                                        |
| `watermark`               | boolean   | No       | `false`    | Add a watermark.                                                                                      |
| `return_last_frame`       | boolean   | No       | `false`    | Also return the final frame as an image URL.                                                          |
| `execution_expires_after` | integer   | No       | `172800`   | 3600–259200 seconds. A task still unfinished after this fails with `task_expired` and is not charged. |
| `priority`                | integer   | No       | `0`        | 0–9.                                                                                                  |
| `safety_identifier`       | string    | No       | —          | 1–64 characters identifying your end user. A hash is fine.                                            |
| `service_tier`            | enum      | No       | `default`  | Only `default`.                                                                                       |
| `content_filter`          | boolean   | No       | `true`     | TokLab extension. `false` turns off content filtering on this request.                                |

### `content` items

| Item  | Shape                                                                                   | Role                                           | Limit                                      |
| ----- | --------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
| Text  | `{"type": "text", "text": "..."}`                                                       | —                                              | One.                                       |
| Image | `{"type": "image_url", "image_url": {"url": "https://..."}, "role": "..."}`             | `first_frame`, `last_frame`, `reference_image` | Up to 9 reference images.                  |
| Video | `{"type": "video_url", "video_url": {"url": "https://..."}, "role": "reference_video"}` | `reference_video`                              | Up to 3.                                   |
| Audio | `{"type": "audio_url", "audio_url": {"url": "https://..."}, "role": "reference_audio"}` | `reference_audio`                              | Up to 3. Needs a reference image or video. |

Unknown fields are rejected. Not supported: `seed`, `callback_url` (poll the task instead), `draft` and `draft_task`, `tools`, and the 1.x-only `frames` and `camera_fixed`, as well as `output_format` and `omni_reference_task_type` (Seedance 2.5 only). Tasks cannot be cancelled or deleted.

## Modes

The mode follows from the `content` items; there is no mode parameter.

| Mode                 | `content`                                                                          |
| -------------------- | ---------------------------------------------------------------------------------- |
| Text to video        | one text item                                                                      |
| First frame          | text (optional) + one image with role `first_frame`, or one image with no role     |
| First and last frame | text (optional) + one `first_frame` image + one `last_frame` image                 |
| Multimodal reference | text + any mix of `reference_image`, `reference_video` and `reference_audio` items |

First-frame modes cannot be combined with reference items. With several images or any other media, every image needs a `role`.

### Reference example

```bash
curl https://api.toklab.ai/v1/videos/generations \
  -H "Authorization: Bearer $TOKLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'
```

Replace the example URLs with your own accessible files.

## Media inputs

This API accepts URL references only. Base64, `data:` URLs, `asset://` IDs and multipart uploads are not accepted.

Media must be public HTTP(S) URLs and meet the model's official limits:

| Media | Formats                                     | Limits                                                                                                                                                                            |
| ----- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Image | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | Smaller than 30 MB; width and height 300–6000 px; aspect ratio (width / height) 0.4–2.5; 1–9 reference images                                                                     |
| Video | MP4, MOV (H.264 or H.265)                   | 2–15 seconds each, up to 3, at most 15 seconds in total; at most 200 MB; 24–60 FPS; width and height 300–6000 px; aspect ratio 0.4–2.5; 407,696–8,295,044 pixels (width × height) |
| Audio | WAV, MP3                                    | 2–15 seconds each, up to 3, at most 15 seconds in total; needs a reference image or video; at most 15 MB                                                                          |

Reference images and videos that contain real human faces are not supported by the model.

Media is checked when the task starts, before any generation. A task whose media breaks one of these limits ends as `failed` with `invalid_request_error` and a message naming the rule, for example `The request was rejected: content reference videos must total at most 15 seconds.`, and is not charged. A file that cannot be read at that point is passed to the model, which accepts or rejects it; a failed task is not charged either way.

## Pricing dimensions

Check the [pricing page](https://toklab.ai/pricing) for current rates. Seedance 2.0 bills video tokens, the official unit:

```text
video tokens = (output seconds + reference video seconds) × width × height × 24 / 1024
```

The rate per million tokens depends on the output resolution and on whether the request includes a reference video; a request with a reference video uses a lower rate for all of its tokens. Text, image and audio inputs are not billed. At 16:9, one second is 10,044 tokens at 480p (864×496), 21,600 at 720p, 48,600 at 1080p, and 194,400 at 4K.

The charge follows the tokens the finished video reports (`output.usage.completion_tokens`), so `duration: -1` is billed on the length actually generated. Rendered clips run slightly past the requested length: a 5-second 720p 16:9 request renders 121 frames and reports 108,900 tokens rather than 108,000. View final charges in [Task logs](https://toklab.ai/tasks). Failed tasks are not charged.

## Output schema

Submission returns the new task:

```json
{"id": "task_...", "model": "dreamina-seedance-2-0", "status": "processing", "created_at": 1790321515}
```

### Get the task

```bash
curl https://api.toklab.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $TOKLAB_API_KEY"
```

Poll every 10–20 seconds until `status` is `completed` or `failed`. A network timeout while polling does not mean generation failed: keep the task ID and resume checking it. Do not create another task to check progress.

### Complete polling example

Run this after the Python submission example above.

```python
import time

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.toklab.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['TOKLAB_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        print(task["output"]["video_url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")
```

### Completed task

```json
{
  "id": "task_...",
  "model": "dreamina-seedance-2-0",
  "status": "completed",
  "created_at": 1790321515,
  "finished_at": 1790321652,
  "output": {
    "video_url": "https://static.toklab.ai/media/tasks/task_example/0.mp4",
    "last_frame_url": "https://static.toklab.ai/media/tasks/task_example/last_frame/0.jpg",
    "content": {
      "video_url": "https://static.toklab.ai/media/tasks/task_example/0.mp4",
      "last_frame_url": "https://static.toklab.ai/media/tasks/task_example/last_frame/0.jpg"
    },
    "usage": {"completion_tokens": 108900, "total_tokens": 108900},
    "seed": 42,
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "framespersecond": 24,
    "generate_audio": true,
    "draft": false,
    "output_format": "mp4",
    "service_tier": "default",
    "execution_expires_after": 172800,
    "priority": 0
  }
}
```

| Field                                                                                           | Meaning                                                         |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `id`                                                                                            | Keep this ID for later queries.                                 |
| `status`                                                                                        | `processing`, `completed` or `failed`.                          |
| `output.video_url`                                                                              | The generated video.                                            |
| `output.last_frame_url`                                                                         | The final frame, when `return_last_frame` is `true`.            |
| `output.content`                                                                                | The same URLs in the official ModelArk shape.                   |
| `output.usage.completion_tokens`                                                                | Video tokens of the finished video; the billed quantity.        |
| `output.duration`, `output.resolution`, `output.ratio`, `output.framespersecond`, `output.seed` | What was actually rendered; `seed` is the one the model picked. |
| `created_at`, `finished_at`                                                                     | Unix timestamps in seconds.                                     |
| `error`                                                                                         | `{"code", "message"}` on a failed task.                         |

Video URLs are hosted on our storage. Save the file to your own storage when you need a durable copy.

## Errors

Requests rejected before a task is created return an HTTP error with an `error` object and are not charged. A task that fails after acceptance returns HTTP 200 when queried, with `status: "failed"` and an `error` object. Output withheld by content filtering fails with `content_policy_violation`; a task that runs past `execution_expires_after` fails with `task_expired`.

See the [shared error catalog](https://toklab.ai/docs/api/errors) for codes, HTTP statuses, and retry guidance.

```json
{
  "id": "task_...",
  "model": "dreamina-seedance-2-0",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}
```

If submission itself times out, check [Task logs](https://toklab.ai/tasks) before submitting again: the first request may have been accepted.

## Tips

* Describe the subject, the action, the camera move, and the lighting in full sentences.
* Draft at 480p with a short `duration`, then render the keeper at a higher resolution.
* Chain shots with `return_last_frame`: use the returned frame as the next task's `first_frame`.

## Pricing

Every rate this model is billed at, read live from the price list billing uses. A tier applies when its condition matches, checked top to bottom.

### dreamina-seedance-2-0

| When | Video (per 1M tokens) |
| --- | --- |
| Resolution: 480p · Reference video: No | $6.996 |
| Resolution: 480p · Reference video: Yes | $4.29 |
| Resolution: 720p · Reference video: No | $6.996 |
| Resolution: 720p · Reference video: Yes | $4.29 |
| Resolution: 1080p · Reference video: No | $7.678 |
| Resolution: 1080p · Reference video: Yes | $4.697 |
| Resolution: 4k · Reference video: No | $3.993 |
| Otherwise | $2.409 |

### dreamina-seedance-2-0-fast

| When | Video (per 1M tokens) |
| --- | --- |
| Resolution: 480p · Reference video: No | $5.588 |
| Resolution: 480p · Reference video: Yes | $3.289 |
| Resolution: 720p · Reference video: No | $5.588 |
| Resolution: 720p · Reference video: Yes | $3.289 |
| Resolution: 1080p · Reference video: No | $5.588 |
| Resolution: 1080p · Reference video: Yes | $3.289 |
| Resolution: 4k · Reference video: No | $5.588 |
| Otherwise | $3.289 |

### dreamina-seedance-2-0-mini

| When | Video (per 1M tokens) |
| --- | --- |
| Resolution: 480p · Reference video: No | $3.729 |
| Resolution: 480p · Reference video: Yes | $2.233 |
| Resolution: 720p · Reference video: No | $3.729 |
| Resolution: 720p · Reference video: Yes | $2.233 |
| Resolution: 1080p · Reference video: No | $3.729 |
| Resolution: 1080p · Reference video: Yes | $2.233 |
| Resolution: 4k · Reference video: No | $3.729 |
| Otherwise | $2.233 |

## Related

* [Seedance 2.0 pricing](https://toklab.ai/pricing)
* [Download OpenAPI](https://toklab.ai/docs/seedance-2-0.openapi.json)
* [Copyable Markdown](https://toklab.ai/docs/seedance-2-0.md)