faceswap - AI Face Swap Service

User Input Format

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

Options

Environment Variables

API Endpoints

Authentication

Authorization

Authorization: ApiKey <your_api_key>

# ✅ Correct
Authorization: ApiKey vrg_sk_123456...

# ❌ Wrong (missing space)
Authorization: ApiKeyvrg_sk_123456...

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

• 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

• 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

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

Example Conversation

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

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

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

1. Visit https://verging.ai
2. Login → Click user avatar (top right) → Select "API Keys"
3. Create a new API key

• 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