DreamID-V 视频换脸 API
Partner DreamID-V 视频换脸的输入、模式、请求、轮询与错误
DreamID-V 视频换脸 API
本功能把一张清晰人脸图的身份应用到源视频，公开模型为 video-face-swap-dreamid。它不走 video-face-swap 的 GPU/Wan3 混合路由，也不接受模板 ID。**生产 Proxy 只读模型列表当前返回 ready=false；本页说明已识别的接口合同，不代表当前可成功生成。**集成前须重新查询模型就绪状态。
地址与鉴权
| 环境 | Base URL |
|---|---|
| 正式 | https://ic.xshow.live/api/partner/v1 |
| 开发 | https://dev.ic.xshow.live/api/partner/v1 |
仅从服务端调用。所有请求携带 Authorization: Bearer $PARTNER_API_KEY；创建还要携带 Idempotency-Key: $ORDER_ID 和 Xcamshow-Uid: $XCAMSHOW_UID。同一订单重试使用同一键与相同文件；Key 不进入浏览器或日志。详见任务生命周期。
创建请求
POST /videos，multipart/form-data。input_reference[] 按人脸图、源视频顺序重复传入；不得传 template_id。客户端自动生成 multipart boundary。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
model | string | 是 | 固定 video-face-swap-dreamid |
input_reference[] | 重复文件 | 是 | 恰好 1 张 JPG/PNG 人脸图和 1 段 MP4/MOV 源视频 |
dreamid_mode | string | 否 | faster（默认，快速模式）或 dwpose（高质量模式） |
seconds | string | 否 | 省略或 15，固定 15 秒计费口径；不用于延长源片 |
人脸图须非空、最多 30MB；源视频须非空、最多 500MB，最长 15 秒。请使用正确的 image/jpeg、image/png、video/mp4 或 video/quicktime MIME。源视频中的音频按上游换脸结果保留；输出画面、身份与音频仍需人工抽检。
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-dreamid" \
-F "dreamid_mode=faster" \
-F "input_reference[]=@face.jpg;type=image/jpeg" \
-F "input_reference[]=@source.mp4;type=video/mp4"创建返回任务对象，例如 {"id":"TASK_ID","status":"pending"}；该 JSON 只是字段形状示例。保存 id，不要把请求超时当作未接单。
查询与结果
| 操作 | HTTP | 路径 |
|---|---|---|
| 查询 | POST | /videos/{id} |
| 成片 | GET | /videos/{id}/content，仅任务 completed 后 |
| 取消 | POST | /videos/{id}/cancel |
全部携带 Bearer Key。完成后检查响应 Content-Type 与媒体实际可解码性；取消回执不等于执行已停或扣费已释放。本模型无独立图片阶段，不应假定 /intermediate 可用。
常见错误
400：检查两份文件数量、MIME、大小与dreamid_mode；模式只接受faster、dwpose。400 idempotency_key_required/partner_user_id_required：补创建请求头；401 invalid_api_key：核对环境 Key。403 model_not_allowed：模型未获授权；409 idempotency_conflict：同一键的请求发生变化；503：DreamID-V 服务未配置或不可用。- 网络结果不明确时先用原任务 ID 查询，或用原键与原请求核对，不新建订单盲重试。