How to Face Swap and Enhance Videos from Your Terminal — No UI Needed

If you've ever wanted to swap a face in a video or upscale a blurry clip without opening a browser, this guide is for you.

Verging AI now offers agent skills — lightweight CLI tools that wrap our API into single commands. You type one line in your terminal, and the skill handles uploading, processing, polling, and downloading automatically.

No SDK. No boilerplate code. Just results.

What Are Agent Skills?

Agent skills are prompt-based tools designed for AI coding agents like Claude Code. Each skill knows how to:

Authenticate with your API key
Upload your files to our CDN
Create processing jobs
Poll for completion
Return (or download) the result

Think of them as CLI wrappers around the Verging AI API — but you don't need to write a single line of code.

Setup (2 Minutes)

1. Get Your API Key

If you don't have one yet:

Go to verging.ai and log in
Click your avatar → API Keys
Create a new key — copy it immediately (it's shown only once)

2. Set the Environment Variable

export VERGING_API_KEY="vrg_sk_your_key_here"

Add this to your .bashrc or .zshrc to persist it.

3. Install the Skills

# Face swap
npx openclaw add verging-ai/faceswap

# Video enhancement
npx openclaw add verging-ai/video-enhancement

# Background removal (bonus)
npx openclaw add verging-ai/background-removal

That's it. You're ready.

Face Swap from the Terminal

Basic Usage

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

This uploads your video and face image, creates a face swap job, waits for it to finish, and returns the result URL.

Swap a Face in a YouTube Video

/faceswap -v "https://youtube.com/watch?v=dQw4w9WgXcQ" -f ./face.jpg --hd

The skill automatically downloads the video using yt-dlp, then processes it. The --hd flag enables high-definition processing (3 credits/sec instead of 1).

Process Only a Specific Segment

Why pay for 30 seconds when you only need 10?

/faceswap -v ./long-video.mp4 -f ./face.jpg --start 5 --end 15

The skill trims the video locally with ffmpeg before uploading — saving both time and credits.

Auto-Download the Result

/faceswap -v ./video.mp4 -f ./face.jpg --download -o ./output/

The result is downloaded directly to your specified directory.

Video Enhancement from the Terminal

Got a blurry or low-resolution video? One command:

Basic Enhancement

/video-enhancement -v ./old-footage.mp4

HD Upscaling

/video-enhancement -v ./clip.mp4 --hd

HD mode uses more advanced models for sharper results (3 credits/sec vs 1 credit/sec).

Enhance a Clip from a URL

/video-enhancement -v "https://youtube.com/watch?v=xxx" --start 0 --end 10 --hd --download

Download a segment, enhance it in HD, and save the result locally — all in one command.

Background Removal — One Command

Need a transparent PNG from a product photo?

/background-removal -i ./product.jpg

Fixed cost: 1 credit per image. Supports JPG, PNG, and WebP up to 10MB.

How It Works Under the Hood

When you run /faceswap -v ./video.mp4 -f ./face.jpg, here's what happens:

Parse — The skill reads your arguments and validates the files
Credit check — Calls /api/v1/auth/me to verify you have enough credits
Upload — Gets a presigned URL from /api/v1/upload-video, uploads your files to R2 CDN
Create job — Calls /api/v1/faceswap/create-job with the CDN URLs
Poll — Checks /api/v1/faceswap/jobs every 5 seconds until the job completes
Result — Returns the result URL (or downloads it if --download is set)

The same pattern applies to video enhancement and background removal. All skills use the same API key and credit system documented in our API reference.

When to Use Skills vs. the Web UI vs. the API

Use case	Best option
Quick one-off processing	Web UI at verging.ai
Batch processing or automation	Agent skills (CLI)
Building your own app	REST API directly
Processing during a coding session	Agent skills inside your AI coding agent

The sweet spot for agent skills is when you're already in the terminal — working on a project, editing code, or running a script — and you need to process a video without context-switching to a browser.

All Available Skills

Skill	Command	What it does
faceswap	`/faceswap -v video -f face.jpg`	Face swap in videos
video-enhancement	`/video-enhancement -v video`	Upscale video quality
background-removal	`/background-removal -i image.jpg`	Remove image backgrounds
imagegen	`/imagegen -p "prompt"`	Generate images from text
chat	`/chat -m "question"`	LLM chat completions
tts	`/tts -t "text" -v nova`	Text-to-speech
stt	`/stt -f audio.mp3`	Speech-to-text
vision	`/vision -i image.jpg -p "describe"`	Image analysis

All skills are open source at github.com/verging-ai/agent-skills.

Getting Started

Get your API key at verging.ai
Set VERGING_API_KEY in your environment
Install the skill you need with npx openclaw add verging-ai/<skill-name>
Run the command

Full API documentation and skill reference: verging.ai/docs/api