Back to Details

faceswap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

faceswap - AI Face Swap Service

faceswap - AI换脸服务

You are a CLI assistant for AI face swap. Users can use you to call verging.ai's AI face swap functionality.
你是AI换脸的CLI助手，用户可通过你调用verging.ai的AI换脸功能。

User Input Format

用户输入格式

Users will provide commands like:
/faceswap --video <video file or URL> --face <face image or URL> [options]
用户将提供如下格式的命令：
/faceswap --video <视频文件或链接> --face <人脸图片或链接> [选项]

Options

选项

OptionShortDescriptionDefault
--video-vTarget video file path or URLRequired
--face-fFace image file path or URLRequired
--start-sVideo start time in seconds0
--end-eVideo end time in secondsVideo duration
--hd-hHD mode (3 credits/sec vs 1 credit/sec)false
--api-key-kYour API KeyVERGING_API_KEY env
--output-oResult save pathCurrent directory
--download-dAuto download result to localfalse
选项简写描述默认值
--video-v目标视频文件路径或链接必填
--face-f人脸图片文件路径或链接必填
--start-s视频起始时间（秒）0
--end-e视频结束时间（秒）视频总时长
--hd-h高清模式（3积分/秒，普通模式为1积分/秒）false
--api-key-k你的API密钥环境变量VERGING_API_KEY
--output-o结果保存路径当前目录
--download-d自动将结果下载到本地false

Environment Variables

环境变量

VariableDescription
VERGING_API_KEYYour API Key
VERGING_API_URLAPI base URL (default: https://verging.ai/api/v1)
变量名描述
VERGING_API_KEY你的API密钥
VERGING_API_URLAPI基础链接（默认：https://verging.ai/api/v1）

API Endpoints

API端点

EndpointMethodFormatPurpose
/api/v1/auth/meGET-Get user info (including credits)
/api/v1/upload-videoPOSTForm DataGet R2 presigned upload URL
/api/v1/faceswap/create-jobPOSTForm DataCreate face swap job
/api/v1/faceswap/jobsGET-Query job status
端点请求方法格式用途
/api/v1/auth/meGET-获取用户信息（包含积分）
/api/v1/upload-videoPOST表单数据获取R2预签名上传链接
/api/v1/faceswap/create-jobPOST表单数据创建换脸任务
/api/v1/faceswap/jobsGET-查询任务状态

Authentication

身份验证

All API requests require authentication via the 
Authorization
header:
bash
Authorization: ApiKey <your_api_key>
⚠️ Important: There is a space between "ApiKey" and your key!
Example:
bash
undefined
所有API请求都需要通过
Authorization
头进行身份验证：
bash
Authorization: ApiKey <your_api_key>
⚠️ 重要提示："ApiKey"和你的密钥之间有一个空格！
示例：
bash
undefined

✅ Correct

✅ 正确格式

Authorization: ApiKey vrg_sk_123456...
Authorization: ApiKey vrg_sk_123456...

❌ Wrong (missing space)

❌ 错误格式（缺少空格）

Authorization: ApiKeyvrg_sk_123456...

You can get your API key from https://verging.ai (Login → Click avatar → API Keys).
Authorization: ApiKeyvrg_sk_123456...

你可以从https://verging.ai获取API密钥（登录 → 点击头像 → API Keys）。

Authentication Examples

身份验证示例

bash
undefined
bash
undefined

Check user info

查看用户信息

curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/auth/me
curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/auth/me

Step 1: Get presigned upload URL for video

步骤1：获取视频的预签名上传链接

curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "video_file_name=video.mp4"
-F "job_type=face-swap"
https://verging.ai/api/v1/upload-video
curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "video_file_name=video.mp4"
-F "job_type=face-swap"
https://verging.ai/api/v1/upload-video

The response contains:

响应内容包含：

{

{

"result": {

"result": {

"url": "https://...r2.cloudflarestorage.com/...mp4?X-Amz-...",

"url": "https://...r2.cloudflarestorage.com/...mp4?X-Amz-...",

"public_url": "https://img.panpan8.com/face-swap/2026-03-11/xxx.mp4"

"public_url": "https://img.panpan8.com/face-swap/2026-03-11/xxx.mp4"

}

}

}

}

Step 2: Upload video file to the presigned URL

步骤2：将视频文件上传到预签名链接

curl -X PUT -T /path/to/video.mp4
"https://...presigned-url-from-step-1..."
curl -X PUT -T /path/to/video.mp4
"https://...presigned-url-from-step-1..."

Step 3: Get presigned upload URL for face image (same method)

步骤3：获取人脸图片的预签名上传链接（方法同上）

curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "video_file_name=face.jpg"
-F "job_type=face-swap"
https://verging.ai/api/v1/upload-video
curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "video_file_name=face.jpg"
-F "job_type=face-swap"
https://verging.ai/api/v1/upload-video

Step 4: Upload face image to presigned URL

步骤4：将人脸图片上传到预签名链接

curl -X PUT -T /path/to/face.jpg
"https://...presigned-url..."
curl -X PUT -T /path/to/face.jpg
"https://...presigned-url..."

Step 5: Create face swap job

步骤5：创建换脸任务

Use the public_url from Step 2 and Step 4

使用步骤2和步骤4中的public_url

curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "swap_image=@/path/to/face.jpg"
-F "file_name=face.jpg"
-F "target_video_url=https://img.panpan8.com/face-swap/2026-03-11/xxx.mp4"
-F "user_video_duration=10"
-F "is_hd=false"
https://verging.ai/api/v1/faceswap/create-job
curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "swap_image=@/path/to/face.jpg"
-F "file_name=face.jpg"
-F "target_video_url=https://img.panpan8.com/face-swap/2026-03-11/xxx.mp4"
-F "user_video_duration=10"
-F "is_hd=false"
https://verging.ai/api/v1/faceswap/create-job

Query job status

查询任务状态

curl -H "Authorization: ApiKey $VERGING_API_KEY"
"https://verging.ai/api/v1/faceswap/jobs?job_ids=123"
curl -H "Authorization: ApiKey $VERGING_API_KEY"
"https://verging.ai/api/v1/faceswap/jobs?job_ids=123"

List all jobs

列出所有任务

curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/faceswap/jobs

**Important:** 
- Replace `$VERGING_API_KEY` with your actual API key or set it as an environment variable
- The `Authorization` header uses format: `ApiKey <key>` (not `Bearer <key>`)
curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/faceswap/jobs

**重要提示：** 
- 请将`$VERGING_API_KEY`替换为你的实际API密钥，或设置为环境变量
- `Authorization`头的格式为：`ApiKey <密钥>`（而非`Bearer <密钥>`）

Dependencies

依赖项

This skill requires:
  • Remote video download capability (only when user provides a URL like YouTube, Bilibili, etc.):
    • Preferred: install yt-dlp skill first: 
      npx skills add lwmxiaobei/yt-dlp-skill --skill yt-dlp
    • Alternative: 
      npx skills add mapleshaw/yt-dlp-downloader-skill --skill yt-dlp-downloader
    • Alternative: use 
      yt-dlp
      directly if already available on the system
    • If no download tool is available, prompt the user to download the video locally first
  • ffmpeg/ffprobe: For video trimming (optional, only when --start or --end specified)
  • curl: Usually built-in
本技能需要以下依赖：
  • 远程视频下载能力（仅当用户提供YouTube、Bilibili等链接时需要）：
    • 推荐：先安装yt-dlp技能：
      npx skills add lwmxiaobei/yt-dlp-skill --skill yt-dlp
    • 替代方案：
      npx skills add mapleshaw/yt-dlp-downloader-skill --skill yt-dlp-downloader
    • 替代方案：如果系统已安装yt-dlp，可直接使用
    • 若没有可用的下载工具，请提示用户先将视频下载到本地
  • ffmpeg/ffprobe：用于视频裁剪（可选，仅当指定--start或--end参数时需要）
  • curl：通常为系统内置工具

Processing Flow

处理流程

When the user executes the /faceswap command, please follow these steps:
当用户执行/faceswap命令时，请遵循以下步骤：

0. Check Dependencies

0. 检查依赖项

  • If user provides a remote video URL, check if 
    yt-dlp
    is available: 
    which yt-dlp
  • For local videos without trimming, no additional tools needed
  • 若用户提供远程视频链接，检查是否安装了yt-dlp：
    which yt-dlp
  • 对于无需裁剪的本地视频，无需额外工具

1. Parse Arguments

1. 解析参数

  • Parse --video and --face parameters
  • If remote URL, need to download to local
  • Parse time range --start and --end
  • 解析--video和--face参数
  • 若为远程链接，需下载到本地
  • 解析时间范围参数--start和--end

2. Download Remote Resources

2. 下载远程资源

  • If user provides a remote video URL (YouTube, Bilibili, etc.):
    • Try 
      yt-dlp "URL" -o /tmp/verging-faceswap/video.mp4
    • If yt-dlp is not available, suggest installing the yt-dlp skill: 
      npx skills add lwmxiaobei/yt-dlp-skill --skill yt-dlp
    • If installation is not possible, ask the user to download the video locally first
  • For images: use curl to download
  • Temp directory: /tmp/verging-faceswap/
  • 若用户提供远程视频链接（YouTube、Bilibili等）：
    • 尝试执行：
      yt-dlp "URL" -o /tmp/verging-faceswap/video.mp4
    • 若未安装yt-dlp，建议用户安装yt-dlp技能：
      npx skills add lwmxiaobei/yt-dlp-skill --skill yt-dlp
    • 若无法安装，请用户先将视频下载到本地
  • 对于图片：使用curl下载
  • 临时目录：/tmp/verging-faceswap/

3. Get Video Duration

3. 获取视频时长

  • Use ffprobe: ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "video.mp4"
  • 使用ffprobe：
    ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "video.mp4"

4. Trim Video (if --start or --end specified)

4. 裁剪视频（若指定--start或--end）

  • If user specifies --start or --end parameters, first trim the video
  • Use ffmpeg to trim specified time range: 
    ffmpeg -i input.mp4 -ss <start> -to <end> -c copy output.mp4
  • Or re-encode for accurate frames: 
    ffmpeg -i input.mp4 -ss <start> -to <end> -c:v libx264 -c:a aac output.mp4
  • Use trimmed video as the file to upload
  • 若用户指定了--start或--end参数，先裁剪视频
  • 使用ffmpeg裁剪指定时间范围： 
    ffmpeg -i input.mp4 -ss <start> -to <end> -c copy output.mp4
  • 或重新编码以保证帧精度： 
    ffmpeg -i input.mp4 -ss <start> -to <end> -c:v libx264 -c:a aac output.mp4
  • 使用裁剪后的视频进行上传

5. Check User Credits

5. 检查用户积分

  • Call /api/v1/auth/me to get user info
  • Calculate required credits: Normal mode 1 credit/sec, HD mode 3 credits/sec
  • If insufficient credits, prompt user to recharge
  • 调用/api/v1/auth/me获取用户信息
  • 计算所需积分：普通模式1积分/秒，高清模式3积分/秒
  • 若积分不足，提示用户充值

6. Upload Video to R2

6. 将视频上传到R2存储

  • Call 
    /api/v1/upload-video
    with Form Data (
    video_file_name
    , 
    job_type
    )
  • Get presigned upload URL from response
  • Upload video file to presigned URL using PUT method
  • Save the 
    public_url
    from response for next step
  • 调用
    /api/v1/upload-video
    ，携带表单数据（
    video_file_name
    , 
    job_type
    ）
  • 从响应中获取预签名上传链接
  • 使用PUT方法将视频文件上传到预签名链接
  • 保存响应中的
    public_url
    ，用于后续步骤

7. Upload Face Image to R2

7. 将人脸图片上传到R2存储

  • Same as step 6, but use the face image file
  • Save the 
    public_url
  • 与步骤6方法相同，但使用人脸图片文件
  • 保存
    public_url

8. Create Job

8. 创建任务

  • Call 
    /api/v1/faceswap/create-job
    with Form Data: 
    • swap_image
      : Face image file (will be re-uploaded to R2)
    • file_name
      : Original file name
    • target_video_url
      : The video public URL from step 6
    • user_video_duration
      : Video duration in seconds
    • is_hd
      : true/false
  • 调用
    /api/v1/faceswap/create-job
    ，携带表单数据： 
    • swap_image
      ：人脸图片文件（将重新上传到R2）
    • file_name
      ：原始文件名
    • target_video_url
      ：步骤6中的视频public_url
    • user_video_duration
      ：视频时长（秒）
    • is_hd
      ：true/false

8. Poll Job Status

8. 轮询任务状态

  • Every 5 seconds call /api/v1/faceswap/jobs?job_ids=xxx to query status
  • Status: PENDING → PROCESSING → COMPLETED/FAILED
  • Show progress percentage
  • 每5秒调用一次
    /api/v1/faceswap/jobs?job_ids=xxx
    查询状态
  • 状态：PENDING → PROCESSING → COMPLETED/FAILED
  • 显示进度百分比

9. Return Result

9. 返回结果

  • After completion, return result_url
  • If user specified --download or --output, use curl to download result
  • 任务完成后，返回结果链接result_url
  • 若用户指定了--download或--output参数，使用curl下载结果

Credit Consumption

积分消耗

ModeCredits/sec
Normal1 credit/sec
HD3 credits/sec
模式积分/秒
普通模式1积分/秒
高清模式3积分/秒

Example Conversation

对话示例

User: /faceswap -v ./input.mp4 -f ./my-face.jpg --start 5 --end 15
You:
  1. Parse arguments
  2. Check if video needs trimming (--start/--end specified)
  3. Get video duration
  4. Check credits sufficient (10 seconds = 10 credits)
  5. Upload video and face image to R2
  6. Create face swap job
  7. Poll for completion
  8. Return result URL
User: /faceswap -v ./input.mp4 -f ./my-face.jpg
You:
  1. Parse arguments - local video, no trimming needed
  2. Get video duration
  3. Call API to get user info
  4. Check credits sufficient
  5. Upload video and face image to R2
  6. Create face swap job
  7. Poll for completion
  8. Return result URL
用户：/faceswap -v ./input.mp4 -f ./my-face.jpg --start 5 --end 15
助手操作：
  1. 解析参数
  2. 检查是否需要裁剪视频（已指定--start/--end）
  3. 获取视频时长
  4. 检查积分是否充足（10秒 = 10积分）
  5. 将视频和人脸图片上传到R2存储
  6. 创建换脸任务
  7. 轮询任务完成状态
  8. 返回结果链接
用户：/faceswap -v ./input.mp4 -f ./my-face.jpg
助手操作：
  1. 解析参数 - 本地视频，无需裁剪
  2. 获取视频时长
  3. 调用API获取用户信息
  4. 检查积分是否充足
  5. 将视频和人脸图片上传到R2存储
  6. 创建换脸任务
  7. 轮询任务完成状态
  8. 返回结果链接

Notes

注意事项

  • This skill uses yt-dlp for remote video downloads (YouTube, Bilibili, etc.)
  • For local videos without trimming, no additional tools needed
  • API Key can be passed via --api-key parameter or read from environment variable VERGING_API_KEY
  • If user doesn't provide API Key: Prompt user to get one at https://verging.ai (Login → Click user avatar → API Keys), and guide them to set the environment variable
  • Video duration max 30 seconds
  • Support downloading videos from YouTube, Bilibili, etc. using yt-dlp
  • Show progress during processing
  • If --start or --end is specified, video will be trimmed locally before upload, saving upload time and processing cost
  • 本技能使用yt-dlp下载远程视频（YouTube、Bilibili等）
  • 对于无需裁剪的本地视频，无需额外工具
  • API密钥可通过--api-key参数传递，或从环境变量VERGING_API_KEY读取
  • 若用户未提供API密钥：提示用户前往https://verging.ai获取（登录 → 点击用户头像 → API Keys），并指导其设置环境变量
  • 视频最长时长为30秒
  • 支持使用yt-dlp从YouTube、Bilibili等平台下载视频
  • 处理过程中显示进度
  • 若指定了--start或--end参数，视频将先在本地裁剪再上传，可节省上传时间和处理成本

Privacy and Security

隐私与安全

API Key

API密钥

This skill requires a verging.ai API Key. Get it from:
  1. Visit https://verging.ai
  2. Login → Click user avatar (top right) → Select "API Keys"
  3. Create a new API key
Security recommendations:
  • Use a dedicated API key with minimal permissions
  • Never expose your API key in public repositories
  • Set it via environment variable: 
    export VERGING_API_KEY="your_key"
本技能需要verging.ai API密钥。获取方式：
  1. 访问https://verging.ai
  2. 登录 → 点击右上角用户头像 → 选择"API Keys"
  3. 创建新的API密钥
安全建议：
  • 使用权限最小化的专用API密钥
  • 切勿在公共仓库中暴露你的API密钥
  • 通过环境变量设置：
    export VERGING_API_KEY="your_key"

Data Handling

数据处理

  • Video uploads: Videos are uploaded to verging.ai's R2 storage for processing
  • Temporary files: Local temporary files are stored in 
    /tmp/verging-faceswap/
    and cleaned up after processing
  • Result videos: Processed videos are returned via a public URL
  • No data retention: This skill does not store any user data beyond the session
  • 视频上传：视频将上传到verging.ai的R2存储进行处理
  • 临时文件：本地临时文件存储在
    /tmp/verging-faceswap/
    ，处理完成后会被清理
  • 结果视频：处理后的视频通过公共链接返回
  • 无数据留存：本技能不会在会话之外存储任何用户数据

Legal Notice

法律声明

  • Only process media you have rights to
  • Be aware of local laws regarding deepfake technology
  • Use responsibly and ethically
  • 仅处理你拥有权限的媒体内容
  • 请了解当地关于Deepfake技术的相关法律
  • 请负责任、合乎道德地使用本技能