0概述
所有接口都通过同一个请求域名 http://test11.5ghcy.com/sdapi.php,业务路径挂在 query 参数 ?path= 上(需 URL-encode)。请求体为 JSON(裸字节上传接口除外),响应亦为 JSON。鉴权 header 为 Authorization: Bearer sk-...。
本页覆盖的 3 条链路
POST /v1/videos→GET /v1/videos/{id}→GET /v1/videos/{id}/signed_url→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
| 名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| Authorization | string | 必填 | 格式 Bearer sk-...。API key 与你后台账号绑定;余额/扣费/历史查询均按 key 隔离。 |
| Content-Type | string | JSON 请求必填 | JSON 请求填 application/json。素材统一走 POST /v1/files(JSON + base64),没有裸字节上传接口了。 |
| Idempotency-Key | string | 推荐 | ≤ 200 字符,作用域为当前 API key。同一 key + 同一 body 重试不会重复扣费;改 body 返回 409。 |
| X-Filename | string | 可选 | 裸字节上传时附带原始文件名(仅 image-ai 素材上传链路)。 |
调用示例
curl -sS -X POST 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fbalance' \
-H 'Authorization: Bearer sk-xxxx' \
-H 'Content-Type: application/json' \
--data '{}'
响应(成功)
{
"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)。现在必须走 目录 → 报价 → 提交 三步,正文与报价必须逐字相同。
GET /v1/catalog→POST /v1/files→POST /v1/videos/quote→POST /v1/videos→GET /v1/videos/{job_id}1 · 读目录 · GET /v1/catalog
返回当前模型目录:revision(提交时必须原样带回,有效期约 1 分钟,过期或变更后要重新读)、每个模型的 id / available / input_schema / parameter_schema / combination_schema / x-canvas-inputs。不要凭旧经验猜参数——目录里没有的字段发过去会被拒。
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 -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_id | string | 必填 | 目录里的 models[].id,原样照抄(例如 seedance-2.5)。 |
| catalog_revision | string | 必填 | 目录返回的 revision,原样带回。 |
| input_mode | string | 必填 | 按目录的 input_modes:纯文本 text、参考素材 references、首尾帧 frames。 |
| input | object | 必填 | 按目录的 input_schema 填。文本是 {"prompt":"…"};素材按 x-canvas-inputs 映射放进 images / videos / audios,元素形如 {"asset_id":"…","kind":"image"}。 |
| parameters | object | 必填 | 按目录的 parameter_schema 填:duration / resolution(目录没声明就别传)/ ratio。 |
| webhook_url | string | 可选 | 终态回调地址(≤ 500 字符)。属于正文和幂等的一部分,重试不能改。 |
当前模型:以 GET /v1/catalog 返回的 models[] 为准(不同 Key 可见的模型可能不同)。
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 -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fvideos%2Fdb_7e6b2d88877147c5a17a667675f9f179' \
-H 'Authorization: Bearer sk-xxxx'
响应字段
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | string | 必返 | 任务 id,与 URL 中的 {job_id} 一致。 |
| status | enum | 必返 | 任务状态:queued / running / succeeded / failed。 |
| file | string | 条件返回 | succeeded 时为签名下载 URL(绝对或站点相对),600 秒有效;其他状态为空串。 |
| download_url | string | 条件返回 | 同 file,便于跨 SDK 兼容。 |
| video_url | string | 已废弃 | 始终为空,仅保留字段名兼容。 |
| error | string | 条件返回 | failed 时为错误描述;其他状态为空串。退款金额请以余额账本为准。 |
| retryable | boolean | 恒为 false | 未提供 retry 接口;重提交(带同一 Idempotency-Key + 同一 body)会返回原任务。 |
| retry_reason | string | 可选 | 信息性提示字段,不要作为任务状态或指令使用。 |
| cancelable | boolean | 恒为 false | 不支持取消。 |
| cancel_reason | string | 恒为 "unsupported" | —— |
| provider | string | 必返 | 上游通道(目录里每个模型自带一个)。 |
| provider_state | string | 必返 | 上游侧状态;submitting / unknown 表示仍在核对,对外 status 还是 running,不要当失败、也不要重新下单。 |
| has_file | boolean | 必返 | 是否已有可下载成片(succeeded 时应为 true)。 |
| media_status | string | 必返 | 成片归档状态(unavailable / ready …)。 |
| refunded | boolean | 必返 | 失败时是否已退回积分,只有 true 才算退过。 |
| progress | object | 可选 | 进度:message 是当前说明,provider_status 是上游原始状态。 |
响应(running)
{
"id": "db_7e6b2d88877147c5a17a667675f9f179",
"status": "running",
"file": "",
"download_url": "",
"video_url": "",
"error": "",
"retryable": false,
"retry_reason": "",
"cancelable": false,
"cancel_reason": "unsupported"
}
响应(succeeded)
{
"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)
{
"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 -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fvideos%2Fdb_7e6b2d88877147c5a17a667675f9f179%2Fsigned_url' \
-H 'Authorization: Bearer sk-xxxx'
响应字段
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| url | string | 必返 | 首方下载 URL(绝对或站点相对)。若为相对路径需拼上基址解析,不要无脑前缀。免鉴权。 |
| expires_at | integer | 必返 | Unix 秒,发出后 600 秒过期。过期请重新请求新链接。 |
| quality | enum | 必返 | preview(预览)或 original(原画质)。 |
响应
{
"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_b64 | string[] | 必填 · 1–30 项 | PNG / JPEG / WebP 的 base64 或 data URL;每张解码后 ≤ 20 MiB。数组中每个元素创建一个独立 job,按顺序对应响应 items。整个 JSON 请求体也受服务端的请求体大小上限约束。 |
| prompt | string|null | 可选 · ≤ 4000 字符 | 风格覆盖提示词。省略或留空使用服务默认的「人像彩铅」风格。 |
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)
{
"batch_id": "ib_a1b2c3d4",
"price_per_image": 8,
"items": [
{
"id": "img_8f7e6d5c",
"ok": true,
"balance": 992
},
{
"id": null,
"ok": false,
"error": "insufficient_balance"
}
]
}
响应字段
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| batch_id | string | 必返 | 本次提交批次 id,可调 GET /v1/image-ai/batch/{batch_id} 一次性查所有仍保留的 job。 |
| price_per_image | integer | 必返 · ≥ 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 -sS 'http://test11.5ghcy.com/sdapi.php?path=%2Fv1%2Fimage-ai%2Fjobs%2Fimg_8f7e6d5c' \
-H 'Authorization: Bearer sk-xxxx'
响应字段
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | string | 必返 | 图片 job id,与 URL 中的 {job_id} 一致。 |
| status | enum | 必返 | 状态:queued / processing / succeeded / failed。 |
| credits_charged | integer | 必返 · ≥ 0 | 原始预扣积分;失败任务会另行退款(看余额账本)。 |
| error | string | 条件返回 | 失败原因;非失败状态为空。 |
| download_url | string | 条件返回 | 首方相对签名 URL,约 10 分钟有效;输出未就绪时为空。过期重新 GET 本接口续期。 |
| created_at | number|null | 可选 | 创建时间(Unix 秒)。 |
| finished_at | number|null | 可选 | 完成时间(Unix 秒);未完成时为 null。 |
响应(succeeded)
{
"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。两种方式不要缺一半。
# 方式 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 响应体均为统一结构:
{
"error": {
"code": "429",
"type": "rpm",
"message": "API key request rate exceeded.",
"request_id": "req_..."
},
"retry_after": 3
}
HTTP 状态码
按端点区分。下表列出本页覆盖的 6 个端点实际返回的状态码:
| 状态码 | 端点 | 含义 & 建议 |
|---|---|---|
| 200 | GET /v1/videos/{id} · /signed_url · /image-ai/jobs/{id} · /file · /batch/{id} | 成功。 |
| 202 | POST /v1/videos · POST /v1/image-ai/submit | 异步任务已接受;image-ai 可能内含 rejected items,请逐项查 ok。 |
| 400 | POST /v1/videos | 请求体无法解析或 schema 严重不符(如非 JSON)。 |
| 401 | 全部 | API key 缺失 / 无效 / 禁用(invalid_key)。 |
| 402 | POST /v1/videos | 积分余额不足(insufficient_balance)。 |
| 403 | 全部(除 POST /v1/videos) | 客户不可用 / 签名直链 exp+sig 不全或失效。 |
| 404 | GET 端点 | 资源不存在 / 已过期 / 不属于当前 key 账号(not_found / submission_deleted)。 |
| 409 | POST /v1/videos · /image-ai/submit · GET /signed_url | idempotency_conflict:同一 key 对应不同 body;或 signed_url 文件尚未就绪。 |
| 410 | POST /v1/videos | 原始提交已被回收(submission_reclaimed);需用同一 Idempotency-Key + body 重试可恢复。 |
| 413 | POST /v1/videos · /image-ai/submit | 请求体或上传文件超限(request_body_too_large);网关上限 128 MiB。 |
| 422 | POST /v1/videos · /image-ai/submit · GET /signed_url | 字段不合法 / 模型退役 / 缺 Idempotency-Key(validation_error)。 |
| 429 | POST /v1/videos · /image-ai/submit | RPM / daily_cap / concurrency / queue 超限;读 Retry-After header 或 retry_after 字段(秒)退避。 |
| 500 | 全部 | 服务端错误(internal_error);用同一 Idempotency-Key + body 重试可恢复不确定状态。 |
| 503 | POST /v1/videos · GET /signed_url | 通道临时不可用(含 queue_full / storage_full / account_unavailable);admission 失败不扣费。 |
error.type 枚举(节选)
重试原则:对于 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 字段以服务方实现为准