> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# seedance-2.5-ext 视频生成

> 使用 seedance-2.5-ext 模型生成视频，支持参考图片、参考视频和参考音频

<Note>
  **国内用户请注意：** 中国大陆用户请使用 `https://toapis.cn` 作为接口地址（Base URL）。文档示例中的 `https://toapis.com` 请替换为 `https://toapis.cn`。
</Note>

`seedance-2.5-ext` 是 Seedance 2.5 系列的促销渠道模型，支持文生视频和多模态参考生成：

* 文生视频、参考图片生成
* 参考视频和参考音频联合生成（不支持视频编辑、延长和首尾帧模式）
* 接口为异步任务：提交后返回 `generation.task`，完成后通过[视频任务状态接口](../../tasks/video-status)获取结果。

根据请求内容自动路由到最优上游：仅图片或纯文本时走低成本上游；携带参考视频、参考音频或超过 10 张参考图时走全能力上游。

## 认证

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 认证：

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 请求参数

<ParamField body="model" type="string" default="seedance-2.5-ext" required>
  ToAPIs 公共模型名，固定使用 `seedance-2.5-ext`。
</ParamField>

<ParamField body="prompt" type="string">
  描述场景、镜头运动、主体动作、风格和声音氛围。引用素材时可按数组顺序写“图片1”“视频1”“音频1”等标签。
</ParamField>

<ParamField body="seconds" type="integer">
  输出视频时长（秒），范围 `10`–`30`。兼容字段 `duration` 也可以使用，无需同时传入。

  <Warning>
    携带参考视频、参考音频或超过 10 张参考图片时不支持 `15` 秒；纯文本或不超过 10 张图片的请求不受此限制。
  </Warning>
</ParamField>

<ParamField body="size" type="string">
  输出宽高比，支持 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`。兼容字段 `aspect_ratio` 也可以使用。
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  输出分辨率，固定为 `720p`。
</ParamField>

<ParamField body="reference_image" type="string">
  单张参考图片的公开 URL。多张时请改用 `reference_images`。
</ParamField>

<ParamField body="reference_images" type="string[]">
  参考图片 URL 数组，最多 `30` 张。也可以使用 `image_with_roles`（`role` 为 `reference_image`）显式传入。
</ParamField>

<ParamField body="video_with_roles" type="object[]">
  参考视频数组，最多 `10` 段。每项包含：

  * `url`：公开可访问的视频 URL
  * `role`：固定为 `reference_video`
</ParamField>

<ParamField body="audio_with_roles" type="object[]">
  参考音频数组，最多 `10` 段。每项包含：

  * `url`：公开可访问的音频 URL
  * `role`：固定为 `reference_audio`

  音频不能单独作为输入，请求中需要至少包含一张参考图片或一段参考视频。
</ParamField>

<ParamField body="callback_url" type="string">
  ToAPIs 任务完成回调地址，详见[任务 Webhook](/docs/cn/api-reference/webhooks/task-webhooks)。
</ParamField>

<ParamField body="client_business_id" type="string">
  客户侧订单号或业务任务 ID。提交后会随任务保存，也可用 `GET /v1/videos/generations/{client_business_id}` 查询。
</ParamField>

<ParamField body="trace_id" type="string">
  调用方自定义的链路追踪 ID。
</ParamField>

## 素材组合规则

| 请求内容 | 是否支持 | 说明 |
| - | -: | - |
| 仅提示词 | 是 | 文生视频 |
| 参考图片 ≤10 张 | 是 | 低成本上游 |
| 参考图片 11–30 张 | 是 | 不支持 15 秒 |
| 参考视频 / 参考音频 | 是 | 不支持 15 秒；音频需搭配图片或视频 |
| 首帧 / 尾帧 | 否 | 不支持首尾帧模式 |
| 视频编辑 / 延长 | 否 | 请使用 `seedance-2-5` |

## 请求示例

### 文生视频

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "电影感产品特写，镜头缓慢推进，保留自然室内声音。",
    "seconds": 10,
    "size": "16:9",
    "resolution": "720p"
  }'
```

### 参考图片生成

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "让图片1中的人物走入雨夜街道，镜头跟随。",
    "seconds": 12,
    "size": "9:16",
    "reference_images": [
      "https://example.com/character.png"
    ]
  }'
```

### 视频和音频联合参考

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "使用图片1中的人物形象、视频1的运镜和音频1的节奏生成视频。",
    "seconds": 14,
    "size": "16:9",
    "reference_images": [
      "https://example.com/character.png"
    ],
    "video_with_roles": [
      {"url": "https://example.com/motion.mp4", "role": "reference_video"}
    ],
    "audio_with_roles": [
      {"url": "https://example.com/rhythm.mp3", "role": "reference_audio"}
    ]
  }'
```

## 响应

<ResponseField name="id" type="string">任务 ID，用于查询状态。</ResponseField>
<ResponseField name="client_business_id" type="string">请求传入该字段时返回。</ResponseField>
<ResponseField name="object" type="string">固定为 `generation.task`。</ResponseField>
<ResponseField name="model" type="string">本次请求的模型名。</ResponseField>
<ResponseField name="status" type="string">`queued`、`in_progress`、`completed` 或 `failed`。</ResponseField>
<ResponseField name="progress" type="integer">`0`–`100` 的任务进度。</ResponseField>
<ResponseField name="created_at" type="integer">创建时间戳。</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "tsk_vid_xxx",
    "object": "generation.task",
    "model": "seedance-2.5-ext",
    "status": "in_progress",
    "progress": 10,
    "created_at": 1781577600
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.