SeeDance Videos Generation API 对接说明
内容提要
本文介绍SeeDance视频生成API的对接方法。用户需在Ace Data Cloud获取API Token，通过输入提示词、模型、分辨率等参数生成视频。支持文生视频、图生视频（首尾帧）、角色与音视频多模态参考，以及Seedance 2.5的视频编辑与延长功能。提供异步回调、错误处理及代码示例，帮助开发者快速集成。
延伸解读
模型选择与能力差异
Seedance 系列模型按版本划分，能力差异明显。1.x 系列仅支持文生视频或图生视频（首尾帧），不支持音频生成；1.5 Pro 开始支持 generate_audio；2.0 系列引入角色与音视频多模态参考，但分辨率上限因型号而异（Fast/Mini 最高 720p，Standard 最高 4k）；2.5 则支持视频编辑、延长、纯音频参考及更多素材。开发者应根据任务需求（如是否需要角色一致性、编辑功能、分辨率）选择合适的模型，避免为简单任务选用高配模型造成资源浪费。
参数校验与错误排查
API 提供两种参数传递方式：顶层字段（强校验）与内联参数（弱校验）。推荐使用顶层字段，因为参数错误时会返回明确提示，便于快速定位问题；内联参数填写有误时自动使用默认值，可能导致生成结果与预期不符且难以察觉。此外，注意 image_url 必须使用对象格式，否则返回 400 错误。合理利用错误码（如 400、401、429）可快速判断问题类型，提高调试效率。
异步模式与任务管理
视频生成耗时约 1-2 分钟，同步请求会长时间占用连接。API 提供两种异步方式：设置 callback_url 接收回调，或设置 async 为 true 后轮询任务查询接口。回调结果中包含与请求一致的 task_id，可用于关联任务。开发者应根据自身架构选择合适方式：有稳定回调地址时用回调，否则用轮询。同时注意设置合理的 execution_expires_after 超时时间，避免任务悬挂。
素材合规与限制
使用角色参考（reference_image）或音视频参考时，必须确保素材为自有或已获授权，且真人素材需符合模型要求。多模态参考有数量与时长限制：图片最多 9 张，音频和视频各最多 3 条且总时长不超过 15 秒。参考图片建议使用清晰正脸照以提高相似度。违反限制会导致任务失败，并返回可定位的错误。开发者应提前检查素材格式与时长，避免无效请求。
Q&A
如何获取 SeeDance 视频生成 API 的 Token？
需要先到 Ace Data Cloud 控制台注册或登录，然后获取 API Token。一个 Token 即可调用平台所有服务，首次申请会赠送免费额度。
SeeDance 视频生成 API 支持哪些模型？
支持 Seedance 1.x 系列（如 doubao-seedance-1-0-pro-250528）、Seedance 2.0 系列（如 doubao-seedance-2-0-260128）、Seedance 2.5（doubao-seedance-2-5-260628）。不同系列支持的功能和参数不同。
如何通过 SeeDance API 生成带音频的视频？
在请求体中设置 generate_audio 为 true，并选择支持该参数的模型（Seedance 1.5 Pro 或 2.x 系列）。1.0 系列不支持此参数。
SeeDance 2.5 的视频编辑和延长功能如何使用？
使用 doubao-seedance-2-5-260628 模型，并在 content 中传入 reference_video。编辑时需设置 omni_reference_task_type 为 edit，且 ratio 必须为 adaptive，duration 为 -1；延长时设置为 extend，ratio 为 adaptive，duration 可为 4-30 或 -1。
图生视频首尾帧如何设置？
在 content 数组中包含两个 image_url 类型的对象，分别设置 role 为 first_frame 和 last_frame，并提供一个 text 类型的提示词。image_url 必须使用对象格式，如 {"url": "https://..."}。
Seedance 2.0 的角色参考功能与 1.x 的首尾帧有何区别？
Seedance 2.0 支持 reference_image，可保持人物身份一致，但场景和动作由提示词决定；1.x 使用 first_frame/last_frame 指定视频首尾帧，视频从首帧开始运动。二者不能混用。
SeeDance API 的异步回调机制是怎样的？
在请求中设置 callback_url，API 会立即返回 task_id，任务完成后平台会将结果以 POST JSON 形式发送到 callback_url，结果中包含相同的 task_id 用于关联。
调用 SeeDance API 时常见的错误码有哪些？
常见错误码包括：400 token_mismatched（参数错误）、401 invalid_token（Token无效）、429 too_many_requests（请求过多）、500 api_error（服务器内部错误）。
