> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 视频换脸
> 无需检测步骤，直接替换视频中的主要人脸。
## 概述
单人视频换脸用于将视频中的主要人脸替换为一张新人脸图片。此接口不需要先做人脸检测，只需提交原始视频地址和新人脸图片地址。
多人换脸仍需要先调用检测接口并传入 `detect_id`。
## 请求示例
```json theme={null}
{
"model": "video-face-swap",
"callback_url": "https://your-domain.com/api/callback",
"input": {
"video_url": "https://example.com/target-video.mp4",
"new_face": "https://example.com/new-face.jpg"
}
}
```
## 参数说明
需要换脸的视频 URL。
新人脸图片 URL。
## 查询任务状态
提交任务后，使用统一查询接口检查进度并获取结果：
了解如何查询任务状态并获取生成结果
生产环境建议使用 `callback_url` 在任务完成时接收自动通知，而不是轮询状态接口。
## 相关资源
使用检测结果替换视频中的指定人脸
查询检测状态并获取 `detect_id` 与人脸列表
查看账户剩余积分
## OpenAPI
````yaml zh/ai-tools/face-swap/video-face-swap.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
title: Crun 视频换脸 API
description: crun.ai 视频换脸 API 文档
version: 1.0.0
contact:
name: 技术支持
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API 服务器
security:
- ApiKeyAuth: []
paths:
/api/v1/client/job/CreateTask:
post:
summary: 视频换脸
operationId: video-face-swap
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- video-face-swap
description: 此接口使用的模型名称，必须为 `video-face-swap`。
callback_url:
type: string
format: uri
description: 可选。用于接收任务完成通知的回调地址。
example: https://your-domain.com/api/callback
input:
$ref: '#/components/schemas/VideoFaceSwapInput'
example:
model: video-face-swap
callback_url: https://your-domain.com/api/callback
input:
video_url: https://example.com/target-video.mp4
new_face: https://example.com/new-face.jpg
disable_safety_checker: false
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
task_id:
type: string
description: 任务 ID，可用于查询任务状态和结果
example: task_12345678
example:
code: 200
message: success
data:
task_id: task_12345678
'422':
description: 验证错误
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
errors:
type: array
description: 详细的参数验证错误信息
items:
type: string
example:
- 具体字段错误信息
example:
code: 422
message: Missing Params or Type Error
errors:
- 具体字段错误信息
'500':
$ref: '#/components/responses/Error'
components:
schemas:
VideoFaceSwapInput:
type: object
description: 单人视频换脸输入参数。
properties:
video_url:
type: string
format: uri
description: 需要换脸的视频 URL。
example: https://example.com/target-video.mp4
new_face:
type: string
format: uri
description: 新人脸图片 URL。
example: https://example.com/new-face.jpg
disable_safety_checker:
type: boolean
nullable: true
description: 禁用安全过滤。
default: null
example: false
required:
- video_url
- new_face
ApiResponse:
type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 422
- 429
- 455
- 500
- 501
- 505
description: |-
响应状态码
- **200**：成功 - 请求已成功处理
- **401**：未授权 - 认证凭据缺失或无效
- **402**：余额不足 - 账户积分不足，无法执行操作
- **404**：未找到 - 请求的资源或接口不存在
- **422**：验证错误 - 请求参数未通过校验
- **429**：请求过多 - 已超过该资源的请求限制
- **455**：服务不可用 - 系统正在维护
- **500**：服务器错误 - 处理请求时发生意外错误
- **501**：生成失败 - 内容生成任务失败
- **505**：功能已禁用 - 请求的功能当前不可用
message:
type: string
description: 响应消息，失败时为错误描述
example: success
responses:
Error:
description: 服务器错误
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: |-
所有 API 都需要通过 API Key 认证。
获取 API Key：
1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key
使用方式：
添加到请求头：
x-api-key: YOUR_API_KEY
注意：
- 请妥善保管你的 API Key，不要分享给他人
- 如果怀疑 API Key 已泄露，请立即在管理页面重置
````