Seedance - Mintlify Starter Kit

本文面向通过西湖云统一网关调用 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. 基础信息

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

BASE_URL=https://ai.xihuyun.com
API_KEY=sk-xxxxxxxxxxxxxxxx

鉴权

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

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 文生视频

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
  }'

典型提交响应：

{
  "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 轮询任务

curl "$BASE_URL/v1/videos/task_wjlMGb4cfEgrqq7oubXjWPdXPmSjfRfe" \
  -H "Authorization: Bearer $API_KEY"

建议客户端每隔 2～5 秒查询一次，直到 status 变为 completed 或 failed。完成响应示例：

{
  "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 下载视频内容

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

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[]：

{
  "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 秒及合计时长限制

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

{
  "type": "image_url",
  "image_url": { "url": "asset://随机图片assetid" },
  "role": "reference_image"
}

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

3.3 旧版 `metadata` 兼容写法

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

{
  "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。

示例：

{
  "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 个

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

{
  "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 指定：

{
  "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" }`

示例：

{
  "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：

{
  "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 风格错误结构：

{
  "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：

export BASE_URL="https://ai.xihuyun.com"
export API_KEY="sk-替换为你的平台APIKey"

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

Authorization: Bearer <API_KEY>

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

POST /v1/assets 上传素材。
从响应中读取 data.asset_uri，例如 asset://随机assetid。
将该 URI 放入 Seedance 2.0 的 images 或 content 字段。
使用返回的任务 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. 上传本地素材

请求

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`

单文件成功响应

{
  "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 素材引用。

批量上传

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. 从在线地址导入

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. 查询和管理素材

查询列表

curl "$BASE_URL/v1/assets?p=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

可选参数：

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

查询详情

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

删除和恢复

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 请求。需要继续使用时，先恢复素材并确认其状态可用。

文件夹

创建文件夹：

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

移动素材：

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`

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
  }'

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

{
  "id": "task_xxxxxxxxx",
  "object": "video.generation",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "error": 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`

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

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"
  }'

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

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. 通用响应和错误处理

成功响应通常包含：

{
  "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。它会自动上传本地图片，并可提交和轮询 Seedance 任务：

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

只上传素材：

python3 docs/examples/seedance2_platform.py upload --image ./reference.png

10. 使用建议

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

​平台约定

​1. 基础信息

​鉴权

​接口列表

​2. 快速开始

​2.1 文生视频

​2.2 轮询任务

​2.3 下载视频内容

​3. 请求参数

​3.1 通用字段

​3.2 结构化参考素材

​3.3 旧版 metadata 兼容写法

​4. Seedance 模型与能力限制

​4.1 当前内置模型目录

​4.2 Seedance 1.x / 1.5 与 2.0

​4.3 Seedance 2.5

​首帧和尾帧

​Seedance 2.5 专用字段

​5. 状态和响应字段

​5.1 状态值

​5.2 标准响应字段

​6. 错误处理

​6.1 Seedance 参数校验错误

​6.2 鉴权和权限错误

​7. 调用建议

​Asset 素材库 API（Seedance 2.0）

​1. 快速开始

​2. 接口概览

​3. 上传本地素材

​请求

​单文件成功响应

​批量上传

​4. 从在线地址导入

​5. 查询和管理素材

​查询列表

​查询详情

​删除和恢复

​文件夹

​6. 使用 Asset 调用 Seedance 2.0

​推荐入口：POST /v1/videos

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

​7. 参数和兼容性提示

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

​9. Python 示例

​10. 使用建议

平台约定

1. 基础信息

鉴权

接口列表

2. 快速开始

2.1 文生视频

2.2 轮询任务

2.3 下载视频内容

3. 请求参数

3.1 通用字段

3.2 结构化参考素材

3.3 旧版 `metadata` 兼容写法

4. Seedance 模型与能力限制

4.1 当前内置模型目录

4.2 Seedance 1.x / 1.5 与 2.0

4.3 Seedance 2.5

首帧和尾帧

Seedance 2.5 专用字段

5. 状态和响应字段

5.1 状态值

5.2 标准响应字段

6. 错误处理

6.1 Seedance 参数校验错误

6.2 鉴权和权限错误

7. 调用建议

Asset 素材库 API（Seedance 2.0）

1. 快速开始

2. 接口概览

3. 上传本地素材

请求

单文件成功响应

批量上传

4. 从在线地址导入

5. 查询和管理素材

查询列表

查询详情

删除和恢复

文件夹

6. 使用 Asset 调用 Seedance 2.0

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

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

7. 参数和兼容性提示

8. 通用响应和错误处理

9. Python 示例

10. 使用建议