FaceSwap API Documentation

Welcome to the FaceSwap API documentation. Here you'll find comprehensive guides and documentation to help you start working with our API as quickly as possible.

Introduction

The FaceSwap API provides powerful face swapping capabilities that you can integrate into your applications. Our API offers multiple methods to suit different needs, from basic swaps to advanced multi-face operations.

With our API, you can:

Swap faces between two different images
Apply advanced face swapping with enhanced detail preservation
Swap a single face to multiple faces in another image
Exchange faces within the same image

Our API is designed to be easy to use, reliable, and to produce high-quality results for a variety of use cases.

Base URL

https://aiapi.aiphotocraft.com/

Authentication

All API requests require authentication using an API key. You can obtain your API key from the Developer Dashboard.

API Key Authentication

Include your API key in the request header:

X-Api-Key: YOUR_API_KEY

Example Request with Authentication

curl -X POST https://aiapi.aiphotocraft.com/api/faceswap/basicswap \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_image": "https://example.com/source.jpg",
    "target_image": "https://example.com/target.jpg"
  }'

Keep Your API Key Secure

Your API key is a secret. Do not share it in publicly accessible areas such as GitHub, client-side code, or forums. Requests should be made from your server, not from client browsers.

API Reference

BasicSwap

POST/api/faceswap/basicswap

Swap faces between 2 images. Each image must contain exactly 1 face. Optionally enhance the result using GFPGAN.

Parameters

Name	Type	Required	Description
srcimage	file (formData)	Required	Source image for swap.
targetimage	file (formData)	Required	Target image for swap.
enhance	string (formData)	Required	Either 'true' or 'false'. Enhance the result after swap.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://aiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://aiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

curl -X POST "https://aiapi.aiphotocraft.com/api/faceswap/basicswap" \
-H "accept: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "srcimage=@source.jpg;type=image/jpeg" \
-F "targetimage=@target.jpg;type=image/jpeg" \
-F "enhance=true"

Couple FaceSwap

POST/api/faceswap/faceswap2

Swaps two faces from two images having two faces and gives the image with swapped face.

Parameters

Name	Type	Required	Description
srcimage	file (formData)	Required	Source image for swap.
targetimage	file (formData)	Required	Target image for swap.
swap_index	text (formData)	Optional	Tuple of indexes to swap.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://aiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://aiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

curl -X POST "https://aiapi.aiphotocraft.com/api/faceswap/faceswap2" \
-H "accept: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "srcimage=@source.jpg;type=image/jpeg" \
-F "targetimage=@target.jpg;type=image/jpeg" \
-F "swap_index=0,1"

Swap1from2

POST/api/faceswap/swap1from2

Swaps two faces from two images having two faces and gives the image with swapped face.

Parameters

Name	Type	Required	Description
srcimage	file (formData)	Required	Source image for swap having 2 faces.
targetimage1	file (formData)	Required	First target image for swap having 1 face.
targetimage2	file (formData)	Required	Second target image for swap having 1 face.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://aiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://aiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

curl -X POST "https://aiapi.aiphotocraft.com/api/faceswap/swap1from2" \
-H "accept: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "srcimage=@source.jpg;type=image/jpeg" \
-F "targetimage1=@target1.jpg;type=image/jpeg" \
-F "targetimage2=@target2.jpg;type=image/jpeg"

SwapFaceSameImage

POST/api/faceswap/swapfacesameimage

Swaps two faces from 1 image having 2 peoples inside it having clear face.

Parameters

Name	Type	Required	Description
srcimage	file (formData)	Required	Source image having two faces for swap.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://aiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://aiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

curl -X POST "https://aiapi.aiphotocraft.com/api/faceswap/swapfacesameimage" \
-H "accept: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "srcimage=@source.jpg;type=image/jpeg"

Error Handling

The FaceSwap API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with our servers.

HTTP Status Codes

Status Code	Description
200 - OK	The request was successful.
400 - Bad Request	The request was invalid or cannot be otherwise served.
401 - Unauthorized	Authentication credentials were missing or incorrect.
403 - Forbidden	The request is understood, but it has been refused or access is not allowed.
404 - Not Found	The requested resource could not be found.
429 - Too Many Requests	You have exceeded the rate limit.
500 - Server Error	Something went wrong on our end.

Error Response Format

When an error occurs, the API will return a JSON response with an error object containing details about the error:

{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "Source image parameter is required",
    "details": {
      "parameter": "srcimage"
    }
  }
}

Common Error Codes

Error Code	Status	Description
invalid_parameter	400	A required parameter is missing or invalid.
api_key_required	401	The X-Api-Key header is missing.
invalid_api_key	401	The provided API key is invalid or has been revoked.
rate_limit_exceeded	429	You have exceeded your rate limit.
no_face_detected	400	No face was detected in the provided image.
face_count_mismatch	400	The image contains an incorrect number of faces for this operation.
face_index_out_of_range	400	The specified face index is out of range.
invalid_image_format	400	The provided image is in an unsupported format.
server_error	500	An unexpected error occurred on our servers.

Example Error Responses

Missing API Key (401)

{
  "success": false,
  "error": {
    "code": "api_key_required",
    "message": "API key is required. Please include X-Api-Key header in your request."
  }
}

No Face Detected (400)

{
  "success": false,
  "error": {
    "code": "no_face_detected",
    "message": "No face was detected in the source image.",
    "details": {
      "image": "srcimage"
    }
  }
}

Rate Limits

To ensure the stability and availability of the FaceSwap API for all users, we implement rate limiting on API requests. Rate limits vary based on your subscription plan.

Rate limits are applied on a per-API-key basis, not per-endpoint.

Rate Limit Headers

The API includes the following headers in all responses to help you manage your rate limits:

Header	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make per hour.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

Rate Limit Plans

Plan	Requests per Hour	Requests per Day
Free	50	500
Basic	200	2,000
Pro	1,000	10,000
Enterprise	Custom	Custom

Handling Rate Limits

If you exceed your rate limit, the API will return a 429 Too Many Requests response. The response will include the standard rate limit headers, so you can determine when you're able to make requests again.

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your rate limit. Please try again later.",
    "details": {
      "reset_at": 1620000000
    }
  }
}

Getting Started

API Reference

Guides

FaceSwap API Documentation

Introduction

Base URL

Authentication

API Key Authentication

Example Request with Authentication

Keep Your API Key Secure

API Reference

BasicSwap

Parameters

Task Status Endpoint

Example Request

Example Response

Response Status Codes

Examples

Couple FaceSwap

Parameters

Task Status Endpoint

Example Request

Example Response

Response Status Codes

Examples

Swap1from2

Parameters

Task Status Endpoint

Example Request

Example Response

Response Status Codes

Examples

SwapFaceSameImage

Parameters

Task Status Endpoint

Example Request

Example Response

Response Status Codes

Examples

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Example Error Responses

Missing API Key (401)

No Face Detected (400)

Rate Limits

Rate Limit Headers

Rate Limit Plans

Handling Rate Limits