Partner 视频换脸的用途、输入顺序、请求字段、示例、任务查询和错误处理

视频换脸 API

把身份图中的面部身份应用到源视频；支持上传源视频或选择受控模板。公开别名 faceswap 会归一到本模型。

项目	值
公开模型	`video-face-swap`
创建接口	`POST /videos`
鉴权	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、文件名均须替换。

输入语义

上传模式：身份图在前，源视频在后。模板模式：只上传身份图并传字典内 template_id；不得同时上传源视频。

创建请求字段

字段	类型	必填	说明
`model`	string	是	`video-face-swap`；兼容 `faceswap`
`input_reference[]`	重复文件	是	上传模式：身份图、源视频；模板模式：仅身份图
`template_id`	string	模板时	只接受服务端受控字典 ID，不能传任意 URL
`prompt`	string	否	非空时用于视频阶段；不要依赖其覆盖服务端约束
`seed`	整数文本	否	重试保持一致

图片使用 JPG/PNG/BMP/WEBP（单张最多 30MB）；视频使用正确的 video/mp4 或 video/quicktime MIME，源文件最多 500MB。视频需能解码且无旋转元数据；并非每个模型都接受 GIF。更多跨模型限制见视频字段总表。

cURL：创建任务

export BASE_URL="https://ic.xshow.live/api/partner/v1"
curl --fail-with-body -X POST "$BASE_URL/videos" \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Idempotency-Key: $ORDER_ID" \
  -H "Xcamshow-Uid: $XCAMSHOW_UID" \
  -F "model=video-face-swap" \
  -F "input_reference[]=@identity.png;type=image/png" \
  -F "input_reference[]=@source.mp4;type=video/mp4"

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

创建回执与结果示例

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

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

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

执行和结果边界

上传与模板源视频均只处理前 10 秒；不足 10 秒则处理已有部分。订单按稳定规则分流 GPU 或 Wan3.0，输出尺寸/帧率在不同分支有差异，按最终媒体读取。GPU 结果不明确时不会盲目再创建云端任务。

查询、下载和取消

操作	HTTP	路径	时机
查询	`POST`	`/videos/{id}`	使用创建响应的 `id` 轮询，不是 `GET`
中间图	`GET`	`/videos/{id}/intermediate`	仅 `intermediate_image_available=true` 时
成片	`GET`	`/videos/{id}/content`	`status=completed` 后；以 `Content-Type` 确定文件类型
取消	`POST`	`/videos/{id}/cancel`	请求取消后仍需查询最终状态

以上请求都携带 Bearer Key。可在 /content 传 ?format=gif 或 ?format=mp4，但实际可用格式以模型和源素材为准；不要把 GIF 字节保存成 MP4。创建超时先查原任务或用原幂等键和完全相同的请求核对。中间图可用不代表最终视频成功。详见任务生命周期。

常见错误及处理

400 invalid_media_count、400 invalid_media_order、400 invalid_template；检查文件顺序和模板 ID。
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，或视频/中间图尚未就绪；先查询原任务。502/503：保留原任务 ID、原幂等键和原始错误以排查，不盲目换键重发。

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

视频换脸 API

On this page