Skip to main content
POST
/
api
/
platform
/
v1
/
face-swap
Create Face Swap
curl --request POST \
  --url https://api.cuttr.com/api/platform/v1/face-swap \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "video_url": "<string>",
  "face_image_url": "<string>",
  "mode": "<string>"
}
'
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "fullbody",
  "duration_seconds": 30,
  "cost_cents": 600,
  "status": "processing"
}
Submit a video and a face image to generate an AI face swap. You can provide any video URL (YouTube, TikTok, Instagram, Vimeo, and 1000+ other platforms — or a direct link to a video file), upload files directly, or a mix of both. Cost is $0.20 per second of video (rounded up), deducted from your wallet upfront. Maximum video duration is 5 minutes (300 seconds).
The response comes back immediately with a job_id. The video is processed in the background. Use Get Face Swap Status to poll for results.

​
Modes

ModeEngineSpeedBest for
faceFAL AIFast (minutes)Face-only swaps, quick previews
fullbody (default)Kling AISlower (may take longer)Full body swaps, production quality
In fullbody mode, the API automatically detects face segments in the video, processes each segment through Kling AI, and stitches the result back into the full original video.

​
Option 1: JSON with URLs

curl -X POST https://api.cuttr.com/api/platform/v1/face-swap \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "face_image_url": "https://example.com/face.jpg",
    "mode": "fullbody"
  }'

​
Option 2: File upload via form data

curl -X POST https://api.cuttr.com/api/platform/v1/face-swap \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "video=@/path/to/video.mp4" \
  -F "face_image=@/path/to/face.jpg" \
  -F "mode=fullbody"

​
Option 3: Mix of URL and file

curl -X POST https://api.cuttr.com/api/platform/v1/face-swap \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "video=@/path/to/video.mp4" \
  -F "face_image_url=https://example.com/face.jpg" \
  -F "mode=face"

​
Headers

​
X-API-Key
string
required
Your API key. Create one from the dashboard.

​
Body parameters (JSON)

​
video_url
string
A URL to the source video. Supports YouTube, TikTok, Instagram, Vimeo, and 1000+ other platforms — as well as direct links to video files. Required if not uploading a video file.
​
face_image_url
string
A publicly accessible URL to the face image. Required if not uploading a face_image file.
​
mode
string
default:"fullbody"
Face swap mode. One of face or fullbody.
  • face — Fast face-only swap using FAL AI.
  • fullbody — Full body swap using Kling AI. Automatically detects face segments and stitches the result into the original video.

​
Form data fields (multipart upload)

​
video
file
Video file (mp4, mov, webm, avi). Max 500MB. Required if not providing video_url.
​
face_image
file
Face image file (jpg, png, webp). Max 500MB. Required if not providing face_image_url.
​
mode
string
default:"fullbody"
Face swap mode. One of face or fullbody.

​
Response

​
job_id
string
UUID job identifier. Poll with Get Face Swap Status.
​
mode
string
The mode used: "face" or "fullbody".
​
duration_seconds
integer
Video duration in seconds (rounded up). This is the billable quantity.
​
cost_cents
integer
Total amount charged in cents (duration_seconds * 20).
​
status
string
Always "processing" on success.
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "fullbody",
  "duration_seconds": 30,
  "cost_cents": 600,
  "status": "processing"
}