Seedance 接口文档
统一入口提交视频任务,账号池自动分配账号。本文对应当前测试工作台,参数基准核对日期为 2026-11-20。
快速接入
基础地址:https://test.seedance.yingchukeji.com。使用 HTTPS,JSON 正文指定 Content-Type: application/json。
接入顺序:读取模型限制 → 上传参考素材(可选)→ 提交任务 → 查询状态 → 下载成片。
POST /v1/jobs 会触发真实生成并自动确认官方积分报价。仅查询模型、上传文件不会生成视频。202 只表示已接收任务,不表示生成成功。
curl 'https://test.seedance.yingchukeji.com/v1/jobs' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: your-business-job-001' \
--data '{
"model": "seedance-2.0-fast",
"mode": "text_to_video",
"prompt": "清晨阳光照进书店,镜头缓慢向前推进",
"settings": {
"durationSec": 5,
"resolution": "720p",
"aspectRatio": "16:9",
"generationCount": 1,
"audio": "native"
}
}'上例为 Bash。PowerShell 使用 curl.exe,并将 JSON 保存为文件后通过 --data-binary @request.json 提交。示例不会在文档页自动执行。
模型与参数限制
GET /v1/models 或 GET /v1/capabilities 返回5个型号。每个模型包含 id、upstreamModel、durationSec、resolutions、aspectRatios、limits。页面和接口使用同一份模型限制;不支持的组合返回400,不自动换模型。
| model | 型号 | 生成时长(整数) | 清晰度 | 参考数量上限 | 纯音频参考 |
|---|---|---|---|---|---|
| seedance-2.5 | Seedance 2.5 | 4–30 秒 | 480p、720p、1080p | 总计 50;图/视频/音频 30/10/10 | 支持 |
| seedance-2.0 | Seedance 2.0 | 4–15 秒 | 480p、720p、1080p、4K | 总计 12;图/视频/音频 9/3/3 | 不支持 |
| seedance-2.0-fast | Seedance 2.0 Fast | 4–15 秒 | 480p、720p | 总计 12;图/视频/音频 9/3/3 | 不支持 |
| seedance-2.0-mini | Seedance 2.0 Mini | 4–15 秒 | 480p、720p | 总计 12;图/视频/音频 9/3/3 | 不支持 |
| seedance-1.0-fast | Seedance 1.0 Fast | 2–12 秒 | 480p、720p | 仅首尾帧 ≤2 张 | 不支持 |
画幅与默认值
所有当前型号支持 auto、9:16、1:1、3:4、16:9、4:3、21:9。auto 发送给官方时转换为 adaptive,4k 转换为 4K。清晰度大小写兼容。
本服务默认 model=seedance-2.5、resolution=720p、aspectRatio=9:16、generationCount=1、audio=native。省略时长时使用官方默认5秒;建议显式填写。时长按整秒发送,13秒即13000毫秒,不向档位取整。
参考音视频时长
| 型号 | 单项视频 / 音频 | 所有视频时长合计 | 所有音频时长合计 |
|---|---|---|---|
| Seedance 2.5 | 1.8–30.2 秒 | ≤30.2 秒 | ≤30.2 秒 |
| Seedance 2.0 / Fast / Mini | 1.8–15.2 秒 | ≤15.2 秒 | ≤15.2 秒 |
| Seedance 1 Fast | 不支持 | 不适用 | 不适用 |
这是参考素材时长,不是生成视频时长。视频、音频分别累加;例如2.0的两段10秒视频合计20秒,不能提交。数量总上限和各类型上限必须同时满足。
会员与账号权限
2.5、2.0、Fast、Mini 模型标记为 Pro;720p 标记为 Pro;2.5 的1080p、2.0 的1080p/4K标记为 Ultra;时长达到10秒时标记 Pro。10秒是会员条件的起点,不是生成时长下限。
以上是公开限制基准,不包含任何账号已开通会员的承诺。POST /v1/model-options/sync 传入 {"accountId":"account-02"} 可读取该账号官方参数卡,不生成视频。GET /v1/model-options 返回已同步参数。会员 active 仅属于对应账号。
实际提交官方前,服务为所分配账号自动读取参数卡(缓存最多5分钟),校验型号、清晰度、时长、素材与会员状态。读取失败停止提交,不绕过校验。重启后缓存清空。
官方来源:CapCut https://www.capcut.com/api/external_mcp 的工具契约与 prepare_for_video_generation 参数卡。Seedance 2.5 Flash 未在当前官方MCP契约中开放,不能映射为其他型号。
创建视频任务
POST /v1/jobs → 202 application/json。只接受下面列出的顶层字段和 settings 字段;未知字段返回400,避免参数被静默忽略。
| 顶层字段 | 类型 | 必填 / 默认 | 约束 |
|---|---|---|---|
| prompt | string | 必填 | 去除两端空格后非空,原文最多5000字符 |
| model | string | seedance-2.5 | 使用模型表的服务ID;也接受响应中的upstreamModel |
| operation | string | generate | 仅支持generate |
| mode | string | omni_reference | 建议显式传入下表模式 |
| references | array | [] | 素材字段见下一节;受对应模型限制 |
| settings | object | {} | 仅接受下表5项 |
| settings 字段 | 类型 | 默认 | 约束 |
|---|---|---|---|
| durationSec | integer | 官方5秒 | 按型号最小/最大时长;不能传毫秒、小数或布尔值 |
| resolution | string | 720p | 按型号,Fast/Mini/1 Fast不支持1080p/4K |
| aspectRatio | string | 9:16 | 上节列出的7项 |
| generationCount | integer | 1 | 1、2、3、4;一个任务可返回多条成片 |
| audio | string | native | 仅native;不是开关或音轨URL |
| mode | 素材要求 |
|---|---|
| text_to_video | 不允许参考素材 |
| image_to_video | 一张图片;工作台使用first_frame角色。1 Fast必须使用first_frame |
| first_last_frame | 必须首帧first_frame和尾帧last_frame各一张 |
| omni_reference | image / video / audio;省略素材等价纯提示词输入;1 Fast不支持普通参考 |
不能指定 accountId。不支持 seed、negative_prompt、fps、额外相机开关、export 或 intelligent_edit,也不承诺官网网页独有功能可通过官方接口调用。
上传与参考素材
上传本地文件
POST /v1/uploads 使用原始二进制正文,不是 multipart。请求头:Content-Type: application/octet-stream、X-File-Name: URL编码文件名、Content-Length。单文件大于0且≤200 MiB(209715200字节),这是本服务限制。
支持 PNG/JPG/JPEG/WebP 图片、MP4/MOV/WebM 视频、MP3/WAV/M4A/OGG/FLAC 音频。服务检查真实媒体类型;伪造扩展名或无法解析的文件返回400。
{
"id": "<上传标识>.mp4",
"name": "参考视频.mp4",
"bytes": 1200000,
"mimeType": "video/mp4",
"mediaType": "video",
"role": "video",
"durationMs": 5000,
"width": 1280,
"height": 720,
"url": "https://test.seedance.yingchukeji.com/v1/uploads/<上传标识>.mp4"
}返回201。图片返回宽高;音视频返回探测到的毫秒时长。将返回的 url 传入 references。上传成功只证明文件可读,不代表它符合所选模型的数量、时长或会员条件。
素材对象
| 字段 | 要求 |
|---|---|
| role | image、video、audio、first_frame、last_frame;用途须与真实媒体类型一致 |
| url | 测试机可访问的HTTP(S)文件地址;优先使用本服务上传返回URL |
| name | 建议提供真实扩展名的文件名;提示词可用@文件名(不含扩展名)引用 |
| originalUrl | 可选;提供时优先读取此地址;仍须为HTTP(S) |
首帧/尾帧各最多一张;尾帧需要同时提供首帧;首尾帧不可混合普通参考。1 Fast允许两张首尾帧,不受普通参考图片数量0的限制。
{
"model": "seedance-2.0",
"mode": "first_last_frame",
"prompt": "从首帧自然过渡到尾帧,镜头缓慢向前移动",
"references": [
{"role": "first_frame", "name": "起点.png", "url": "https://your-assets.example/start.png"},
{"role": "last_frame", "name": "终点.png", "url": "https://your-assets.example/end.png"}
],
"settings": {"durationSec": 5, "resolution": "720p", "aspectRatio": "16:9"}
}替换示例素材地址。本服务已上传文件在接收任务前检查时长;外部直链在后台读取文件后检查。全部素材在上传CapCut、提交生成之前检查类型、单项时长和总时长。失败进入 needs_user 并给出原因,不自动重发。
响应与任务状态
创建响应示例(标识为占位符):
{
"id": "job_<32位十六进制>",
"status": "queued",
"accountId": null,
"needsUser": false,
"officialJobId": null,
"officialTaskId": null,
"officialCredits": null,
"videoUrl": null,
"artifacts": []
}响应也包含 request、createdAt、updatedAt、events。时间戳为Unix秒。使用 id 查询本服务;不要把 officialJobId 或 officialTaskId 代入本地任务路径。
| status | 含义 | 处理 |
|---|---|---|
| queued | 等待可用账号或容量 | 查询原任务 |
| running | 读取/上传/提交/官方生成/结算 | 结合message显示进度;progress不是连续百分比 |
| needs_user | 授权、会员、素材或未知提交结果 | 核查message,处理原任务,禁止盲目换号重发 |
| succeeded | 已取得生成结果 | 读取artifacts,逐条下载 |
| failed | 明确失败 | 读取message和官方失败原因 |
| cancelled | 本地等待取消 | 不代表上游退款 |
officialCredits 是报价,实际扣费以原官方记录 actual_credits 为准;settled=true 表示上游生成和结算结束。
查询、分页与下载
GET /v1/jobs/{job_id} 返回200任务快照。建议每3–5秒查询一次,网络失败适度退避。
GET /v1/tasks 先筛选、后分页,按创建时间倒序。
| 查询参数 | 约束 |
|---|---|
| q | 提示词、本地任务ID、官方任务ID关键词,最多200字符 |
| status | queued / running / needs_user / succeeded / failed / cancelled |
| model | 模型表中的服务ID |
| account | account-01等槽位ID |
| from / to | 带时区ISO时间;建议UTC,例如2026-11-20T00:00:00Z |
| page | 正整数,默认1;超末页时返回末页 |
| pageSize | 6 / 12 / 24 / 48,默认12 |
响应包含 count(筛选命中)、total(全量)、page、pageSize、pages、summary、jobs、updatedAt。无结果时pages=1,jobs=[]。
| 成片路径 | 行为 |
|---|---|
| GET /v1/jobs/{job_id}/artifacts/{index} | 307跳转官方视频地址,用于预览;index从0开始 |
| GET /v1/jobs/{job_id}/download/{index} | 附件下载,支持单段Range;按artifacts数组逐条下载 |
| GET /v1/jobs/{job_id}/artifact | 首个成片预览的兼容入口 |
成片不会永久保存到本服务。官方签名链接可能过期,过期下载返回502,应及时保存文件。
幂等、调度与恢复
Idempotency-Key 建议必传:1–128位,字母、数字、下划线、点、冒号或连字符。同键同正文返回原任务;同键不同正文返回400。省略字段、修改模型别名或数组顺序都会影响正文摘要。
账号池只分配已连接、启用、未满容量的账号,先比较任务数/容量,再比较最近分配时间。绑定后不自动换号;没有可用账号就排队。未知结果和待处理任务保留原归属,不能靠重发释放占用。
| 操作 | 限制 |
|---|---|
| POST /v1/jobs/{job_id}/recover,正文{} | 仅恢复已有officialJobId的原任务查询;不重新生成 |
| POST /v1/jobs/{job_id}/cancel,正文{} | 仅取消尚未开始处理的本地等待;不是上游生成取消 |
| GET /v1/official/jobs/{official_id} | 查看原官方记录、结算状态及实际积分 |
| POST /v1/official/jobs/{official_id}/poll,正文{} | 使用绑定的原账号查询上游 |
提交超时不等于失败。有任务ID先查询;没有任务ID,用原幂等键和原正文重试,不能直接换新键。
账号与参数管理
| 方法与路径 | 请求 / 返回 |
|---|---|
| GET /v1/pool | accounts、queued、running、lastError、updatedAt |
| POST /v1/pool/accounts | name最多40字符,capacity为1–4整数;返回201及accountId |
| POST /v1/pool/accounts/{account_id} | 更新name、enabled(boolean)、capacity;不接受其他字段 |
| POST /v1/pool/accounts/{account_id}/auth/start | 正文{};返回authorizationUrl和expiresAt;有效期内重复调用返回同一链接,restart=true仅重新开始未连接槽位的授权 |
| GET /v1/model-options | accounts映射与checkedAt;仅包含已同步账号 |
| POST /v1/model-options/sync | accountId必填;读取该账号官方参数卡 |
账号初始5个,可动态增加至100槽位,不需要重启。并发容量是本服务调度额度,不保证官方并发、余额或会员权益。暂停只停止新分配,不打断旧任务。
connected 表示存在授权令牌;active 是已绑定非终态任务数;needsUser 是其中待处理数;enabled 表示是否参与分配。
登录电脑先运行工作台提供的 /pool-connect.cmd(Windows启动器,需要Python3)或 /pool-connect.py。接收器只监听127.0.0.1:8788,保持运行直到手动关闭,不再15分钟自动退出。工作台先检查接收器就绪,再显示官方授权链接。新增其他真实账号请复制链接到新的无痕窗口登录;完成后关闭所有无痕窗口再连接下一个。服务令牌仅在内存;重启后需重新连接原账号,任务与槽位配置保留。不能将有历史任务的槽位接为另一个真实账号。
错误与健康检查
错误格式:{"detail":"可操作的错误原因"}。参数错误在提交前返回400;后台读取直链或上游拒绝发生在接收后,通过任务status/message反馈。
| HTTP状态 | 含义 / 处理 |
|---|---|
| 200 | 查询或更新成功 |
| 201 | 素材上传或账号槽位创建成功 |
| 202 | 已接收任务,或命中原幂等任务 |
| 307 | 成片预览重定向 |
| 400 | 参数超限、不支持字段、文件无效、幂等冲突或账号状态错误 |
| 404 | 任务或资源不存在 |
| 502 | 官方成片无法下载或链接已失效 |
| 503 | 上传/存储/网络操作中断,先核查实际结果 |
GET /v1/health 返回健康状态、模式、持久化、账号数及队列数。还需结合 /v1/pool.lastError 和实际账号连接判断业务是否可执行。代理可能返回HTML错误页,请先检查Content-Type再解析JSON。
部署与验证边界
这是自部署桥接服务,当前没有独立API Key、用户登录和租户隔离。CapCut OAuth用于上游授权,不是本服务访问鉴权。管理写请求检查Host/Origin;同源检查不能代替身份验证。
已实现型号参数、素材内容与时长检查、账号独立授权、幂等提交、任务归属、分页查询和下载。模型限制来自官方参数卡与公开契约;不代表已对所有型号和组合完成付费出片验收。
没有余额自动调度、账号真实身份去重、永久成片存储或自动清理素材。不要依赖未文档化的旧浏览器模式端点。
授权恢复(2026-11-21):等待期间可点“继续授权”重新打开同一链接;“重新开始”只使该未连接槽位的旧链接失效,不改变已连接槽位。官方OAuth state仍为10分钟,接收器运行时间与state有效期是两个概念。提供方注册请求不持有账号池全局锁,列表与其他账号可继续响应。