Partner BFS 自动换头的用途、输入顺序、请求字段、示例、任务查询和错误处理

BFS 自动换头 API

两图换头；服务端仅分析第 2 张身份图的人脸占比，自动选择 BFS 或 Klein 链路，公开模型名不变。

项目	值
公开模型	`head-swap-bfs`
创建接口	`POST /images/edits`
鉴权	Bearer API Key，服务端调用
任务类型	异步；创建返回任务对象及 `id`

调用前准备

正式 Base URL：https://ic.xshow.live/api/partner/v1；开发验收：https://dev.ic.xshow.live/api/partner/v1。两环境的 Key 和任务 ID 不混用。
仅由服务端发送 Authorization: Bearer $PARTNER_API_KEY。创建时还需 Idempotency-Key: $ORDER_ID 与 Xcamshow-Uid: $XCAMSHOW_UID；后者必须是当前已鉴权 XCamShow 用户 ID，不是 IC 账户 ID。可选归因头 Xcamshow-Tg-Id（1–32 位数字）及 Xcamshow-Tg-Username（仅与 TG ID 同时传）。
同一订单网络重试保持幂等键、文件、字段完全一致；新订单换新键。不要传内部模型、工作流路径、供应商 Key 或 GPU 地址。
请求体为 multipart/form-data；让 HTTP 客户端自动设置带 boundary 的 Content-Type。示例中的 $ORDER_ID、$XCAMSHOW_UID、文件名均须替换。

输入语义

第 1 张 image 为目标底图（保留身体、服装、背景）；第 2 张为头部身份参考图。交换顺序会改变语义。

创建请求字段

字段	类型	必填	说明
`model`	string	是	固定 `head-swap-bfs`
`image`	重复文件	是	恰好 2 张，目标底图在前
`prompt`	string	是	描述希望保留的目标图内容
`seed`	整数文本	否	0 到 2^63-1

图片 MIME 仅支持 image/jpeg、image/png、image/webp、image/bmp；每张最多 30MB，整个请求最多 64MB，创建时需有效 Content-Length。prompt 对全部图片模型都是必填。

cURL：创建任务

export BASE_URL="https://ic.xshow.live/api/partner/v1"
curl --fail-with-body -X POST "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Idempotency-Key: $ORDER_ID" \
  -H "Xcamshow-Uid: $XCAMSHOW_UID" \
  -F "model=head-swap-bfs" \
  -F "image=@target.png;type=image/png" \
  -F "image=@head.png;type=image/png" \
  -F "prompt=保持目标图的身体、服装和背景，自然替换头部"

此示例只展示一种输入模式。不要手工设置 multipart Content-Type；curl -F 会生成 boundary。保存创建响应中的 id；客户端超时不代表服务器未受理。

创建回执与结果示例

创建成功返回任务对象，保存 id，不从 url 猜测任务 ID。以下是结构示例，不是实际任务或保证出现的全部字段：

{"id":"TASK_ID","status":"pending"}

查询到 {"id":"TASK_ID","status":"completed"} 后，再请求 GET /images/TASK_ID/content。若状态为 failed，保留响应中的 error.message 与原订单号排查；不要将 HTTP 200 的查询响应当作媒体文件。正常任务查询包含 compute，url 可能不存在；两者均不作为完成判据。

执行和结果边界

身份图额外上限为 2500 万像素；按 EXIF 修正方向后检测。可靠单脸面积超过整图 50% 走 BFS，等于或低于 50% 走 Klein；无可靠脸或多可靠脸返回 422。自动路由在提交与计费前完成，同一幂等键重试保留首次路由结果。

查询、下载和取消

操作	HTTP	路径	时机
查询	`POST`	`/images/{id}`	创建回执取得 `id` 后轮询；不是 `GET`
下载	`GET`	`/images/{id}/content`	`status=completed` 后，以响应 `Content-Type` 决定后缀
取消	`POST`	`/images/{id}/cancel`	不再需要结果时请求；继续查询最终状态

所有操作仍须 Bearer Key。典型状态为 pending、completed、failed；创建、查询返回任务对象，不要假定响应有 data 外壳。创建超时不等于未接单，按原幂等键核对，不要换键重复扣费。完整响应与错误策略见任务生命周期。

常见错误及处理

422 reference_face_not_found / reference_multiple_faces：更换清晰单人身份图；503 reference_analyzer_unavailable：保留原键重试；409 idempotency_conflict：请求与原订单不一致。
400 idempotency_key_required：补业务订单键；400 partner_user_id_required：补有效的 Xcamshow-Uid；401 invalid_api_key：核对当前环境 Key。
403 model_not_allowed：此账号未开放模型；409 idempotency_conflict：相同键的有效请求发生变化，先核对原订单。
404：任务不存在或不属于该 Partner；409 结果未就绪：继续查询原任务。502/503：保留原任务 ID、原幂等键和原始错误以排查，不盲目换键重发。

示例任务 ID、文件名和提示词是演示值，不代表实际执行或效果验收。参考阿里云万相视频 API 文档与Qwen Image API 文档的分节形式；本页字段以 Partner 实际接口为准，不继承百炼原生 Endpoint 或参数。

BFS 自动换头 API

On this page