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

# Seedance 系列

> 使用 AIOAGI 视频任务接口调用 Seedance 文生视频、图生视频和多模态参考生视频能力。

Seedance 系列通过 AIOAGI 视频任务接口调用。你可以创建异步视频任务，再查询任务结果。请求体使用官方 Seedance 参数结构：用 `content` 数组传入文本、图片、视频或音频，用 `ratio`、`duration`、`resolution` 和 `generate_audio` 控制输出规格。

<Warning>
  Seedance 模型名称、价格、分辨率、时长、音频支持和任务状态字段可能变化。生产调用前，请在 **控制台**、`GET /models` 或 **开发者指南** 中核对当前可用模型。
</Warning>

## 接口概览

| 能力     | 接口                  | 方法     | 说明                      |
| ------ | ------------------- | ------ | ----------------------- |
| 创建视频任务 | `/videos`           | `POST` | 提交文生视频、图生视频或多模态参考生视频任务。 |
| 查询视频任务 | `/videos/{task_id}` | `GET`  | 查询任务状态、进度和视频结果。         |

<Info>
  AIOAGI 使用 `/videos` 作为视频任务入口。请求体参数按官方 Seedance 字段填写。不要使用第三方自定义字段替代官方 `content`、`ratio`、`duration`、`resolution` 和 `generate_audio`。
</Info>

## 文生视频示例

```bash theme={null}
export AIO_API_KEY="sk-your-api-key"
export AIO_BASE_URL="https://api.aiearth.dev/v1"

curl "$AIO_BASE_URL/videos" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "一段未来科技展台的产品发布短片，镜头缓慢推进，金属材质，高级商业广告质感。"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": true,
    "watermark": false
  }'
```

## 图生视频示例

首帧图生视频只需要一张 `role: "first_frame"` 图片。首尾帧图生视频需要同时传入 `first_frame` 和 `last_frame`。

```bash theme={null}
curl "$AIO_BASE_URL/videos" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "让画面从产品特写自然过渡到完整展示，镜头轻微推进，光线保持柔和。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/first-frame.png"
        },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/last-frame.png"
        },
        "role": "last_frame"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": true
  }'
```

## 多模态参考生视频示例

Seedance 2.0 系列支持参考图片、参考视频和参考音频。音频不能单独作为输入，至少需要同时提供一张参考图片或一段参考视频。

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考素材中的人物站在海边，夕阳下回眸一笑，镜头从中景缓慢推进。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-20260519163832-example"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/reference-action.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/reference-voice.wav"
      },
      "role": "reference_audio"
    }
  ],
  "ratio": "adaptive",
  "duration": 5,
  "resolution": "720p",
  "generate_audio": true
}
```

## 查询任务结果

提交成功后，响应通常会包含任务 ID。官方任务创建响应字段为 `id`。如果你的兼容返回中同时提供 `task_id`，也可以按平台返回字段读取。

```bash theme={null}
curl "$AIO_BASE_URL/videos/{task_id}" \
  -H "Authorization: Bearer $AIO_API_KEY"
```

任务状态通常包括 `queued`、`running`、`succeeded`、`failed` 和 `expired`。如果任务失败，请读取错误信息，并记录请求体、模型名、任务 ID 和时间窗口。

## 核心参数

| 参数                        | 类型        | 说明                                                                                                              |
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `model`                   | `string`  | 必填。Seedance 模型 ID，例如 `doubao-seedance-2-0-260128`。                                                              |
| `content`                 | `array`   | 必填。输入给模型的内容数组。支持文本、图片、视频、音频和样片任务 ID。                                                                            |
| `content[].type`          | `string`  | 必填。可用值包括 `text`、`image_url`、`video_url`、`audio_url`、`draft_task`。                                               |
| `content[].text`          | `string`  | 当 `type` 为 `text` 时必填。用于描述期望生成的视频。                                                                              |
| `content[].image_url.url` | `string`  | 当 `type` 为 `image_url` 时必填。支持公网图片 URL、`data:image/...;base64,...` 或 `asset://` 素材 ID。                           |
| `content[].video_url.url` | `string`  | 当 `type` 为 `video_url` 时必填。支持公网视频 URL 或 `asset://` 素材 ID。仅 Seedance 2.0 系列支持参考视频输入。                             |
| `content[].audio_url.url` | `string`  | 当 `type` 为 `audio_url` 时必填。支持公网音频 URL、`data:audio/...;base64,...` 或 `asset://` 素材 ID。仅 Seedance 2.0 系列支持参考音频输入。 |
| `content[].role`          | `string`  | 条件必填。图片常见值为 `first_frame`、`last_frame`、`reference_image`；视频为 `reference_video`；音频为 `reference_audio`。           |
| `callback_url`            | `string`  | 可选。任务状态变化时接收回调通知。                                                                                               |
| `return_last_frame`       | `boolean` | 可选。是否在查询任务结果时返回生成视频的尾帧图像。默认通常为 `false`。                                                                         |
| `service_tier`            | `string`  | 可选。服务等级。Seedance 2.0 系列仅支持在线推理模式，不支持配置该参数。                                                                      |
| `execution_expires_after` | `integer` | 可选。任务超时阈值，单位为秒。官方默认值为 `172800`。                                                                                 |
| `generate_audio`          | `boolean` | 可选。是否生成同步音频。Seedance 2.0 系列和 Seedance 1.5 Pro 支持。                                                               |
| `draft`                   | `boolean` | 可选。是否开启样片模式。仅 Seedance 1.5 Pro 支持。                                                                              |
| `tools`                   | `array`   | 可选。Seedance 2.0 系列可配置工具，例如 `{"type": "web_search"}`。                                                            |
| `safety_identifier`       | `string`  | 可选。终端用户的唯一标识符，建议传入固定且不可反查个人信息的哈希值。                                                                              |
| `priority`                | `integer` | 可选。Seedance 2.0 系列请求优先级，范围通常为 `0` 到 `9`。                                                                        |
| `resolution`              | `string`  | 可选。常见值包括 `480p`、`720p`、`1080p`、`4k`。不同模型支持范围不同。                                                                 |
| `ratio`                   | `string`  | 可选。生成视频宽高比。常见值包括 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`。                                             |
| `duration`                | `integer` | 可选。生成视频时长，单位为秒。Seedance 2.0 系列常见范围为 `4` 到 `15`，也可按模型支持情况设置为 `-1` 自动选择。                                          |
| `frames`                  | `integer` | 可选。按帧数控制视频长度。Seedance 2.0 系列和 Seedance 1.5 Pro 暂不支持。                                                            |
| `seed`                    | `integer` | 可选。随机种子。Seedance 2.0 系列暂不支持。                                                                                    |
| `camera_fixed`            | `boolean` | 可选。是否固定摄像头。参考图场景和 Seedance 2.0 系列暂不支持。                                                                          |
| `watermark`               | `boolean` | 可选。是否添加 `AI 生成` 水印。默认通常为 `false`。                                                                               |

<Warning>
  `resolution`、`ratio`、`duration`、`frames`、`seed`、`camera_fixed` 和 `watermark` 推荐直接写在 request body 中。不要把它们写成第三方字段名。
</Warning>

## 输入内容规则

| 场景      | `content` 写法                                  | 说明                                                 |
| ------- | --------------------------------------------- | -------------------------------------------------- |
| 文生视频    | 一个 `type: "text"` 项                           | 所有 Seedance 模型均支持中英文提示词。Seedance 2.0 系列还支持更多提示词语言。 |
| 首帧图生视频  | `text` 加一张 `role: "first_frame"` 图片           | 图片也可以不填 `role`，但建议显式填写。                            |
| 首尾帧图生视频 | `text` 加 `first_frame` 和 `last_frame` 图片      | 首尾帧图片宽高比不一致时，平台会以首帧为主裁剪适配。                         |
| 参考图生视频  | `text` 加 1 到 9 张 `role: "reference_image"` 图片 | Seedance 2.0 系列支持。                                 |
| 参考视频    | `text` 加最多 3 段 `role: "reference_video"` 视频   | Seedance 2.0 系列支持。所有参考视频总时长不超过模型限制。                |
| 参考音频    | `text` 加 `reference_audio`，并同时包含图片或视频         | Seedance 2.0 系列支持。不可只传音频。                          |

## 素材格式

* 图片支持公网 URL、`data:image/...;base64,...` 和 `asset://` 素材 ID。大文件建议使用 URL 或素材 ID，不要使用 Base64。
* 单张图片常见格式包括 `jpeg`、`png`、`webp`、`bmp`、`tiff`、`gif`。Seedance 1.5 Pro 和 Seedance 2.0 系列还可支持 `heic`、`heif`。
* 参考视频支持公网 URL 或 `asset://` 素材 ID。常见容器格式包括 `mp4` 和 `mov`。
* 参考音频支持公网 URL、`data:audio/...;base64,...` 和 `asset://` 素材 ID。常见格式包括 `wav` 和 `mp3`。

## 排障建议

* 遇到 `401`，检查 API Key 和 `Authorization` 请求头。
* 遇到 `403`，检查账户余额、Token 组额度和模型权限。
* 遇到 `404` 或 `model_not_found`，核对 base URL、模型 ID 和任务 ID。
* 遇到参数错误，先检查 `content` 是否是数组、`content[].type` 是否正确、`role` 是否匹配输入场景。
* 遇到规格错误，核对 `ratio`、`duration`、`resolution`、`generate_audio` 和当前模型支持范围。
* 遇到 `429`，降低提交并发和轮询频率，并加入指数退避。
* 遇到 `500` 或 `502`，记录任务 ID 和时间窗口，稍后重试或联系服务支持。