Quick start
Create a key in your verified account, send a multipart request from your server, then poll the matching GET route with the returned taskId. Keep the secret outside browser and mobile client bundles.
- 1Create and copy a key once
- 2Submit local media with consent=true
- 3Poll while PENDING or PROCESSING
curl --request POST https://faceswapai.com/api/v1/face-swap/image \
--header "Authorization: Bearer $FACESWAPAI_API_KEY" \
--form "sourceImage=@./source.jpg" \
--form "targetImage=@./target.jpg" \
--form "consent=true"Endpoints and exact pricing
| Method | Endpoint | Purpose | Credit formula |
|---|---|---|---|
| POST | /api/v1/face-swap/image | Image face swap | 6 |
| POST | /api/v1/face-swap/video | Video face swap | max(9, 3 × ceil(serverMeasuredInputSeconds)) |
| POST | /api/v1/face-swap/gif | GIF face swap | max(9, 3 × ceil(serverMeasuredInputSeconds)) |
| POST | /api/v1/face-swap/multiple | Multiple-face image swap | 6 × selectedTargetFaces |
| GET | /api/v1/tasks | Task history | 0 |
Worked credit examples
66 creditsmax(9, 3 × ceil(4))12 creditsmax(9, 3 × ceil(8))24 creditsmax(9, 3 × ceil(18))54 creditsRequest fields by endpoint
Choose the route by target media, then send the exact multipart fields below. Optional restoration controls accept numbers from 0 to 1.
/api/v1/face-swap/imageImage face swap
Apply one source identity to one target photo.
- Required
sourceImagetargetImageconsent=true- Optional
faceRestoreVisibilityrestoreVisibility
/api/v1/face-swap/videoVideo face swap
Apply one source identity throughout an uploaded target video.
- Required
sourceImagetargetVideoconsent=true- Optional
faceRestoreVisibilityrestoreVisibility
/api/v1/face-swap/gifGIF face swap
Apply one source identity throughout an uploaded target GIF.
- Required
sourceImagetargetGifconsent=true- Optional
faceRestoreVisibilityrestoreVisibility
/api/v1/face-swap/multipleMultiple-face image swap
Replace one to ten selected faces in one group photo.
- Required
sourceImagetargetFace0consent=true- Optional
targetFace1...targetFace9faceBox0...faceBox9
/api/v1/tasksTask history
List tasks owned by the authenticated account.
- Optional
pagepageSizestatustaskType
Poll every media task
After a media POST returns taskId, send GET to that same media route with taskId as a query parameter while status is PENDING or PROCESSING. COMPLETED, FAILED and CANCELLED are terminal.
Bearer authentication
Send the key in every request as Authorization: Bearer YOUR_API_KEY. API keys inherit the verified account and its live credit balance. The application-level authenticated limit is 300 requests per minute; generation capacity remains queue-dependent.
Authorization: Bearer YOUR_API_KEYJavaScript and Python examples
These server-side examples submit two local files, reject HTTP failures, poll the matching task route and print the temporary result URL. Every field comes from the live OpenAPI contract.
JavaScriptNode.js 18+
import { readFile } from 'node:fs/promises';
const apiUrl = 'https://faceswapai.com/api/v1/face-swap/image';
const headers = {
Authorization: 'Bearer ' + process.env.FACESWAPAI_API_KEY,
};
const form = new FormData();
form.set('sourceImage', new Blob([await readFile('./source.jpg')]), 'source.jpg');
form.set('targetImage', new Blob([await readFile('./target.jpg')]), 'target.jpg');
form.set('consent', 'true');
const submitted = await fetch(apiUrl, { method: 'POST', headers, body: form });
if (!submitted.ok) throw new Error(submitted.status + ': ' + await submitted.text());
const { taskId } = await submitted.json();
let task;
do {
await new Promise((resolve) => setTimeout(resolve, 2000));
const polled = await fetch(apiUrl + '?taskId=' + encodeURIComponent(taskId), { headers });
if (!polled.ok) throw new Error(polled.status + ': ' + await polled.text());
task = await polled.json();
} while (task.status === 'PENDING' || task.status === 'PROCESSING');
console.log(task.status === 'COMPLETED' ? task.result?.url : task.result?.error);Pythonrequests 2.x
import os
import time
import requests
api_url = "https://faceswapai.com/api/v1/face-swap/image"
headers = {"Authorization": "Bearer " + os.environ["FACESWAPAI_API_KEY"]}
with open("source.jpg", "rb") as source, open("target.jpg", "rb") as target:
response = requests.post(
api_url,
headers=headers,
files={"sourceImage": source, "targetImage": target},
data={"consent": "true"},
timeout=60,
)
response.raise_for_status()
task_id = response.json()["taskId"]
while True:
time.sleep(2)
response = requests.get(api_url, headers=headers, params={"taskId": task_id}, timeout=30)
response.raise_for_status()
task = response.json()
if task["status"] not in ("PENDING", "PROCESSING"):
break
result = task.get("result") or {}
print(result.get("url") if task["status"] == "COMPLETED" else result.get("error"))Submit, then poll
A successful POST reserves the required credits and returns a taskId. Poll the same media route while status is PENDING or PROCESSING. COMPLETED, FAILED and CANCELLED are terminal. A queue or provider failure refunds a pending reservation exactly once.
curl --get https://faceswapai.com/api/v1/face-swap/image \
--header "Authorization: Bearer $FACESWAPAI_API_KEY" \
--data-urlencode "taskId=YOUR_TASK_ID"- PENDING
- Accepted and queued
- PROCESSING
- Running
- COMPLETED
- Result is available
- FAILED
- Stopped with a public error
- CANCELLED
- Cancelled
Formats and limits
Images accept JPG, PNG, WebP, GIF, BMP, HEIC or HEIF up to 30 MB. Video accepts MP4, MOV, WebM or AVI up to 100 MB and 600 seconds. 100 MB is about 1–2 minutes of typical 1080p phone video, so compress or trim longer clips. GIF targets are limited to 30 MB and 30 seconds. Multiple-face inputs are limited to 15 MB each and ten selected faces.
HTTP errors and retries
Do not retry 400, 401, 402, 403 or 413 responses without changing the request or account state. Back off on 429. A 500 or 503 can be retried after a delay; credit reservations are protected by the task refund path.
Current production boundaries
Plan against the public v1 contract that exists today, including what it does not claim.
- Media tasks are asynchronous and use polling. The current public v1 contract does not expose a webhook.
- There is no public batch route, idempotency-key field, live-camera route, published SLA or guaranteed completion time.
- API keys belong on a protected server. Results are temporary, generation capacity is queue-dependent and accepted failures use the documented refund path.
Consent, privacy and watermark
Every generation requires consent=true, meaning you have permission to use every uploaded face. Task media is temporary. There is no free trial: every task is paid with one-time credits, and every result has no watermark and no account email.
Face Swap API FAQ
Is there a free Face Swap API key?
Creating an API key is free. Generation uses the account credit balance. There is no free trial or free API tier: every task is paid with one-time credits, from 600 credits for $19.99.
Does the API support video and multiple faces?
Yes. Versioned routes cover image, video, GIF and multiple-face image tasks. Video and GIF pricing is calculated from measured media metadata.
How do I know when a result is ready?
Read taskId from the POST response and poll the matching GET route while status is PENDING or PROCESSING. COMPLETED includes the temporary result URL; FAILED and CANCELLED are also terminal.
Can I call the API directly from a browser?
Do not expose a secret key in browser code. Send requests from your own server, serverless function or other protected backend.