S
Seedance 聚合
视频生成 API 接入指南
请求域名 http://test11.5ghcy.com/sdapi.php?path=/<endpoint>

视频生成 & 过人脸图片 API

本页文档面向对接 sdapi.php 的客户端开发者。覆盖三条主链路:创建视频(POST /v1/videos)、轮询视频任务并获取下载链接(GET /v1/videos/{job_id} & /signed_url)、过人脸图片(POST /v1/image-ai/submit & GET /v1/image-ai/jobs/{job_id})。所有路径均挂在 ?path= query 参数,鉴权使用 Authorization: Bearer sk-...。

OpenAPI Skill: video · image-ai Bearer auth 幂等键:Idempotency-Key 状态轮询

0概述

所有接口都通过同一个请求域名 http://test11.5ghcy.com/sdapi.php,业务路径挂在 query 参数 ?path= 上(需 URL-encode)。请求体为 JSON(裸字节上传接口除外),响应亦为 JSON。鉴权 header 为 Authorization: Bearer sk-...。

本页覆盖的 3 条链路

1 · 创建视频POST /v1/videos→
2 · 轮询视频GET /v1/videos/{id}→
2 · 下载视频GET /v1/videos/{id}/signed_url→
3 · 过人脸POST /v1/image-ai/submit

状态机(视频)

中间态 queued → running → 终态 succeeded 或 failed。只有 succeeded 时 file / download_url 才会返回有效签名链接。

状态机(图片)

中间态 queued → processing → 终态 succeeded 或 failed。

幂等性:POST 提交请带上 Idempotency-Key header(最大 200 字符,按 API key 作用域内去重)。同一 key + 同一 body 重试直接返回原 job_id,不会重复扣费;改 body 会返回 409。

⚙鉴权 & 请求约定

公共 Header

名称类型是否必填说明
Authorizationstring必填格式 Bearer sk-...。API key 与你后台账号绑定;余额/扣费/历史查询均按 key 隔离。
Content-TypestringJSON 请求必填JSON 请求填 application/json。素材统一走 POST /v1/files(JSON + base64),没有裸字节上传接口了。
Idempotency-Keystring推荐≤ 200 字符,作用域为当前 API key。同一 key + 同一 body 重试不会重复扣费;改 body 返回 409。
X-Filenamestring可选裸字节上传时附带原始文件名(仅 image-ai 素材上传链路)。

调用示例

cURL
curl -sS -X POST 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fbalance' \
  -H 'Authorization: Bearer sk-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{}'

响应(成功)

JSON
{
  "balance": 1000,
  "account_type": "credits",
  "ledger": [
    { "delta": -30, "reason": "video",  "job_id": "v_abc", "balance_after": 970, "created_at": 1700000000 }
  ]
}

1创建视频

2026-10-23 起协议换了:旧的「一次 POST /v1/videos 直接带 prompt/model/duration」已经被上游拒绝(未知顶层字段一律 422)。现在必须走 目录 → 报价 → 提交 三步,正文与报价必须逐字相同。

1 · 读目录GET /v1/catalog→
2 · 传素材POST /v1/files→
3 · 报价POST /v1/videos/quote→
4 · 提交POST /v1/videos→
5 · 取片GET /v1/videos/{job_id}

1 · 读目录 · GET /v1/catalog

返回当前模型目录:revision(提交时必须原样带回,有效期约 1 分钟,过期或变更后要重新读)、每个模型的 id / available / input_schema / parameter_schema / combination_schema / x-canvas-inputs。不要凭旧经验猜参数——目录里没有的字段发过去会被拒。

cURL
curl -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fcatalog' \
  -H 'Authorization: Bearer sk-xxxx'

2 · 上传素材 · POST /v1/files

参考素材先传图库换 asset_id。JSON 必须有 name,image_b64 / audio_b64 / video_b64 三选一。图片 ≤ 10 MiB,音视频 ≤ 50 MiB,图库总量 ≤ 250 MiB;同一个 sha256 重复上传会复用同一份。

cURL
curl -sS -X POST 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Ffiles' \
  -H 'Authorization: Bearer sk-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{"name":"ref.png","image_b64":"iVBORw0KGgo..."}'

3 · 报价 · POST /v1/videos/quote

与提交完全相同的正文,返回 quote_id / credits / price_rule_id / pricing_version。报价不扣费。

4 · 提交 · POST /v1/videos

Header是否必填说明
Expected-Quote-Id必填上一步拿到的 quote_id。缺失一律 409 pricing_changed(不扣费);报价过期(目录变了)同样是这个错 —— 重新读目录 + 重新报价再来一轮。
Idempotency-Key必填1–200 字符。同 key + 同正文重放返回原任务(不重复扣费);同 key 换正文 → 409 idempotency_conflict。
字段类型约束说明
model_idstring必填 目录里的 models[].id,原样照抄(例如 seedance-2.5)。
catalog_revisionstring必填 目录返回的 revision,原样带回。
input_modestring必填 按目录的 input_modes:纯文本 text、参考素材 references、首尾帧 frames。
inputobject必填 按目录的 input_schema 填。文本是 {"prompt":"…"};素材按 x-canvas-inputs 映射放进 images / videos / audios,元素形如 {"asset_id":"…","kind":"image"}。
parametersobject必填 按目录的 parameter_schema 填:duration / resolution(目录没声明就别传)/ ratio。
webhook_urlstring可选 终态回调地址(≤ 500 字符)。属于正文和幂等的一部分,重试不能改。

当前模型:以 GET /v1/catalog 返回的 models[] 为准(不同 Key 可见的模型可能不同)。

cURL · 纯文本生成

cURL
# 1) 读目录
REV=$(curl -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fcatalog' \
  -H 'Authorization: Bearer sk-xxxx' | python3 -c 'import json,sys;print(json.load(sys.stdin)["revision"])')

# 2) 报价(正文里带 catalog_revision)
cat > request.json <<EOF
{"model_id":"seedance-2.5","catalog_revision":"$REV","input_mode":"text",
 "input":{"prompt":"少年在雨中的天台回头,霓虹反光打在脸上"},
 "parameters":{"duration":10,"resolution":"720p","ratio":"9:16"}}
EOF
QID=$(curl -sS -X POST 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fvideos%2Fquote' \
  -H 'Authorization: Bearer sk-xxxx' -H 'Content-Type: application/json' \
  --data-binary @request.json | python3 -c 'import json,sys;print(json.load(sys.stdin)["quote_id"])')

# 3) 提交(同一份正文 + Expected-Quote-Id)
curl -sS -X POST 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fvideos' \
  -H 'Authorization: Bearer sk-xxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-task-001' \
  -H "Expected-Quote-Id: $QID" \
  --data-binary @request.json
# → 202 {"id":"db_7e6b…","status":"queued","provider":"main","charged_credits":30}

提交结果未知时不要另开一单:保留原 request.json / quote_id / Idempotency-Key,用同一份正文重放 —— 受理过就返回原任务;也可以用原 Key 查 GET /v1/submissions/{操作编号} 恢复回执(accepted / not_found / closed)。

2轮询 & 下载

视频生成是异步任务,通过轮询 GET /v1/videos/{job_id} 拿到最新状态;状态到达 succeeded 后从响应的 file / download_url 取签名下载链接(10 分钟有效,过期请重新调此接口或单独调 /signed_url)。

轮询 · GET /v1/videos/{job_id}

cURL
curl -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fvideos%2Fdb_7e6b2d88877147c5a17a667675f9f179' \
  -H 'Authorization: Bearer sk-xxxx'

响应字段

字段类型约束说明
idstring必返任务 id,与 URL 中的 {job_id} 一致。
statusenum必返任务状态:queued / running / succeeded / failed。
filestring条件返回succeeded 时为签名下载 URL(绝对或站点相对),600 秒有效;其他状态为空串。
download_urlstring条件返回同 file,便于跨 SDK 兼容。
video_urlstring已废弃始终为空,仅保留字段名兼容。
errorstring条件返回failed 时为错误描述;其他状态为空串。退款金额请以余额账本为准。
retryableboolean恒为 false未提供 retry 接口;重提交(带同一 Idempotency-Key + 同一 body)会返回原任务。
retry_reasonstring可选信息性提示字段,不要作为任务状态或指令使用。
cancelableboolean恒为 false不支持取消。
cancel_reasonstring恒为 "unsupported"——
providerstring必返上游通道(目录里每个模型自带一个)。
provider_statestring必返上游侧状态;submitting / unknown 表示仍在核对,对外 status 还是 running,不要当失败、也不要重新下单。
has_fileboolean必返是否已有可下载成片(succeeded 时应为 true)。
media_statusstring必返成片归档状态(unavailable / ready …)。
refundedboolean必返失败时是否已退回积分,只有 true 才算退过。
progressobject可选进度:message 是当前说明,provider_status 是上游原始状态。

响应(running)

JSON
{
  "id": "db_7e6b2d88877147c5a17a667675f9f179",
  "status": "running",
  "file": "",
  "download_url": "",
  "video_url": "",
  "error": "",
  "retryable": false,
  "retry_reason": "",
  "cancelable": false,
  "cancel_reason": "unsupported"
}

响应(succeeded)

JSON
{
  "id": "db_7e6b2d88877147c5a17a667675f9f179",
  "status": "succeeded",
  "file": "https://cdn.example.com/v_c8d2...mp4?exp=...&sig=...",
  "download_url": "https://cdn.example.com/v_c8d2...mp4?exp=...&sig=...",
  "video_url": "",
  "error": "",
  "retryable": false,
  "retry_reason": "",
  "cancelable": false,
  "cancel_reason": "unsupported"
}

响应(failed)

JSON
{
  "id": "db_7e6b2d88877147c5a17a667675f9f179",
  "status": "failed",
  "file": "",
  "download_url": "",
  "video_url": "",
  "error": "content_policy_violation: prompt contains disallowed content",
  "retryable": false,
  "retry_reason": "submission_rejected",
  "cancelable": false,
  "cancel_reason": "unsupported"
}

下载 · GET /v1/videos/{job_id}/signed_url

仅在 succeeded 后可用。返回一条新的 600 秒有效签名链接,可用于刷新过期链接、写入自己的存储等场景。

cURL
curl -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fvideos%2Fdb_7e6b2d88877147c5a17a667675f9f179%2Fsigned_url' \
  -H 'Authorization: Bearer sk-xxxx'

响应字段

字段类型约束说明
urlstring必返首方下载 URL(绝对或站点相对)。若为相对路径需拼上基址解析,不要无脑前缀。免鉴权。
expires_atinteger必返Unix 秒,发出后 600 秒过期。过期请重新请求新链接。
qualityenum必返preview(预览)或 original(原画质)。

响应

JSON
{
  "url": "/v1/videos/v_c8d2.../file?exp=1700003600&sig=abcdef...",
  "expires_at": 1700003600,
  "quality": "original"
}

轮询建议:建议间隔 3–5 秒;不要并发打同一 job_id(拿到 succeeded 后立刻停)。429 时按响应 header Retry-After 退避(秒)。

3过人脸图片

上传人脸图片,让模型处理后输出。一次提交最多 30 张图,每张独立计费、产生独立 job。响应里逐张返回 receipt(含 ok 与可选 error),HTTP 202 即便包含失败项也算提交成功——请逐项检查 ok 字段。失败的输入不会扣费。

提交 · POST /v1/image-ai/submit

请求字段

字段类型约束说明
images_b64string[]必填 · 1–30 项 PNG / JPEG / WebP 的 base64 或 data URL;每张解码后 ≤ 20 MiB。数组中每个元素创建一个独立 job,按顺序对应响应 items。整个 JSON 请求体也受服务端的请求体大小上限约束。
promptstring|null可选 · ≤ 4000 字符 风格覆盖提示词。省略或留空使用服务默认的「人像彩铅」风格。

cURL · 提交单张

cURL
B64=$(base64 -w0 portrait.png)
curl -sS -X POST 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fimage-ai%2Fsubmit' \
  -H 'Authorization: Bearer sk-xxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: img-batch-001' \
  --data "{
    \"images_b64\": [\"data:image/png;base64,${B64}\"]
  }"

响应(202)

JSON
{
  "batch_id": "ib_a1b2c3d4",
  "price_per_image": 8,
  "items": [
    {
      "id": "img_8f7e6d5c",
      "ok": true,
      "balance": 992
    },
    {
      "id": null,
      "ok": false,
      "error": "insufficient_balance"
    }
  ]
}

响应字段

字段类型约束说明
batch_idstring必返本次提交批次 id,可调 GET /v1/image-ai/batch/{batch_id} 一次性查所有仍保留的 job。
price_per_imageinteger必返 · ≥ 1每张成功图消耗的积分。仅对 ok:true 的项计费。
items[]array必返 · 顺序与入参一致每张输入对应一个 receipt,oneOf:accepted 项必有 id/ok:true/balance;rejected 项 id:null/ok:false/error。

部分失败:HTTP 202 仍可能包含被拒条目。被拒项的 id 固定为 null,ok:false,并在 error 字段写明原因(如 insufficient_balance / invalid_image),不消耗积分且不计入扣费。accepted 项携带 balance(提交后剩余积分)。请逐项检查 ok。

轮询 · GET /v1/image-ai/jobs/{job_id}

逐 job 轮询(不是按 batch 轮询)。状态机:queued → processing → succeeded / failed。succeeded 时 download_url 返回 约 10 分钟有效的首方签名 URL;过期请重新 GET 本接口续期。

cURL
curl -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fimage-ai%2Fjobs%2Fimg_8f7e6d5c' \
  -H 'Authorization: Bearer sk-xxxx'

响应字段

字段类型约束说明
idstring必返图片 job id,与 URL 中的 {job_id} 一致。
statusenum必返状态:queued / processing / succeeded / failed。
credits_chargedinteger必返 · ≥ 0原始预扣积分;失败任务会另行退款(看余额账本)。
errorstring条件返回失败原因;非失败状态为空。
download_urlstring条件返回首方相对签名 URL,约 10 分钟有效;输出未就绪时为空。过期重新 GET 本接口续期。
created_atnumber|null可选创建时间(Unix 秒)。
finished_atnumber|null可选完成时间(Unix 秒);未完成时为 null。

响应(succeeded)

JSON
{
  "id": "img_8f7e6d5c",
  "status": "succeeded",
  "credits_charged": 8,
  "error": "",
  "download_url": "/v1/image-ai/jobs/img_8f7e6d5c/file?exp=1700003600&sig=abcd...",
  "created_at": 1700000000,
  "finished_at": 1700000120
}

下载 · GET /v1/image-ai/jobs/{job_id}/file

支持两种鉴权方式,二选一即可:

  • 带 Authorization: Bearer sk-...,不需要 exp / sig;
  • 把 download_url 里完整的 exp + sig 拼到查询串上,不需要Authorization。

用签名直链时如果同时带 API key 但 exp/sig 不全/失效,服务端会返回 403。两种方式不要缺一半。

cURL
# 方式 A:用 API Key 直接拿
curl -sSO 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fimage-ai%2Fjobs%2Fimg_8f7e6d5c%2Ffile' \
  -H 'Authorization: Bearer sk-xxxx' \
  -o out.png

# 方式 B:用 download_url 里的 exp+sig(免鉴权)
curl -sSO "http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fimage-ai%2Fjobs%2Fimg_8f7e6d5c%2Ffile%3Fexp%3D1700003600%26sig%3Dabcd..." \
  -o out.png

响应

原始图片二进制,Content-Type 按实际字节给出(image/png / image/jpeg / image/webp),私有、不缓存。

批量查询 · GET /v1/image-ai/batch/{batch_id}

提交后返回的 batch_id 可以一次性取回当前仍在保留期内的 jobs(已过期或全部被拒的 batch 返回 404)。

!错误码 & 重试

所有非 2xx 响应体均为统一结构:

JSON
{
  "error": {
    "code": "429",
    "type": "rpm",
    "message": "API key request rate exceeded.",
    "request_id": "req_..."
  },
  "retry_after": 3
}

HTTP 状态码

按端点区分。下表列出本页覆盖的 6 个端点实际返回的状态码:

状态码端点含义 & 建议
200GET /v1/videos/{id} · /signed_url · /image-ai/jobs/{id} · /file · /batch/{id}成功。
202POST /v1/videos · POST /v1/image-ai/submit异步任务已接受;image-ai 可能内含 rejected items,请逐项查 ok。
400POST /v1/videos请求体无法解析或 schema 严重不符(如非 JSON)。
401全部API key 缺失 / 无效 / 禁用(invalid_key)。
402POST /v1/videos积分余额不足(insufficient_balance)。
403全部(除 POST /v1/videos)客户不可用 / 签名直链 exp+sig 不全或失效。
404GET 端点资源不存在 / 已过期 / 不属于当前 key 账号(not_found / submission_deleted)。
409POST /v1/videos · /image-ai/submit · GET /signed_urlidempotency_conflict:同一 key 对应不同 body;或 signed_url 文件尚未就绪。
410POST /v1/videos原始提交已被回收(submission_reclaimed);需用同一 Idempotency-Key + body 重试可恢复。
413POST /v1/videos · /image-ai/submit请求体或上传文件超限(request_body_too_large);网关上限 128 MiB。
422POST /v1/videos · /image-ai/submit · GET /signed_url字段不合法 / 模型退役 / 缺 Idempotency-Key(validation_error)。
429POST /v1/videos · /image-ai/submitRPM / daily_cap / concurrency / queue 超限;读 Retry-After header 或 retry_after 字段(秒)退避。
500全部服务端错误(internal_error);用同一 Idempotency-Key + body 重试可恢复不确定状态。
503POST /v1/videos · GET /signed_url通道临时不可用(含 queue_full / storage_full / account_unavailable);admission 失败不扣费。

error.type 枚举(节选)

validation_error invalid_key insufficient_balance daily_cap concurrency rpm idempotency_in_progress idempotency_conflict invalid_image not_found range_not_satisfiable service_unavailable http_error internal_error submission_reclaimed submission_deleted request_body_too_large account_unavailable

重试原则:对于 5xx / 网络错误 / 429,按指数退避 + 抖动重试;对于 4xx 中的 idempotency_in_progress(425)请 用同一 key + 同一 body 重试;对于 idempotency_conflict(409)必须重新生成 Idempotency-Key。所有响应均带 X-Request-ID header,遇到问题请带上它上报。

文档版本 · 请求域名 http://test11.5ghcy.com/sdapi.php · OpenAPI 字段以服务方实现为准