> ## 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 视频生成与 Asset 素材库 API

本文面向通过西湖云统一网关调用 Seedance 视频模型的开发者，覆盖视频任务提交、异步查询、结果下载、Asset 素材上传与管理，以及图片首帧和尾帧组合调用。

## 平台约定

* Base URL：`https://ai.xihuyun.com`
* 所有请求使用平台 API Key：`Authorization: Bearer <API_KEY>`。
* `model` 应使用平台模型页展示的可用模型名；需要固定渠道时，复制完整的渠道路由模型名。
* Asset 上传和视频生成必须使用同一个 API Key。
* Asset 引用统一使用上传响应中的完整 `data.asset_uri`，格式为 `asset://随机assetid`。不要自行添加固定前缀，也不要传对象存储 URL或预览 URL。

> 文档版本：2026-09-01 适用范围：本项目统一视频任务接口中的 Seedance / Doubao 视频模型

本文档描述用户通过本项目网关调用 Seedance 模型的方式。请求发往本项目部署域名，网关负责模型路由、上游请求转换、异步任务保存和任务状态查询；客户端不需要直接调用火山方舟或其他上游地址。

## 1. 基础信息

将下面的变量替换为实际值：

```text theme={null}
BASE_URL=https://ai.xihuyun.com
API_KEY=sk-xxxxxxxxxxxxxxxx
```

### 鉴权

所有提交、查询和视频内容下载请求都使用用户 API 令牌：

```http theme={null}
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
```

API 令牌必须属于已启用用户，并且该令牌所在分组可以使用所请求的模型。请勿把 API Key 写入前端公开代码、日志或错误上报内容。

### 接口列表

| 方法     | 路径                                 | 说明               |
| ------ | ---------------------------------- | ---------------- |
| `POST` | `/v1/videos`                       | 提交视频生成任务，推荐使用    |
| `GET`  | `/v1/videos/{task_id}`             | 查询任务状态和结果，推荐使用   |
| `GET`  | `/v1/videos/{task_id}/content`     | 下载已完成的视频二进制内容    |
| `POST` | `/v1/video/generations`            | 项目原生兼容入口         |
| `GET`  | `/v1/video/generations/{task_id}`  | 项目原生兼容查询入口       |
| `POST` | `/v1/videos/generations`           | 兼容部分 OpenAI 风格网关 |
| `GET`  | `/v1/videos/generations/{task_id}` | 对应的兼容查询入口        |

提交和查询必须使用同一种路径风格。例如使用 `/v1/videos` 提交后，应使用 `/v1/videos/{task_id}` 查询。不同入口返回字段基本一致；`/v1/videos` 及 `/v1/videos/{task_id}` 的时间字段为 Unix 秒，`/v1/video/generations*` 和 `/v1/videos/generations*` 入口的时间字段为 RFC3339 字符串。

## 2. 快速开始

### 2.1 文生视频

```bash theme={null}
curl "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "电影感夜景，雨后的城市街道，一名穿红色风衣的女性从霓虹灯下缓慢走过，镜头平稳推进，保留自然的城市环境音",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true,
    "watermark": false
  }'
```

典型提交响应：

```json theme={null}
{
  "id": "task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe",
  "object": "video.generation",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "progress": 0,
  "created_at": 1778293580,
  "error": null
}
```

`id` 是本项目生成的公开任务 ID。后续查询时必须使用这个 ID，不要使用上游返回的内部任务 ID。

### 2.2 轮询任务

```bash theme={null}
curl "$BASE_URL/v1/videos/task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe" \
  -H "Authorization: Bearer $API_KEY"
```

建议客户端每隔 2～5 秒查询一次，直到 `status` 变为 `completed` 或 `failed`。

完成响应示例：

```json theme={null}
{
  "id": "task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe",
  "object": "video.generation",
  "model": "doubao-seedance-2-5-260628",
  "status": "completed",
  "progress": 100,
  "created_at": 1778293580,
  "completed_at": 1778293807,
  "output": {
    "video_url": "https://cdn.example.com/videos/task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe.mp4",
    "last_frame_url": "https://cdn.example.com/videos/task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe-last-frame.jpg"
  },
  "usage": {
    "completion_tokens": 12345,
    "total_tokens": 12345
  },
  "error": null
}
```

`output.video_url` 在上游返回视频地址时出现；`output.last_frame_url` 只有在请求开启 `return_last_frame` 且上游返回尾帧时出现。

### 2.3 下载视频内容

如果客户端不希望直接访问上游视频地址，可以使用本项目的视频内容代理：

```bash theme={null}
curl "$BASE_URL/v1/videos/task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o output.mp4
```

该接口只允许下载已完成任务，并返回视频二进制内容，不返回 JSON。任务不存在返回 `404`，任务尚未完成返回 `400`。

## 3. 请求参数

提交接口使用 `application/json`。`model` 必填；`prompt` 通常必填，但图生视频、参考生成可以使用视觉参考替代纯文本提示词，Seedance 2.5 还允许纯音频参考请求。

### 3.1 通用字段

| 字段                 | 类型        | 必填 | 说明                                                                       |
| ------------------ | --------- | -: | ------------------------------------------------------------------------ |
| `model`            | string    |  是 | 已在本项目渠道中启用且当前令牌可用的模型名                                                    |
| `prompt`           | string    | 条件 | 文本提示词；可包含主体、动作、镜头、场景、风格和声音描述                                             |
| `duration`         | integer   |  否 | 生成时长，单位为秒；Seedance 2.5 支持 `4`～`30` 或 `-1` 自动时长                           |
| `resolution`       | string    |  否 | 分辨率档位，如 `480p`、`720p`；Seedance 2.5 仅支持 `480p`、`720p`                     |
| `ratio`            | string    |  否 | 画面比例：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`；Seedance 2.5 另外支持 `adaptive` |
| `generate_audio`   | boolean   |  否 | 是否生成音频。Seedance 2.x 未填写时按 `true` 处理；显式传 `false` 会保留为 `false`             |
| `n`                | integer   |  否 | 输出数量。当前 Seedance 只支持单输出；如传入必须为 `1`，建议直接省略                                |
| `images`           | string\[] |  否 | 图片 URL 数组，适合简单图生视频                                                       |
| `image`            | string    |  否 | 单张图片 URL，兼容字段，服务端会转换为 `images`                                           |
| `reference_inputs` | object\[] |  否 | 结构化图片、视频、音频参考，推荐用于参考生成或首尾帧                                               |
| `input_reference`  | string    |  否 | 单个参考 URL 的兼容字段；建议使用 `images` 或 `reference_inputs`                        |
| `metadata`         | object    |  否 | 兼容旧调用方式，可放 `video_url(s)`、`audio_url(s)`、首尾帧 URL 等字段                     |

`duration` 是规范字段。旧客户端可以传 `seconds`，但当 `duration` 同时存在时，以 `duration` 为准。`size` 也属于兼容字段；新调用请使用 `resolution` 和 `ratio`，尤其不要用 `size` 表示 Seedance 2.5 的分辨率。

### 3.2 结构化参考素材

推荐使用 `reference_inputs`，服务端会将其转换为上游 Seedance 所需的 `content[]`：

```json theme={null}
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "人物按照视频中的动作节奏转身，最后停在首帧人物的正面构图",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9",
  "reference_inputs": [
    {
      "type": "image",
      "role": "reference_image",
      "url": "asset://随机图片assetid"
    },
    {
      "type": "video",
      "role": "reference_video",
      "url": "asset://随机视频assetid",
      "duration_seconds": 8
    },
    {
      "type": "audio",
      "role": "reference_audio",
      "url": "asset://随机音频assetid",
      "duration_seconds": 8
    }
  ]
}
```

字段说明：

| 字段                 | 类型     | 说明                                                                                              |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------- |
| `type`             | string | `image`、`video` 或 `audio`                                                                       |
| `role`             | string | 图片可用 `first_frame`、`last_frame`、`reference_image`；视频使用 `reference_video`；音频使用 `reference_audio` |
| `url`              | string | 上游可访问的绝对 URL；不要传浏览器本地路径或临时 Blob URL                                                             |
| `duration_seconds` | number | 视频/音频参考时长。Seedance 2.5 建议填写；填写时必须满足 2～30 秒及合计时长限制                                               |

服务端生成的上游内容项大致如下：

```json theme={null}
{
  "type": "image_url",
  "image_url": { "url": "asset://随机图片assetid" },
  "role": "reference_image"
}
```

用户调用统一接口时，不需要也不应自行包装 `task_type`、`options` 等非本项目请求字段；项目会根据统一字段构造上游 `content[]`。

### 3.3 旧版 `metadata` 兼容写法

下列写法仍可用于传入视频和音频参考：

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "使用参考视频的动作节奏生成产品展示视频",
  "images": ["https://cdn.example.com/product.png"],
  "metadata": {
    "video_urls": ["asset://随机视频assetid"],
    "audio_urls": ["asset://随机音频assetid"]
  }
}
```

还支持单个 `metadata.video_url` 或 `metadata.audio_url`。首尾帧可以通过 `metadata.first_frame_url` 和 `metadata.last_frame_url` 指定；使用 `reference_inputs` 的 `role` 更直观，也更适合同时传递时长信息。

## 4. Seedance 模型与能力限制

### 4.1 当前内置模型目录

当前 Doubao 视频适配器内置以下模型名。实际可用模型还受管理员渠道、模型映射、分组和令牌权限影响，请以部署实例的模型列表为准：

| 模型                                | 说明                        |
| --------------------------------- | ------------------------- |
| `doubao-seedance-1-0-pro-250528`  | Seedance 1.0 Pro          |
| `doubao-seedance-1-0-lite-t2v`    | Seedance 1.0 Lite 文生视频    |
| `doubao-seedance-1-0-lite-i2v`    | Seedance 1.0 Lite 图生视频    |
| `doubao-seedance-1-5-pro-251215`  | Seedance 1.5 Pro          |
| `doubao-seedance-2-0-260128`      | Seedance 2.0              |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 Fast         |
| `doubao-seedance-2-5-260628`      | Seedance 2.5，当前 2.5 规范模型名 |

Seedance 2.5 常见别名（例如 `seedance-2.5`、`Seedance2.5`、`doubao-seedance-2.5`）可被项目识别并在发送到上游时归一化为 `doubao-seedance-2-5-260628`；公开调用仍应优先使用部署实例实际配置的模型名。

### 4.2 Seedance 1.x / 1.5 与 2.0

项目对 Seedance 家族的通用输入能力按以下上限校验：

| 项目     |                                                 限制 |
| ------ | -------------------------------------------------: |
| 图片参考   |                                             最多 9 个 |
| 视频参考   |                                             最多 3 个 |
| 音频参考   |                                             最多 3 个 |
| 额外总数上限 |                             当前项目不声明额外的图片+视频+音频合计上限 |
| 输出数量   |                                            仅支持 1 个 |
| 支持模式   | `text_to_video`、`image_to_video`、`multi_reference` |

Seedance 1.x / 1.5 和 2.0 的具体时长、分辨率和上游能力可能随已配置渠道而变化。当前项目不会把 Seedance 2.5 的固定范围自动套用到 2.0；请使用该渠道/模型的实际文档或控制台配置。

Seedance 2.0（含 `doubao-seedance-2-0-fast-260128`）的注意事项：

* 音频参考必须同时存在至少一个图片或视频参考，不能仅传音频。
* `n` 只能为 `1`；不能请求多输出。
* `seed`、`frames`、`camera_fixed`、`service_tier`、`fps`、`motion`、`negative_prompt` 不支持，传入后会在扣费前拒绝。
* `output_format` 对 Seedance 2.0 不支持；需要指定输出格式时使用 Seedance 2.5。
* 未传 `generate_audio` 时，项目按 `true` 发送；如不需要生成音频，请明确传 `"generate_audio": false`。

示例：

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "一只金色柴犬在樱花树下奔跑，镜头平稳跟拍",
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": false
}
```

### 4.3 Seedance 2.5

Seedance 2.5 只按明确的 2.5 模型标识启用以下契约：

| 项目         |                                                限制 |
| ---------- | ------------------------------------------------: |
| 图片参考       |                                           最多 30 个 |
| 视频参考       |                                           最多 10 个 |
| 音频参考       |                                           最多 10 个 |
| 图片+视频+音频合计 |                                           最多 50 个 |
| 单个视频参考时长   |                                            2～30 秒 |
| 单个音频参考时长   |                                            2～30 秒 |
| 视频参考合计时长   |                                           最多 30 秒 |
| 音频参考合计时长   |                                           最多 30 秒 |
| 输出时长       |                                4～30 秒，或 `-1` 自动时长 |
| 分辨率        |                                     `480p`、`720p` |
| 画面比例       | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive` |
| 输出格式       |                                       `mp4`、`mov` |
| 输出数量       |                                           仅支持 1 个 |

音频参考可以单独使用，不要求同时传图片或视频。例如：

```json theme={null}
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "根据参考音频的节奏生成抽象光影视频",
  "duration": 8,
  "resolution": "480p",
  "ratio": "16:9",
  "reference_inputs": [
    {
      "type": "audio",
      "role": "reference_audio",
      "url": "https://cdn.example.com/reference.mp3",
      "duration_seconds": 8
    }
  ]
}
```

#### 首帧和尾帧

首帧/尾帧通过图片参考的 `role` 指定：

```json theme={null}
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "人物从第一张图的站立姿势自然走到第二张图的构图",
  "duration": 6,
  "resolution": "720p",
  "ratio": "adaptive",
  "reference_inputs": [
    {
      "type": "image",
      "role": "first_frame",
      "url": "asset://随机首帧assetid"
    },
    {
      "type": "image",
      "role": "last_frame",
      "url": "asset://随机尾帧assetid"
    }
  ]
}
```

首尾帧规则：

* 最多一个 `first_frame` 和一个 `last_frame`。
* 传 `last_frame` 时必须同时传 `first_frame`。
* 使用首帧或尾帧时，`ratio` 必须为 `adaptive` 或省略。
* 首尾帧模式不能同时混入 `reference_image`、`reference_video` 或 `reference_audio` 参考角色；如需混合素材，请使用普通参考生成模式。

#### Seedance 2.5 专用字段

| 字段                        | 类型        | 限制                               |
| ------------------------- | --------- | -------------------------------- |
| `output_format`           | string    | `mp4` 或 `mov`                    |
| `priority`                | integer   | `0`～`9`；显式传 `0` 会保留              |
| `safety_identifier`       | string    | 最多 64 个字符                        |
| `return_last_frame`       | boolean   | 为 `true` 时请求返回尾帧地址               |
| `watermark`               | boolean   | 是否添加水印                           |
| `execution_expires_after` | integer   | `3600`～`259200` 秒                |
| `callback_url`            | string    | 可选回调地址；是否回调取决于已配置上游，客户端仍应轮询任务    |
| `tools`                   | object\[] | 当前仅支持 `{ "type": "web_search" }` |

示例：

```json theme={null}
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "一只猫在窗台上眺望城市夜景",
  "duration": -1,
  "resolution": "720p",
  "ratio": "adaptive",
  "output_format": "mp4",
  "priority": 0,
  "generate_audio": false,
  "return_last_frame": true,
  "watermark": false,
  "execution_expires_after": 3600,
  "tools": [{ "type": "web_search" }]
}
```

## 5. 状态和响应字段

### 5.1 状态值

| `status`      | 说明                          |
| ------------- | --------------------------- |
| `queued`      | 已提交，等待上游处理                  |
| `in_progress` | 上游正在生成                      |
| `completed`   | 生成成功，可读取 `output.video_url` |
| `failed`      | 生成失败，查看 `error`             |
| `unknown`     | 网关无法识别当前状态，客户端应保留原始响应并联系管理员 |

`progress` 为整数百分比。异步生成阶段的进度是网关根据上游状态映射的估算值，不应被当作精确的剩余时间。

### 5.2 标准响应字段

| 字段                      | 类型             | 说明                                                                |
| ----------------------- | -------------- | ----------------------------------------------------------------- |
| `id`                    | string         | 本项目公开任务 ID，格式通常为 `task_...`                                       |
| `object`                | string         | 固定为 `video.generation`                                            |
| `model`                 | string         | 请求使用的公开模型名                                                        |
| `status`                | string         | 任务状态                                                              |
| `progress`              | integer        | 0～100 的进度值                                                        |
| `created_at`            | integer/string | 创建时间；`/v1/videos`、`/v1/videos/{task_id}` 为 Unix 秒，其他视频入口为 RFC3339 |
| `completed_at`          | integer/string | 完成时间；任务未完成时可能不存在，格式与 `created_at` 一致                              |
| `output.video_url`      | string         | 成功后的视频地址                                                          |
| `output.last_frame_url` | string         | 可选的尾帧地址                                                           |
| `usage`                 | object         | 上游返回用量时包含 `completion_tokens`、`total_tokens`                      |
| `error`                 | object/null    | 失败时包含 `code`、`message`                                            |

## 6. 错误处理

### 6.1 Seedance 参数校验错误

请求参数错误通常返回 HTTP `400`：

```json theme={null}
{
  "code": "seedance_duration_unsupported",
  "message": "seedance_duration_unsupported",
  "data": null
}
```

常见错误码：

| 错误码                                            | 说明                        |
| ---------------------------------------------- | ------------------------- |
| `seedance_reference_image_limit_exceeded`      | 图片参考数量超限                  |
| `seedance_reference_video_limit_exceeded`      | 视频参考数量超限                  |
| `seedance_reference_audio_limit_exceeded`      | 音频参考数量超限                  |
| `seedance_reference_total_limit_exceeded`      | 2.5 参考素材总数超过 50           |
| `seedance_reference_audio_requires_visual`     | 2.0/1.x 仅传音频，缺少图片或视频参考    |
| `seedance_output_count_unsupported`            | `n` 不是 1                  |
| `seedance_duration_unsupported`                | 2.5 时长不是 4～30 或 `-1`      |
| `seedance_resolution_unsupported`              | 2.5 分辨率不是 `480p` 或 `720p` |
| `seedance_ratio_unsupported`                   | 画面比例不支持                   |
| `seedance_output_format_unsupported`           | 输出格式不支持，或 2.0 传入了该字段      |
| `seedance_priority_unsupported`                | `priority` 不在 0～9 范围      |
| `seedance_execution_expires_after_unsupported` | 任务有效期不在允许范围               |
| `seedance_safety_identifier_too_long`          | 安全标识超过 64 个字符             |
| `seedance_tool_unsupported`                    | `tools` 包含当前不支持的工具类型      |
| `seedance_seed_unsupported`                    | 传入了 `seed`                |
| `seedance_frames_unsupported`                  | 传入了 `frames`              |
| `seedance_camera_fixed_unsupported`            | 传入了 `camera_fixed`        |
| `seedance_service_tier_unsupported`            | 传入了 `service_tier`        |
| `seedance_fps_unsupported`                     | 传入了 `fps`                 |
| `seedance_motion_unsupported`                  | 传入了 `motion`              |
| `seedance_negative_prompt_unsupported`         | 传入了 `negative_prompt`     |
| `seedance_last_frame_requires_first_frame`     | 只传了尾帧，没有首帧                |
| `seedance_frame_ratio_requires_adaptive`       | 首尾帧模式没有使用 `adaptive` 比例   |
| `seedance_frame_reference_roles_conflict`      | 首尾帧与普通参考角色混用              |

### 6.2 鉴权和权限错误

鉴权失败使用 OpenAI 风格错误结构：

```json theme={null}
{
  "error": {
    "message": "Invalid token",
    "type": "token_factory_error",
    "code": ""
  }
}
```

常见 HTTP 状态码：

|   状态码 | 说明                         |
| ----: | -------------------------- |
| `401` | 缺少、格式错误、无效或过期的 API 令牌      |
| `403` | 用户被禁用、令牌无权访问分组，或触发令牌 IP 限制 |
| `404` | 查询的任务不存在或不属于当前令牌用户         |
| `429` | 当前分组或上游负载已饱和               |
| `5xx` | 网关或上游服务异常                  |

客户端应同时检查 HTTP 状态码和 JSON 中的 `code`、`message` 或 `error`，不要只依据 HTTP `200` 判断视频已经生成成功。

## 7. 调用建议

* 新项目使用 `/v1/videos` 和 `/v1/videos/{task_id}`，并按 Unix 秒解析时间字段。
* 所有图片、视频、音频 URL 都应能被上游服务访问；本地文件需要先上传到项目素材接口或其他可访问存储，再把返回 URL 作为参考地址。
* 对视频和音频参考填写准确的 `duration_seconds`，便于 2.5 在提交前完成时长校验。
* 2.0/2.5 只提交项目已声明支持的字段；不支持的字段会在预扣费前拒绝。
* 任务提交成功只表示任务已进入异步队列；必须继续轮询到 `completed` 或 `failed`。
* 费用由本项目当前渠道、模型、分组和视频计价配置决定，不要在客户端硬编码价格。生成任务可能先预扣额度，最终按任务实际结果完成结算。
* 不要把同一任务的提交入口和查询入口混用，避免时间格式和响应适配方式不一致。

***

## Asset 素材库 API（Seedance 2.0）

本文说明如何使用平台 Asset 素材库 API 上传、管理图片/视频/音频素材，并将素材引用到 Seedance 2.0 视频生成请求中。

## 1. 快速开始

准备平台地址和 API Key：

```bash theme={null}
export BASE_URL="https://ai.xihuyun.com"
export API_KEY="sk-替换为你的平台APIKey"
```

所有接口都使用以下请求头：

```http theme={null}
Authorization: Bearer <API_KEY>
```

API Key 必须属于已启用用户，并且该用户有权使用目标 Seedance 模型。请勿把真实 Key 写入前端代码、公开仓库或日志。

最小可用流程：

1. `POST /v1/assets` 上传素材。
2. 从响应中读取 `data.asset_uri`，例如 `asset://随机assetid`。
3. 将该 URI 放入 Seedance 2.0 的 `images` 或 `content` 字段。
4. 使用返回的任务 ID 查询生成状态。

## 2. 接口概览

| 功能        | 方法       | 路径                               |
| --------- | -------- | -------------------------------- |
| 上传本地素材    | `POST`   | `/v1/assets`                     |
| 从在线地址导入素材 | `POST`   | `/v1/assets/import`              |
| 查询素材列表    | `GET`    | `/v1/assets`                     |
| 查询素材详情    | `GET`    | `/v1/assets/{asset_id}`          |
| 删除素材      | `DELETE` | `/v1/assets/{asset_id}`          |
| 恢复已删除素材   | `POST`   | `/v1/assets/{asset_id}/restore`  |
| 查询文件夹     | `GET`    | `/v1/assets/folders`             |
| 创建文件夹     | `POST`   | `/v1/assets/folders`             |
| 重命名文件夹    | `PATCH`  | `/v1/assets/folders/{folder_id}` |
| 删除文件夹     | `DELETE` | `/v1/assets/folders/{folder_id}` |
| 移动素材到文件夹  | `PATCH`  | `/v1/assets/{asset_id}/folder`   |

素材属于当前 API Key 对应的用户。生成请求也应使用同一个 API Key，以便平台校验 `asset://` 的归属。

## 3. 上传本地素材

### 请求

```bash theme={null}
curl -X POST "$BASE_URL/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./reference.png" \
  -F "agreed=true"
```

字段说明：

| 字段             | 类型     | 必填 | 说明                               |
| -------------- | ------ | -- | -------------------------------- |
| `file`         | File   | 是  | 素材文件；支持单文件，也支持同一请求上传多个 `file` 字段 |
| `agreed`       | string | 是  | 是否同意素材使用合规协议，传 `true`            |
| `folder_id`    | string | 否  | 素材所属文件夹 ID                       |
| `storage_mode` | string | 否  | 使用平台已配置的存储模式；不填使用默认模式            |

支持的扩展名：

| 类型 | 扩展名                                         |
| -- | ------------------------------------------- |
| 图片 | `.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.bmp` |
| 视频 | `.mp4`、`.mov`、`.webm`、`.mkv`、`.avi`、`.m4v`  |
| 音频 | `.mp3`、`.wav`、`.m4a`、`.aac`、`.flac`、`.ogg`  |

### 单文件成功响应

```json theme={null}
{
  "success": true,
  "data": {
    "asset_id": "随机assetid",
    "asset_uri": "asset://随机assetid",
    "asset": {
      "name": "reference.png",
      "asset_type": "Image",
      "status": "Active",
      "url": "https://..."
    }
  }
}
```

后续请求必须使用响应中的完整 `data.asset_uri`。不要把对象存储 URL、预览 URL 或自行拼接的 ID 当作 Seedance 素材引用。

### 批量上传

```bash theme={null}
curl -X POST "$BASE_URL/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./first.png" \
  -F "file=@./last.png" \
  -F "file=@./reference.mp4" \
  -F "agreed=true"
```

批量上传响应包含：

* `upload_batch_id`：本批次 ID。
* `assets`：成功创建的素材列表。
* `items`：逐文件结果；每项包含 `status`，失败项包含 `error`。

批量请求可能出现部分成功。客户端应逐项检查 `items`，不要只根据 HTTP 状态判断所有文件是否成功。

## 4. 从在线地址导入

```bash theme={null}
curl -X POST "$BASE_URL/v1/assets/import" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/reference.png",
    "name": "reference.png",
    "asset_type": "Image",
    "agreed": true
  }'
```

字段说明：

| 字段             | 类型      | 必填 | 说明                                      |
| -------------- | ------- | -- | --------------------------------------- |
| `url`          | string  | 是  | 可访问的 HTTP/HTTPS 素材地址                    |
| `name`         | string  | 否  | 素材名称；未填写时由地址或服务端推断                      |
| `asset_type`   | string  | 否  | `Image`、`Video` 或 `Audio`；未填写时按文件名扩展名识别 |
| `folder_id`    | string  | 否  | 素材所属文件夹 ID                              |
| `storage_mode` | string  | 否  | 使用平台已配置的存储模式                            |
| `agreed`       | boolean | 是  | 传 `true`                                |

在线地址必须能被服务端访问。远程地址失效、扩展名不受支持或下载超时都会导致导入失败。

## 5. 查询和管理素材

### 查询列表

```bash theme={null}
curl "$BASE_URL/v1/assets?p=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"
```

可选参数：

| 参数          | 说明                          |
| ----------- | --------------------------- |
| `p`         | 页码，从 `1` 开始                 |
| `page_size` | 每页数量                        |
| `folder_id` | 只查询指定文件夹；根目录可使用平台返回的根文件夹 ID |

### 查询详情

```bash theme={null}
curl "$BASE_URL/v1/assets/随机assetid" \
  -H "Authorization: Bearer $API_KEY"
```

### 删除和恢复

```bash theme={null}
curl -X DELETE "$BASE_URL/v1/assets/随机assetid" \
  -H "Authorization: Bearer $API_KEY"

curl -X POST "$BASE_URL/v1/assets/随机assetid/restore" \
  -H "Authorization: Bearer $API_KEY"
```

删除后的素材不能继续用于新的 Seedance 请求。需要继续使用时，先恢复素材并确认其状态可用。

### 文件夹

创建文件夹：

```bash theme={null}
curl -X POST "$BASE_URL/v1/assets/folders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Seedance参考素材"}'
```

移动素材：

```bash theme={null}
curl -X PATCH "$BASE_URL/v1/assets/随机assetid/folder" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":"folder_xxxxxxxx"}'
```

## 6. 使用 Asset 调用 Seedance 2.0

### 推荐入口：`POST /v1/videos`

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "让图片中的人物自然优雅地走向镜头，保持人物外貌和服装一致。",
    "images": ["asset://随机图片assetid"],
    "duration": 4,
    "resolution": "480p",
    "ratio": "3:4",
    "generate_audio": true
  }'
```

提交成功后会返回异步任务，例如：

```json theme={null}
{
  "id": "task_xxxxxxxxx",
  "object": "video.generation",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "error": null
}
```

查询任务：

```bash theme={null}
curl "$BASE_URL/v1/videos/task_xxxxxxxxx" \
  -H "Authorization: Bearer $API_KEY"
```

任务状态通常包括 `queued`、`in_progress`、`completed`、`succeeded`、`failed` 和 `cancelled`。建议每 2～5 秒查询一次，不要因为任务尚未完成而重复提交。

### 原生多模态入口：`POST /v1/video/generations`

需要显式声明参考图片角色时，可以使用：

```bash theme={null}
curl -X POST "$BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "保持人物外貌和服装一致，让人物自然地转身并挥手。",
    "content": [
      {
        "type": "image_url",
        "image_url": {"url": "asset://随机图片assetid"},
        "role": "reference_image"
      }
    ],
    "duration": 4,
    "resolution": "480p",
    "ratio": "3:4"
  }'
```

查询时使用同一组路径风格：

```bash theme={null}
curl "$BASE_URL/v1/video/generations/task_xxxxxxxxx" \
  -H "Authorization: Bearer $API_KEY"
```

`prompt` 必须放在请求顶层。不要只把文字写入 `content`。

## 7. 参数和兼容性提示

| 参数               | 说明                                                     |
| ---------------- | ------------------------------------------------------ |
| `model`          | 使用平台模型目录中已开放的 Seedance 2.0 模型名；基础模型名通常为 `seedance-2.0` |
| `prompt`         | 生成描述和对白；放在请求顶层                                         |
| `images`         | 使用 `asset://...` 图片素材 URI                              |
| `content`        | 原生多模态入口使用，可声明素材角色                                      |
| `duration`       | 视频时长，单位为秒；以当前模型能力为准                                    |
| `resolution`     | 例如 `480p`、`720p`；以当前模型能力为准                             |
| `ratio`          | 例如 `16:9`、`3:4`；以当前模型能力为准                              |
| `generate_audio` | 是否生成音频                                                 |

Seedance 2.0 不要传入当前契约未支持的 `frames`、`seed`、`camera_fixed`、`fps`、`motion`、`negative_prompt` 等字段。最终可用的模型、时长、分辨率、比例和素材数量仍以平台模型配置及接口返回为准。

## 8. 通用响应和错误处理

成功响应通常包含：

```json theme={null}
{
  "success": true,
  "data": {}
}
```

常见错误：

| HTTP 状态 | 处理建议                                        |
| ------- | ------------------------------------------- |
| `401`   | 检查 `Authorization: Bearer ...`、API Key 是否有效 |
| `403`   | 检查用户权限、素材库是否开放、是否已同意协议                      |
| `400`   | 检查 `file`、`url`、扩展名、JSON 字段和 `asset_uri`    |
| `404`   | 检查素材 ID、任务 ID 或接口路径                         |
| `413`   | 文件超过平台上传大小限制                                |
| `429`   | 降低上传/查询频率，等待后重试                             |
| `5xx`   | 记录请求 ID 和响应内容，稍后重试；不要盲目重复创建任务               |

上传失败时，先修正文件或参数再重试。Seedance 任务提交成功后，优先轮询原任务；重复提交可能造成重复任务和重复计费。

## 9. Python 示例

项目提供了可复用脚本：[seedance2\_platform.py](/Users/peng/Documents/futoken/docs/examples/seedance2_platform.py)。它会自动上传本地图片，并可提交和轮询 Seedance 任务：

```bash theme={null}
export BASE_URL="https://ai.xihuyun.com"
export API_KEY="sk-替换为你的平台APIKey"

python3 docs/examples/seedance2_platform.py generate \
  --image ./reference.png \
  --prompt '让图片中的人物自然优雅地走向镜头。' \
  --model seedance-2.0 \
  --duration 4 \
  --resolution 480p \
  --ratio 3:4 \
  --wait
```

只上传素材：

```bash theme={null}
python3 docs/examples/seedance2_platform.py upload --image ./reference.png
```

## 10. 使用建议

* 保存上传响应中的 `asset_id` 和 `asset_uri`，不要依赖临时预览 URL。
* 在提交视频任务前，确认素材状态为 `Active` 或接口返回的可用状态。
* 图片、视频、音频分别上传并记录用途，生成请求只传对应的 `asset://` URI。
* 生产环境为 API 请求设置超时、重试上限和任务轮询超时。
* 记录业务侧的任务 ID 与素材 URI，便于定位失败任务；不要记录完整 API Key。