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

# Seedance 2.5

> 通过 Xuwu 调用国内 Doubao 与海外 BytePlus Dreamina Seedance 2.5。

Seedance 2.5 同时提供国内 Doubao 和海外 BytePlus Dreamina 版本。两者共用 Xuwu 的任务接口和请求结构，但模型名、价格与联网搜索能力不同。

需要使用经过本人认证的真人素材时，先按 [真人素材库 API](./real-person-assets) 完成对应地域的 H5 认证和素材入库，再使用 `asset://<AssetId>` 创建任务。

## 1. 模型与价格

| 区域 | Xuwu 稳定模型名              | 官方版本 ID                        |            无视频输入 |           含视频输入 |
| -- | ----------------------- | ------------------------------ | ---------------: | --------------: |
| 国内 | `doubao-seedance-2-5`   | `doubao-seedance-2-5-260628`   |     ¥70/M tokens |    ¥42/M tokens |
| 海外 | `dreamina-seedance-2-5` | `dreamina-seedance-2-5-260628` | \$10.70/M tokens | \$6.40/M tokens |

建议在请求中使用稳定模型名。平台也接受对应的官方版本 ID，并自动映射到稳定模型；查询和列表响应仍回显稳定模型名。

`video` 档表示 `content[]` 中包含 `video_url`，否则使用 `novideo` 档。480p 与 720p 单价相同；只对成功生成的视频结算，实际视频用量以查询响应中的 `usage.completion_tokens` 为准。

国内模型还支持纯文本任务使用 `tools: [{"type":"web_search"}]`。联网搜索按响应中的 `usage.tool_usage.web_search` 实际次数独立结算；海外模型不支持该工具，具体客户价格以 Xuwu 控制台为准。

## 2. 接口

```bash theme={null}
export BASE_URL="https://xuwuai.com"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

| 功能      | 路径                                                            |
| ------- | ------------------------------------------------------------- |
| 创建任务    | `POST /volcark/api/v3/contents/generations/tasks`             |
| 查询任务    | `GET /volcark/api/v3/contents/generations/tasks/{task_id}`    |
| 查询任务列表  | `GET /volcark/api/v3/contents/generations/tasks`              |
| 取消或删除任务 | `DELETE /volcark/api/v3/contents/generations/tasks/{task_id}` |

所有请求使用 Xuwu API Token：

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

## 3. 创建任务

国内文生视频示例：

```bash theme={null}
curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5",
    "content": [
      {
        "type": "text",
        "text": "一段 5 秒的电影感产品短片，柔和自然光，镜头缓慢向前推进。"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true,
    "output_format": "mp4",
    "watermark": false
  }'
```

海外调用只需把 `model` 改为 `dreamina-seedance-2-5`；接口地址仍使用 Xuwu 的 `BASE_URL`。

创建成功返回任务 ID：

```json theme={null}
{
  "id": "cgt-202608130001-example",
  "model": "doubao-seedance-2-5"
}
```

### 多模态参考

`content[]` 支持以下输入：

| 类型          | `role`                                       | 数量上限 |
| ----------- | -------------------------------------------- | ---: |
| `image_url` | `reference_image`、`first_frame`、`last_frame` |   30 |
| `video_url` | `reference_video`                            |   10 |
| `audio_url` | `reference_audio`                            |   10 |

图片、视频和音频合计最多 50 个。Xuwu 托管素材可使用 `asset://<Asset_Id>`；素材需先完成上传和处理，再提交生成任务。

```json theme={null}
{
  "model": "doubao-seedance-2-5",
  "content": [
    {
      "type": "text",
      "text": "保持参考视频的镜头运动，使用参考图片的产品外观和参考音频的节奏。"
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {"url": "asset://video-asset-id"}
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "asset://image-asset-id"}
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {"url": "asset://audio-asset-id"}
    }
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1
}
```

首帧/尾帧任务必须使用 `ratio=adaptive`，`last_frame` 必须与 `first_frame` 同时出现，且首尾帧不能和 `reference_*` 素材混用。

### 国内联网搜索

联网搜索只支持国内 `doubao-seedance-2-5`，且 `content[]` 必须只有文本：

```json theme={null}
{
  "model": "doubao-seedance-2-5",
  "content": [
    {
      "type": "text",
      "text": "结合近期公开信息生成一段科技新闻风格短片。"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "tools": [
    {"type": "web_search"}
  ]
}
```

## 4. 参数边界

| 字段                        | Seedance 2.5 约束                                   |
| ------------------------- | ------------------------------------------------- |
| `resolution`              | 仅 `480p`、`720p`，不支持 `1080p` 或 `4k`                |
| `duration`                | `4-30` 的整数，或 `-1` 由模型选择                           |
| `ratio`                   | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `output_format`           | `mp4`、`mov`                                       |
| `generate_audio`          | 布尔值；默认生成同步音频                                      |
| `return_last_frame`       | 布尔值；成功响应可返回尾帧 URL                                 |
| `priority`                | `0-9`                                             |
| `execution_expires_after` | `3600-259200` 秒                                   |
| `service_tier`            | 仅支持 `default`                                     |
| `draft`                   | 仅支持 `false`                                       |

`seed`、`frames`、`frames_per_second`、`frame_rate`、`fps`、`camera_fixed` 不适用于 Seedance 2.5，传入时会在请求模型服务前返回 HTTP 400。

## 5. 查询结果

```bash theme={null}
curl "$BASE_URL/volcark/api/v3/contents/generations/tasks/cgt-202608130001-example" \
  -H "Authorization: Bearer $TOKEN"
```

任务状态包括 `queued`、`running`、`succeeded`、`failed` 和 `expired`。成功任务会返回 `content.video_url`、实际规格与 `usage`：

```json theme={null}
{
  "id": "cgt-202608130001-example",
  "model": "doubao-seedance-2-5",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/generated-video.mp4"
  },
  "usage": {
    "completion_tokens": 108000
  }
}
```

成功视频 URL 通常有效 24 小时，且存在下载次数限制，请及时转存；失败任务应读取响应中的结构化 `error`。

## 6. OpenAI 风格接口

Seedance 2.5 也可通过 `POST /v1/videos` 创建任务：

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5",
    "prompt": "一艘纸船漂浮在清晨的水面上",
    "seconds": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true
  }'
```

OpenAI 风格接口适合基础文生视频和参考素材调用。需要 `content[].role`、`output_format`、`tools.web_search` 等完整原生能力时，请使用 `/volcark/api/v3/contents/generations/tasks`。