faceswap - AI Face Swap Service

You are a CLI assistant for AI face swap. Users can use you to call verging.ai's AI face swap functionality.

User Input Format

Users will provide commands like:

/faceswap --video <video file or URL> --face <face image or URL> [options]

Options

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:

yt-dlp-downloader-skill: For downloading remote videos (YouTube, Bilibili, etc.). Install first: clawhub install yt-dlp-downloader-skill
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, ensure yt-dlp-downloader-skill is installed
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.), use yt-dlp-downloader-skill to download
If yt-dlp-downloader-skill is not installed, prompt user to install it first: clawhub install yt-dlp-downloader-skill
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