视频换脸 v2 智能选路 API
Partner 视频换脸 v2 的遮挡判定、输入、请求、任务结果与错误
视频换脸 v2 智能选路 API
公开模型 video-face-swap-v2 输入一张人脸图和一段源视频。服务端抽帧分析目标人脸是否被遮挡：有遮挡走 Wan3.0 参考视频生成；无遮挡走 DreamID-V 换脸。路由结果由服务端决定，调用方不传内部模型或判定提示词。此功能与 video-face-swap 的 GPU/Wan3 订单分流不是同一链路。**生产 Proxy 只读模型列表当前返回 ready=false；本页仅说明已识别的接口合同，不代表当前可成功生成。**所需的判定、DreamID-V、Wan3 与存储服务均须就绪。
地址与鉴权
正式 Base URL 为 https://ic.xshow.live/api/partner/v1，开发验收为 https://dev.ic.xshow.live/api/partner/v1。仅服务端使用 Bearer Key。创建还须 Idempotency-Key 与当前 XCamShow 用户的 Xcamshow-Uid；重复请求复用原键、字段与文件。详见任务生命周期。
创建请求
POST /videos，multipart/form-data。input_reference[] 上传人脸图、源视频，各一份；不接受模板 ID 或 Wan3 扩展输入。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
model | string | 是 | 固定 video-face-swap-v2 |
input_reference[] | 重复文件 | 是 | JPG/PNG 人脸图和 MP4/MOV 源视频，各一份 |
seconds | string | 否 | 省略或 15；固定 15 秒计费口径 |
resolution_name | string | 否 | 480p 或 720p；默认 720p |
dreamid_mode | string | 否 | DreamID-V 分支的 faster（默认）或 dwpose |
seed | 整数文本 | 否 | 重试保持不变；生成分支仍可能非确定性 |
图片须非空、最多 30MB；视频须非空、最多 500MB。源视频少于 1 秒会被拒绝；超过 15 秒时服务端尝试截取开头约 14.95 秒，截取失败则返回错误。上传素材须使用正确 MIME；不要传 template_id。prompt 不是该模式的路由控制参数。
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-v2" \
-F "resolution_name=720p" \
-F "input_reference[]=@face.jpg;type=image/jpeg" \
-F "input_reference[]=@source.mp4;type=video/mp4"成功创建返回任务对象，例如 {"id":"TASK_ID","status":"pending"}。判定与提交在后台执行；pending 不代表已经选定并成功提交下游。创建超时也不代表没有接单。
查询、下载与取消
| 操作 | HTTP | 路径 |
|---|---|---|
| 查询 | POST | /videos/{id} |
| 成片 | GET | /videos/{id}/content，仅 completed 后 |
| 取消 | POST | /videos/{id}/cancel |
所有请求携带 Bearer Key。轮询时保留 status、error 与路由阶段信息；不要把查询 HTTP 200 当作成片成功。完成后验证文件可解码，并审查身份稳定性、遮挡段与音轨。此模型无独立姿势图片阶段，不应假定 /intermediate 可用。
常见错误
400：媒体数量、类型、大小、源时长或截取失败；按具体错误修正，不换键重试不同文件。400 idempotency_key_required/partner_user_id_required、401 invalid_api_key、403 model_not_allowed：先修正鉴权与授权。409 idempotency_conflict：同一业务键对应不同有效请求；核对原订单。502/503：判定服务、DreamID-V、Wan3 或存储依赖故障。保留任务 ID、原始错误和订单号；结果不明确时不盲目再创建任务。