鉴权与任务生命周期
Partner API 的环境、请求头、异步任务、错误、幂等与最小轮询示例
鉴权与任务生命周期
环境与请求头
| 环境 | Base URL | 用途 |
|---|---|---|
| 正式 | https://ic.xshow.live/api/partner/v1 | 正式业务订单 |
| 开发 | https://dev.ic.xshow.live/api/partner/v1 | 开发验收；使用该环境的 Key |
Authorization: Bearer $PARTNER_API_KEY 用于所有请求。创建任务另外要求 Idempotency-Key: $ORDER_ID 和 Xcamshow-Uid: $XCAMSHOW_UID。后者是调用方当前已鉴权用户 ID，长度不超过 128 且不含空白或控制字符；仅在创建时传递。可选 Xcamshow-Tg-Id 为 1–32 位数字，Xcamshow-Tg-Username 只有同时传 TG ID 才有效。凭据只放服务端；不进入浏览器、URL、日志或仓库。
图片创建 POST /images/edits，视频创建 POST /videos。两者均为 multipart。图片创建必须有 Content-Length，每张最多 30MB，整份 multipart 最多 64MB。不要手动设置缺少 boundary 的 Content-Type。
异步状态机
- 创建后保存响应
id与业务订单号。常见状态pending、completed、failed；不要假定一定存在running或进度百分比。 - 用
POST /images/{id}或POST /videos/{id}查询。任务 ID 与环境、Partner 账号绑定。 - 仅在
completed后GET /images/{id}/content或GET /videos/{id}/content。视频intermediate_image_available=true时可先读/videos/{id}/intermediate，但它不是最终结果。 - 取消使用
POST /images/{id}/cancel或POST /videos/{id}/cancel。取消回执不是 GPU 已停机或退款完成的证明；继续查询终态。
成功创建和查询直接返回任务对象，例如 {"id":"TASK_ID","status":"pending","compute":{"kind":"scheduler","phase":"queued"}}。正常 Proxy 任务响应含 compute，Web 合成的幂等回执可能省略；它不是完成百分比，vram_required_mb 是调度预留估算而非实测峰值。图片完成查询还返回 created（Unix 秒）和 data:[{"url":"..."}]；失败任务可能带 error.message。下载响应是媒体字节，不是 JSON。保存前核对 Content-Type 和媒体有效性。
幂等与网络重试
同一业务订单的重复创建必须复用原幂等键、字段和文件；服务端使用该键关联订单。不同任务使用新键。创建请求网络超时、连接断开或 HTTP 502/503 均不能证明未接单：优先凭已保存的任务 ID 查询；尚无 ID 时用原键和完全相同的请求核对，不另造键盲目提交。409 idempotency_conflict 表示相同键对应的有效请求不同，不能靠循环重试修复。
常见 HTTP 错误
| HTTP / code | 含义 | 处理 |
|---|---|---|
400 idempotency_key_required | 创建缺订单键 | 以稳定业务键重新提交 |
400 partner_user_id_required | 用户归因头缺失或无效 | 核对 Xcamshow-Uid |
400 媒体或参数错误 | 数量、顺序、MIME、prompt 等不合法 | 按功能页修正 |
401 invalid_api_key | Bearer Key 无效 | 核对环境和服务端秘密配置 |
403 model_not_allowed | 当前账户无此模型权限 | 核对公开模型与授权 |
404 | 路径或任务不可见 | 核对环境、账号、任务 ID |
409 idempotency_conflict | 同键不同请求 | 回到原订单；新订单才使用新键 |
409 图片结果未就绪 | 过早下载图片 | 延后查询，不另建任务 |
404 视频结果未就绪 | 过早下载视频或中间图；也可能是任务不存在 | 查询原任务，确认 ID 与账号 |
422 人脸分析错误 | 身份图不符合要求 | 按具体 code 更换输入 |
502/503 | 上游或配置故障 | 保留原任务与错误细节排查 |
入参/鉴权错误通常是 {"code":"...","data":null,"message":"..."}；共享 Proxy 错误可能使用 error 字段。客户端应先按 HTTP 状态判断，再保留完整错误体，不能假定所有响应同一 envelope。
最小轮询示例
# 创建后从 JSON 响应保存 TASK_ID；此处只演示查询，不会再次创建任务。
curl --fail-with-body -X POST "$BASE_URL/videos/$TASK_ID" \
-H "Authorization: Bearer $PARTNER_API_KEY"
# 仅 status=completed 后下载；输出可能是 MP4 或 GIF，应检查响应 Content-Type。
curl --fail-with-body -L "$BASE_URL/videos/$TASK_ID/content" \
-H "Authorization: Bearer $PARTNER_API_KEY" -o result.bin轮询应设有限退避和客户端截止时间；客户端停止轮询不会自动取消服务端任务。图片把上述 /videos/ 换为 /images/。若需要代码级完整视频示例，参阅视频字段总表。