XCamShow Partner 图片 API（v2）

历史 v1 文档保留升级前原文。本次视频链路切换不改变以下图片模型和路径。

XCamShow 只从服务端使用 Bearer Key 调用，不使用浏览器 Cookie。当前开放图片脱衣、姿势切换、BFS 换头和 Klein 换头 4 个业务模型。

Base URL: https://ic.xshow.live/api/partner/v1
Authorization: Bearer <XCAMSHOW_API_KEY>

接口

四个图片模型

四个模型统一通过 POST /images/edits 创建，任务生命周期统一使用 /images/{task_id}。Partner 调用方不直接访问内部 /v1/toolsbox-pose-edit/、其他 Scheduler 路径或 GPU 地址。

image-pose 会先生成姿势图，再用同一张输入图作为身份参考执行 Klein 精准换脸。该身份恢复阶段只由 Partner 服务端签名路由启用；画布的普通 Proxy 姿势编辑不会进入换脸或换头工作流。

姿势编辑独立入口（候选，尚未部署验证）

POST /api/partner/v1/toolsbox-pose-edit/ 复用与 /videos 相同的 Bearer Key 和 Partner 账号绑定，不要求浏览器 Cookie。请求仍需 Idempotency-Key，使用下述 multipart 字段；model 可以省略，提供时仅接受 image-pose。返回值、租户归属、计费和 /images/{task_id} 系列任务接口均与统一图片入口一致。该入口是 Web Partner 适配层，不直接开放内部 Scheduler。

创建请求使用 multipart；重复的 image 字段按出现顺序解释：

Klein 精准换头

head-swap 使用 Klein 换头后接 SeedVR2 放大，与 head-swap-bfs 是两个独立模型；此入口不启用 Pro 的 Krea2 融合阶段。不要交换两张图片的顺序。head-swap-pro 尚未开放给 Partner。

# Klein 换头：图片 1 是目标底图，图片 2 是头部身份图
curl -X POST "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $XCAMSHOW_API_KEY" \
  -H "Idempotency-Key: $XCAMSHOW_ORDER_ID" \
  -F "model=head-swap" \
  -F "image=@target.png;type=image/png" \
  -F "image=@head.png;type=image/png" \
  -F "prompt=保持目标图身体、服装、姿势和背景，自然替换完整头部" \
  -F "seed=12345"

head-swap-bfs 内置 auto

接口名、公开模型名和参数不变：继续调用 POST /images/edits，传 model=head-swap-bfs 和两张 image。 自动判断在服务端完成，无需新增 auto 字段。

仅分析第 2 张 image：头部身份参考图，第 1 张仍为目标底图，图片顺序保持不变。身份参考图额外限制为 2500 万像素，先按 EXIF 修正方向，再等比例缩小进行检测。

服务端使用人脸专用 YOLOv8 权重与姿态检测。当前 head-reference-v2 规则：可靠人脸置信度至少 0.5；人脸框面积占整图不超过 50%（含 50%）走 Klein，超过 50% 走 BFS。姿态检测结果仅用于诊断，不再作为 Klein 路由的硬条件。检测阈值是服务端配置，不新增调用参数，也不等同于生成效果保证。

自动选择在计费和任务提交前完成，实际执行模型与计费模型一致。首次路由结果持久化，同一 Idempotency-Key 的重试保持原链路；更改图片、提示词或 seed 后复用原键返回 409 idempotency_conflict。升级前已创建的任务继续沿用原计费模型。分析服务不可用时返回 503 reference_analyzer_unavailable，不静默提交到其他模型。

head-swap 仍保留为显式指定 Klein 的入口；head-swap-pro 不参与此次 auto。查询、下载、取消和原有鉴权方式不变。

# 自动换头：图片 1 是目标底图，图片 2 是头部身份参考图
curl -X POST "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $XCAMSHOW_API_KEY" \
  -H "Idempotency-Key: $XCAMSHOW_ORDER_ID" \
  -F "model=head-swap-bfs" \
  -F "image=@target.png;type=image/png" \
  -F "image=@head.png;type=image/png" \
  -F "prompt=保持目标图身体、服装、姿势、镜头和背景，自然替换头部身份"

# 图片脱衣：第 1 张是目标图，第 2 张身份参考可选
curl -X POST "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $XCAMSHOW_API_KEY" \
  -H "Idempotency-Key: $XCAMSHOW_ORDER_ID" \
  -F "model=image-undress" \
  -F "image=@target.png;type=image/png" \
  -F "prompt=保持人物身份、姿势、构图和背景，执行服装编辑"

# 姿势切换
curl -X POST "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $XCAMSHOW_API_KEY" \
  -H "Idempotency-Key: $XCAMSHOW_ORDER_ID" \
  -F "model=image-pose" \
  -F "image=@source.png;type=image/png" \
  -F "prompt=change the pose while preserving identity and background" \
  -F "lora=krea2/sex/cowgirl.safetensors" \
  -F "seed=12345"

服务端固定映射

Klein 与 BFS 换头均严格按 multipart 中两张 image 的出现顺序解释；脱衣允许 1–2 张图；姿势切换只允许 1 张图并要求合法 LoRA。任一图片均不得超过 30MB，整个 multipart 不得超过 64MB。

创建和查询响应直接返回任务对象，常见状态为 pending、completed 和 failed。完成后下载：

curl -X POST -H "Authorization: Bearer $XCAMSHOW_API_KEY" "$BASE_URL/images/$TASK_ID"
curl -L -H "Authorization: Bearer $XCAMSHOW_API_KEY" "$BASE_URL/images/$TASK_ID/content" -o result.png

Idempotency-Key 应使用 XCamShow 订单号；同一次创建的网络重试必须复用原值，新任务必须使用新值。Key 不得放入 URL、日志、浏览器或代码仓库。XCamShow 不接触内部 Scheduler 地址、工作流节点 ID、GPU 节点或内部服务 Token。