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

Spicy 视频换脸 API

独立 Wan3.0 参考视频换脸入口；不同于混合路由的 video-face-swap，也不同于历史 LTX 2.5 模型。

项目	值
公开模型	`video-head-swap-spicy`
创建接口	`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。上传时不能用 GIF 代替视频。

创建请求字段

字段	类型	必填	说明
`model`	string	是	固定 `video-head-swap-spicy`
`input_reference[]`	重复文件	是	身份图先于源视频；模板模式只需身份图
`template_id`	string	模板时	受控字典 ID，不能与上传源视频同时使用
`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-head-swap-spicy" \
  -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 秒，匹配处理片段的时长与尺寸；不提供独立图片预编辑阶段。旧 video-head-swap-spicy-ltx25 另有历史合同，不要互换模型名。

查询、下载和取消

操作	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。
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 或参数。

Spicy 视频换脸 API

On this page