# Seedance 2.0 Fast API（TokenRa）

模型 ID：`seedance-2-0-fast`
获取 API Key：https://tokenra.io/sign-up?utm_source=llms-agent&utm_medium=model-llms
更新日期：2026-10-30

> Seedance 2.0 Fast 是字节跳动 Seedance 2.0 系列中价格更低的 Fast 版本，请求方式与 Seedance 2.0 Pro 相同：先提交任务，再轮询直到拿到视频地址。

- 厂商：字节跳动
- 类型：视频模型
- 输入：文本、图片
- 输出：视频（可带音频）
- 调用方式：异步任务

## 价格

以下为本文件最后更新时 TokenRa 控制台的价格，单位美元，默认分组。请以实时价格为准：https://tokenra.io/pricing（JSON：https://tokenra.io/api/pricing）。

- `seedance-2-0-fast`：$5.15 / 100 万 token，输入和输出同价（视频任务按实际消耗的 token 计费）

## 能力与接口

视频生成是异步的：先创建任务，再轮询结果。实测 4 秒 480p 的视频需要 3.5–4 分钟。

- `POST https://tokenra.io/v1/video/generations`：创建任务，立即返回 `task_id`。
- `GET https://tokenra.io/v1/video/generations/{task_id}`：查询任务；`data.status` 为 `SUCCESS` 时，视频链接在 `data.result_url`。

## 调用示例

先把环境变量 `TOKENRA_API_KEY` 设为你的 API Key。文档页提供同一示例的 Python、JavaScript 和 Java 版本。

```bash
# 1. 创建任务，响应里包含 task_id
curl https://tokenra.io/v1/video/generations \
  -H "Authorization: Bearer $TOKENRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0-fast",
    "prompt": "雨夜霓虹街道上漂流的纸船，电影感特写镜头",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    }
  }'

# 2. 每 10–15 秒查询一次，直到 data.status 为 SUCCESS 或 FAILURE
curl https://tokenra.io/v1/video/generations/TASK_ID \
  -H "Authorization: Bearer $TOKENRA_API_KEY"
```

## 生成场景

以下三种请求结构均已于 2026-10-23 实测生成成功。

### A. 文生视频

只传提示词，输出设置写在 `metadata` 里。

**POST /v1/video/generations**

```json
{
  "model": "seedance-2-0-fast",
  "prompt": "雨夜霓虹街道上漂流的纸船，电影感特写镜头",
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }
}
```

### B. 图生视频（首帧）

把图片链接放在 `images` 数组中，单张图片作为视频首帧。

**POST /v1/video/generations**

```json
{
  "model": "seedance-2-0-fast",
  "prompt": "画面中的女孩转身微笑",
  "images": ["https://example.com/first-frame.png"],
  "metadata": {"resolution": "720p", "duration": 5}
}
```

### C. 多图参考

需要给图片指定角色时，在 `metadata.content` 中按火山方舟格式传入素材，提示词会自动作为文本项加入。

**POST /v1/video/generations**

```json
{
  "model": "seedance-2-0-fast",
  "prompt": "图一中的角色走进图二的房间",
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/character.png"},
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/room.png"},
        "role": "reference_image"
      }
    ]
  }
}
```

## 请求参数

**输出设置必须放在 metadata 里**

Seedance 2.0 会忽略顶层的 `resolution`、`ratio`、`duration`。2026-10-23 实测：顶层传 `ratio: "9:16"`、`duration: 4`，生成的仍是 16:9、5 秒的视频，而 `metadata.resolution` 生效；同样的值放进 `metadata` 后，生成的是 9:16、4 秒的视频。

### 顶层字段

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `seedance-2-0-fast`。`seedance-2-0-pro`、`seedance-2-0-mini` 的参数与它相同。 |
| `prompt` | string | 是 | 画面、动作与镜头描述。 |
| `images` | string[] | 否 | 图片链接数组，只能是字符串；需要指定角色时改用 `metadata.content`。 |
| `metadata` | object | 否 | 输出设置与火山方舟原生字段，见下表。 |

### metadata 字段

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `resolution` | string | 否 | `480p`、`720p` 或 `1080p`，实测 `480p`。同时决定计费档位。 |
| `ratio` | string | 否 | `16:9`、`9:16`、`4:3`、`3:4`、`1:1`、`21:9` 或 `adaptive`，实测 `16:9` 和 `9:16`。 |
| `duration` | integer | 否 | 视频时长（秒），4–15，默认 5，实测 `4` 生效。 |
| `generate_audio` | boolean | 否 | 是否同时生成音效。默认开启，实测生成的视频均带音轨。 |
| `seed` | integer | 否 | 随机种子，用于复现效果。 |
| `camera_fixed` | boolean | 否 | 是否固定镜头。 |
| `watermark` | boolean | 否 | 是否添加上游水印。 |
| `content` | array | 否 | 火山方舟素材项：`image_url`，可带 `role`，如 `first_frame`、`last_frame`、`reference_image`。 |

## 响应格式

### 创建任务的响应

**200 OK**

```json
{
  "id": "task_FUhA4FK80TV1p70mpHlyZXCxeHR0dPPa",
  "task_id": "task_FUhA4FK80TV1p70mpHlyZXCxeHR0dPPa",
  "object": "video",
  "model": "seedance-2-0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1792766873
}
```

### 查询任务的响应

**200 OK**

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_FUhA4FK80TV1p70mpHlyZXCxeHR0dPPa",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://example.com/output.mp4",
    "submit_time": 1792766873,
    "start_time": 1792766890,
    "finish_time": 1792767085,
    "progress": "100%",
    "data": {"resolution": "720p", "ratio": "16:9", "duration": 5, "...": "..."}
  }
}
```

`data.data` 是上游返回的原始任务信息，可以从中确认实际使用的分辨率、比例和时长。

| data.status | 含义 |
| --- | --- |
| `NOT_START` / `SUBMITTED` / `QUEUED` | 已受理，等待开始。 |
| `IN_PROGRESS` | 生成中。 |
| `SUCCESS` | 完成，下载 `result_url`。 |
| `FAILURE` | 失败，原因见 `fail_reason`，预扣费用会退回。 |

## 错误与限制

### 常见错误

| HTTP | error.code | 含义 | 处理建议 |
| --- | --- | --- | --- |
| `401` | — | API Key 缺失、错误或已删除，message 为 `Invalid token`。 | 检查 `Authorization: Bearer` 请求头，并在控制台核对 Key。 |
| `400` | — | 请求体不是合法 JSON。 | 修正 JSON，并带上 `Content-Type: application/json`。 |
| `500` | `invalid_request` | 缺少必填字段，例如未传 `messages`。 | 按 message 补全字段，重试无效。 |
| `403` | `insufficient_user_quota` | 账户余额或套餐额度不足。 | 在控制台充值后重试。 |
| `503` | `model_not_found` | 模型 ID 不存在，或你的分组下没有可用渠道。 | 在模型列表或 `GET /v1/models` 中核对模型 ID。 |
| `429` | — | 请求过于频繁。 | 指数退避后重试。 |
| `5xx` | — | 上游服务商出错或超时。 | 稍后重试几次；持续出错时保留 request id 联系支持。 |

### 使用限制与说明

- 建议每 10–15 秒查询一次。实测 4 秒 480p 的任务 3.5–4 分钟完成。
- `result_url` 是临时链接，请自行下载保存。
- 价格由 `metadata.resolution` 以及是否包含视频参考决定，实时价格见模型广场。

## 更多链接

- [Seedance 2.0 Fast API 文档页](https://tokenra.io/zh/docs/seedance-2-0-fast.html)：参数表和 cURL、Python、JavaScript、Java 代码示例
- [Seedance 2.0 Fast 模型介绍与价格页](https://tokenra.io/zh/models/seedance-2-0-api.html)
- [公共信息](https://tokenra.io/zh/docs/common.html)：Base URL、鉴权、错误码与重试
- [快速开始](https://tokenra.io/zh/docs/quickstart.html)：创建 Key 并发出第一个请求
- [全部模型](https://tokenra.io/zh/docs/models.html)：所有模型 ID
- [本指南的英文版](https://tokenra.io/docs/seedance-2-0-fast/llms.txt)
- [面向 AI 代理的站点索引](https://tokenra.io/llms.txt)

---

本文档的规范地址：https://tokenra.io/zh/docs/seedance-2-0-fast/llms.txt