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

# Seedance 文生视频

> 字节跳动 Seedance 视频生成接口

Seedance 是字节跳动视频生成模型族。在 AiSDK 里，推荐通过统一视频入口调用，而不是直接使用上游私有路径。

## AiSDK 推荐入口

* 提交任务：`POST /v1/videos`
* 兼容旧路径：`POST /v1/video/generations`
* 查询任务：`GET /v1/videos/{task_id}`
* 获取结果：`GET /v1/videos/{task_id}/content`

<Tip>
  如果你们历史客户端已经在使用 `/v1/video/generations`，可以继续兼容；新接入建议统一走 `/v1/videos`。
</Tip>

## 提交任务

### 请求参数

| 参数             | 类型      | 必填 | 说明                                                                 |
| -------------- | ------- | -- | ------------------------------------------------------------------ |
| `model`        | string  | 是  | 平台开放给你的 Seedance 模型名，例如 `video-seedance-1.5`、`doubao-seedance-2.0` |
| `prompt`       | string  | 是  | 视频描述提示词                                                            |
| `image`        | string  | 否  | 首帧图 URL，图生视频时使用                                                    |
| `duration`     | integer | 否  | 视频时长（秒），如 5、10                                                     |
| `ratio`        | string  | 否  | 比例，如 `16:9`、`9:16`、`1:1`                                           |
| `aspect_ratio` | string  | 否  | 某些渠道使用的等价字段，建议优先与平台约定一种写法                                          |
| `resolution`   | string  | 否  | 如 `480p`、`720p`、`1080p`                                            |
| `fps`          | integer | 否  | 帧率，常见为 24                                                          |
| `seed`         | integer | 否  | 随机种子                                                               |
| `metadata`     | object  | 否  | 透传扩展参数，适合放供应商特有字段                                                  |

<Note>
  `ratio`、`aspect_ratio`、`resolution`、`fps` 这些字段在代码里已有识别与计费链路支持，但是否被最终上游接受，仍取决于你当前绑定的具体渠道。
</Note>

### 示例

```bash theme={null}
curl https://your-domain.com/v1/videos \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-seedance-1.5",
    "prompt": "一只猫在雪地里奔跑，电影感",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p"
  }'
```

### 响应

AiSDK 统一视频入口提交后，先返回任务摘要。典型格式如下：

```json theme={null}
{
  "task_id": "task_xxxxxxxx",
  "status": "queued"
}
```

## 查询任务

**GET** `/v1/videos/{task_id}`

典型查询结果如下：

```json theme={null}
{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "model": "video-seedance-1.5",
  "status": "completed",
  "progress": 100,
  "created_at": 1712000000,
  "completed_at": 1712000028,
  "metadata": {
    "url": "https://.../output.mp4"
  }
}
```

## 下载结果

如果你希望通过平台代理地址直接下载最终视频：

```bash theme={null}
curl -L https://your-domain.com/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer sk-xxxx" \
  -o output.mp4
```

## 任务状态

| 状态            | 说明  |
| ------------- | --- |
| `queued`      | 排队中 |
| `in_progress` | 生成中 |
| `completed`   | 已完成 |
| `failed`      | 失败  |

## 接入建议

* 对外请优先使用平台公开模型名，不要把上游原始模型名直接写死到客户端。
* 第一次接入建议先只传 `model` + `prompt` 跑通，再逐步补 `duration`、`ratio`、`resolution`。
* 如果任务能提交但始终失败，优先排查当前 token 所属分组是否真的开放了这个 Seedance 模型。