返回账号池接口文档

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.5Seedance 2.54–30 秒480p、720p、1080p总计 50;图/视频/音频 30/10/10支持
seedance-2.0Seedance 2.04–15 秒480p、720p、1080p、4K总计 12;图/视频/音频 9/3/3不支持
seedance-2.0-fastSeedance 2.0 Fast4–15 秒480p、720p总计 12;图/视频/音频 9/3/3不支持
seedance-2.0-miniSeedance 2.0 Mini4–15 秒480p、720p总计 12;图/视频/音频 9/3/3不支持
seedance-1.0-fastSeedance 1.0 Fast2–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.51.8–30.2 秒≤30.2 秒≤30.2 秒
Seedance 2.0 / Fast / Mini1.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,避免参数被静默忽略。

顶层字段类型必填 / 默认约束
promptstring必填去除两端空格后非空,原文最多5000字符
modelstringseedance-2.5使用模型表的服务ID;也接受响应中的upstreamModel
operationstringgenerate仅支持generate
modestringomni_reference建议显式传入下表模式
referencesarray[]素材字段见下一节;受对应模型限制
settingsobject{}仅接受下表5项
settings 字段类型默认约束
durationSecinteger官方5秒按型号最小/最大时长;不能传毫秒、小数或布尔值
resolutionstring720p按型号,Fast/Mini/1 Fast不支持1080p/4K
aspectRatiostring9:16上节列出的7项
generationCountinteger11、2、3、4;一个任务可返回多条成片
audiostringnative仅native;不是开关或音轨URL
mode素材要求
text_to_video不允许参考素材
image_to_video一张图片;工作台使用first_frame角色。1 Fast必须使用first_frame
first_last_frame必须首帧first_frame和尾帧last_frame各一张
omni_referenceimage / 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。上传成功只证明文件可读,不代表它符合所选模型的数量、时长或会员条件。

素材对象

字段要求
roleimage、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字符
statusqueued / running / needs_user / succeeded / failed / cancelled
model模型表中的服务ID
accountaccount-01等槽位ID
from / to带时区ISO时间;建议UTC,例如2026-11-20T00:00:00Z
page正整数,默认1;超末页时返回末页
pageSize6 / 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/poolaccounts、queued、running、lastError、updatedAt
POST /v1/pool/accountsname最多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-optionsaccounts映射与checkedAt;仅包含已同步账号
POST /v1/model-options/syncaccountId必填;读取该账号官方参数卡

账号初始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有效期是两个概念。提供方注册请求不持有账号池全局锁,列表与其他账号可继续响应。