# Seedance 2.5 Pro API（TokenRa）

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

> Seedance 2.5 Pro 是字节跳动的 Seedance 2.5 视频模型，在 TokenRa 上的模型 ID 为 `artsdance-2-5-pro-260801`。支持文本和参考图输入，输出带音轨的视频；请求格式与 Seedance 2.0 不同。

- 厂商：字节跳动
- 类型：视频模型
- 输入：文本、参考图
- 输出：720p 或 1080p 视频
- 调用方式：异步任务

## 价格

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

- `artsdance-2-5-pro-260801`：$8.88 / 100 万 token，输入和输出同价（视频任务按实际消耗的 token 计费）

## 能力与接口

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

- `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": "artsdance-2-5-pro-260801",
    "prompt": "雨夜霓虹街道上漂流的纸船，电影感特写镜头",
    "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"
```

## 生成场景

### A. 文生视频

输出设置直接写在请求顶层。2026-10-23 实测：生成的视频为 720x1280、4.08 秒，且没有音轨。

**POST /v1/video/generations**

```json
{
  "model": "artsdance-2-5-pro-260801",
  "prompt": "雨夜霓虹街道上漂流的纸船，电影感特写镜头",
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 4,
  "generate_audio": false
}
```

### B. 参考图生视频

`images` 中的图片会作为参考图（reference_image）传给模型。2026-10-23 实测：生成 1280x720、5 秒、带音轨的视频，即不传 `ratio`、`duration`、`generate_audio` 时的默认效果。

**POST /v1/video/generations**

```json
{
  "model": "artsdance-2-5-pro-260801",
  "prompt": "标志卡片缓慢推近，一道柔光从画面上扫过",
  "images": ["https://example.com/logo-card.png"],
  "resolution": "720p"
}
```

### C. content 数组

需要逐项控制素材时，用 `content` 代替 `prompt` 和 `images`：1–16 个 `text` 或 `image_url` 项，且至少包含一个 `text` 项，`role` 原样传给模型。B 模式最终也会转换成这种请求。

**POST /v1/video/generations**

```json
{
  "model": "artsdance-2-5-pro-260801",
  "resolution": "720p",
  "content": [
    {"type": "text", "text": "图一中的角色走进图二的房间"},
    {
      "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"
    }
  ]
}
```

## 请求参数

**输出设置写在请求顶层**

Seedance 2.5 从请求顶层读取 `resolution`、`ratio`、`duration` 和 `generate_audio`，与 [Seedance 2.0](https://tokenra.io/zh/docs/seedance-2-0-pro.html) 从 `metadata` 读取的方式相反。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `artsdance-2-5-pro-260801` |
| `prompt` | string | 是 | 画面、动作与镜头描述。使用 `content` 且其中包含 `text` 项时可省略。 |
| `resolution` | string | 是 | `720p` 或 `1080p`，必填；不传或传 `480p` 都会被拒绝。同时决定计费档位。 |
| `ratio` | string | 否 | 画面比例，如 `16:9`、`9:16`，实测 `9:16` 生效。 |
| `duration` | integer | 否 | 视频时长（秒），默认 5，实测 `4` 生效。 |
| `generate_audio` | boolean | 否 | 是否生成音轨，默认开启；实测 `false` 生成无声视频。 |
| `images` | string[] | 否 | 参考图链接数组，见 B 模式。 |
| `content` | array | 否 | 文本与图片素材，见 C 模式，可代替 `prompt` 和 `images`。 |

**TokenRa 上不支持的用法**

- `metadata` 会被忽略。实测只在 `metadata` 中传 `resolution` 时，请求被拒绝，错误码为 `invalid_resolution`。
- 不支持视频和音频参考：`video_url`、`audio_url` 素材会报错 `unsupported content type`。
- 只有上表中的字段会发送给模型，`seed`、`watermark`、`return_last_frame`、`callback_url` 等其他字段会被直接丢弃，不会报错。

## 响应格式

### 创建任务的响应

**200 OK**

```json
{
  "id": "task_FUhA4FK80TV1p70mpHlyZXCxeHR0dPPa",
  "task_id": "task_FUhA4FK80TV1p70mpHlyZXCxeHR0dPPa",
  "object": "video",
  "model": "artsdance-2-5-pro-260801",
  "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": {
      "id": "cgt-20261023154938-amaq7",
      "object": "video.generation",
      "status": "completed",
      "data": [{"url": "https://example.com/output.mp4"}],
      "usage": {"total_tokens": 104140, "completion_tokens": 104140}
    }
  }
}
```

`data.data` 是上游返回的原始任务信息。与 Seedance 2.0 不同，其中不会回显分辨率、比例和时长；`usage.total_tokens` 是计费用的视频 token 数。

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

## 错误与限制

### 该模型的参数错误

| HTTP | code | message | 原因 |
| --- | --- | --- | --- |
| `400` | `invalid_resolution` | `resolution must be 720p or 1080p` | 未传 `resolution`、传了 `480p`，或只写在 `metadata` 里。 |
| `400` | `invalid_request` | `prompt is required` | 没有 `prompt`，`content` 中也没有 `text` 项。 |
| `500` | `build_request_failed` | `unsupported content type: video_url` | `content` 中有 `text`、`image_url` 以外的素材类型。 |

### 常见错误

| 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–5 秒 720p 的任务约 5 分钟完成。
- `result_url` 是临时链接，请自行下载保存。
- 价格由 `resolution`（720p 或 1080p）决定，实时价格见模型广场。

## 更多链接

- [Seedance 2.5 Pro API 文档页](https://tokenra.io/zh/docs/artsdance-2-5-pro-260801.html)：参数表和 cURL、Python、JavaScript、Java 代码示例
- [Seedance 2.5 Pro 模型介绍与价格页](https://tokenra.io/zh/models/seedance-2-5-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/artsdance-2-5-pro-260801/llms.txt)
- [面向 AI 代理的站点索引](https://tokenra.io/llms.txt)

---

本文档的规范地址：https://tokenra.io/zh/docs/artsdance-2-5-pro-260801/llms.txt