Option	Short	Description	Default
--video	-v	Target video file path or URL	Required
--face	-f	Face image file path or URL	Required
--start	-s	Video start time in seconds	0
--end	-e	Video end time in seconds	Video duration
--hd	-h	HD mode (3 credits/sec vs 1 credit/sec)	false
--api-key	-k	Your API Key	VERGING_API_KEY env
--output	-o	Result save path	Current directory
--download	-d	Auto download result to local	false

Environment Variables

Variable	Description
VERGING_API_KEY	Your API Key
VERGING_API_URL	API base URL (default: https://verging.ai/api/v1)

API Endpoints

Endpoint	Method	Format	Purpose
/api/v1/auth/me	GET	-	Get user info (including credits)
/api/v1/upload-video	POST	Form Data	Get R2 presigned upload URL
/api/v1/faceswap/create-job	POST	Form Data	Create face swap job
/api/v1/faceswap/jobs	GET	-	Query job status

Authentication

All API requests require authentication via the Authorization header:

Authorization: ApiKey <your_api_key>

⚠️ Important: There is a space between "ApiKey" and your key!

Example:

# ✅ Correct
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).

Authentication Examples

# Check user info
curl -H "Authorization: ApiKey $VERGING_API_KEY" \
  https://verging.ai/api/v1/auth/me

# Step 1: Get presigned upload URL for 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": {
#     "url": "https://...r2.cloudflarestorage.com/...mp4?X-Amz-...",
#     "public_url": "https://img.panpan8.com/face-swap/2026-03-11/xxx.mp4"
#   }
# }

# Step 2: Upload video file to the presigned URL
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)
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
curl -X PUT -T /path/to/face.jpg \
  "https://...presigned-url..."

# Step 5: Create face swap job
# Use the public_url from Step 2 and Step 4
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"

# 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>)

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

Processing Flow

When the user executes the /faceswap command, please follow these steps:

0. Check Dependencies

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

1. Parse Arguments

Parse --video and --face parameters
If remote URL, need to download to local
Parse time range --start and --end

2. Download Remote Resources

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/

3. Get Video Duration

Use 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)

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

5. Check User Credits

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

6. Upload Video to 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

7. Upload Face Image to R2

Same as step 6, but use the face image file
Save the public_url

8. Create Job

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

8. Poll Job Status

Every 5 seconds call /api/v1/faceswap/jobs?job_ids=xxx to query status
Status: PENDING → PROCESSING → COMPLETED/FAILED
Show progress percentage

9. Return Result

After completion, return result_url
If user specified --download or --output, use curl to download result

Credit Consumption

Mode	Credits/sec
Normal	1 credit/sec
HD	3 credits/sec

Example Conversation

User: /faceswap -v ./input.mp4 -f ./my-face.jpg --start 5 --end 15

You:

Parse arguments
Check if video needs trimming (--start/--end specified)
Get video duration
Check credits sufficient (10 seconds = 10 credits)
Upload video and face image to R2
Create face swap job
Poll for completion
Return result URL

User: /faceswap -v ./input.mp4 -f ./my-face.jpg

You:

Parse arguments - local video, no trimming needed
Get video duration
Call API to get user info
Check credits sufficient
Upload video and face image to R2
Create face swap job
Poll for completion
Return result URL

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

Privacy and Security

API Key

This skill requires a verging.ai API Key. Get it from:

Visit https://verging.ai
Login → Click user avatar (top right) → Select "API Keys"
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"

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

Legal Notice

Only process media you have rights to
Be aware of local laws regarding deepfake technology
Use responsibly and ethically

faceswap

faceswap - AI Face Swap Service

User Input Format

Options

More from verging-ai/agent-skills

video-enhancement

background-removal

background-remover