Build Something Fun with the API

The ai-face-swap.online API gives developers direct access to our face-swap engine. Whether you're building a photo app, a creative tool, or something totally unexpected, the API is designed to get out of your way and let you ship fast.

Authentication

Every request needs a valid API key passed in the request header. Generate your key from the dashboard, then include it like this:

Authorization: Bearer YOUR_API_KEY

Keep your key private. Treat it like a password — don't commit it to public repos or share it in client-side code.

Base URL

https://api.ai-face-swap.online/v1

Core Endpoints

• POST /swap — Submit a source image and a target face. Returns a job ID.
• GET /swap/{job_id} — Poll for the result. Returns status and, when ready, the output image URL.
• GET /account/usage — Check how many requests you've made this billing period.

Request Structure

Send a multipart/form-data request to /swap with the following fields:

Field	Type	Required	Description
source_image	file	Yes	The image containing the face to be replaced.
target_face	file	Yes	The face you want to swap in.
output_format	string	No	jpg or png. Defaults to jpg.

Example Response

{
  "job_id": "abc123xyz",
  "status": "processing",
  "estimated_seconds": 4
}

Once the job completes, polling /swap/{job_id} returns a result_url pointing to your finished image. URLs expire after 24 hours, so download and store the output on your end.

Rate Limits

Rate limits depend on your plan tier. By default, free-tier keys are capped at a set number of requests per minute and per day. If you hit a limit, the API returns a 429 Too Many Requests status. Back off briefly and retry — a simple exponential backoff strategy works well here.

Need higher throughput? Upgrade your plan from the dashboard to unlock increased limits.

Error Codes

• 400 — Bad request. Check your field names and file formats.
• 401 — Invalid or missing API key.
• 422 — No detectable face found in one of the submitted images.
• 429 — Rate limit reached.
• 500 — Something went wrong on our end. Rare, but it happens.

Ready to Start?

Grab your API key from the dashboard and make your first swap in minutes. The docs are here whenever you need a reference — but honestly, the best way to learn is to just start sending requests.

Get Your API Key