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>"
}
'

import requests

url = "https://api.cuttr.com/api/platform/v1/face-swap"

payload = {
    "video_url": "<string>",
    "face_image_url": "<string>",
    "mode": "<string>"
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({video_url: '<string>', face_image_url: '<string>', mode: '<string>'})
};

fetch('https://api.cuttr.com/api/platform/v1/face-swap', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cuttr.com/api/platform/v1/face-swap",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'video_url' => '<string>',
    'face_image_url' => '<string>',
    'mode' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cuttr.com/api/platform/v1/face-swap"

	payload := strings.NewReader("{\n  \"video_url\": \"<string>\",\n  \"face_image_url\": \"<string>\",\n  \"mode\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cuttr.com/api/platform/v1/face-swap")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"video_url\": \"<string>\",\n  \"face_image_url\": \"<string>\",\n  \"mode\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cuttr.com/api/platform/v1/face-swap")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"video_url\": \"<string>\",\n  \"face_image_url\": \"<string>\",\n  \"mode\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "fullbody",
  "duration_seconds": 30,
  "cost_cents": 600,
  "status": "processing"
}

{
  "error": "Provide either a video_url or a video file via multipart form data"
}

{
  "error": "Insufficient wallet balance",
  "required_cents": 600,
  "balance_cents": 200
}

POST

api

platform

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>"
}
'

import requests

url = "https://api.cuttr.com/api/platform/v1/face-swap"

payload = {
    "video_url": "<string>",
    "face_image_url": "<string>",
    "mode": "<string>"
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({video_url: '<string>', face_image_url: '<string>', mode: '<string>'})
};

fetch('https://api.cuttr.com/api/platform/v1/face-swap', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cuttr.com/api/platform/v1/face-swap",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'video_url' => '<string>',
    'face_image_url' => '<string>',
    'mode' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cuttr.com/api/platform/v1/face-swap"

	payload := strings.NewReader("{\n  \"video_url\": \"<string>\",\n  \"face_image_url\": \"<string>\",\n  \"mode\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cuttr.com/api/platform/v1/face-swap")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"video_url\": \"<string>\",\n  \"face_image_url\": \"<string>\",\n  \"mode\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cuttr.com/api/platform/v1/face-swap")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"video_url\": \"<string>\",\n  \"face_image_url\": \"<string>\",\n  \"mode\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "fullbody",
  "duration_seconds": 30,
  "cost_cents": 600,
  "status": "processing"
}

{
  "error": "Provide either a video_url or a video file via multipart form data"
}

{
  "error": "Insufficient wallet balance",
  "required_cents": 600,
  "balance_cents": 200
}

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

Mode	Engine	Speed	Best for
`face`	FAL AI	Fast (minutes)	Face-only swaps, quick previews
`fullbody` (default)	Kling AI	Slower (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

string

required

Your API key. Create one from the dashboard.

Body parameters (JSON)

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.

string

A publicly accessible URL to the face image. Required if not uploading a face_image file.

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)

file

Video file (mp4, mov, webm, avi). Max 500MB. Required if not providing video_url.

file

Face image file (jpg, png, webp). Max 500MB. Required if not providing face_image_url.

string

default:"fullbody"

Face swap mode. One of face or fullbody.

Response

string

UUID job identifier. Poll with Get Face Swap Status.

string

The mode used: "face" or "fullbody".

integer

Video duration in seconds (rounded up). This is the billable quantity.

integer

Total amount charged in cents (duration_seconds * 20).

string

Always "processing" on success.

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "fullbody",
  "duration_seconds": 30,
  "cost_cents": 600,
  "status": "processing"
}

{
  "error": "Provide either a video_url or a video file via multipart form data"
}

{
  "error": "Insufficient wallet balance",
  "required_cents": 600,
  "balance_cents": 200
}

Overview

Endpoints

Create Face Swap

Modes

Option 1: JSON with URLs

Option 2: File upload via form data

Option 3: Mix of URL and file

Headers

Body parameters (JSON)

Form data fields (multipart upload)

Response

​Modes

​Option 1: JSON with URLs

​Option 2: File upload via form data

​Option 3: Mix of URL and file

​Headers

​Body parameters (JSON)

​Form data fields (multipart upload)

​Response

Modes

Option 1: JSON with URLs

Option 2: File upload via form data

Option 3: Mix of URL and file

Headers

Body parameters (JSON)

Form data fields (multipart upload)

Response