API Documentation

Qubico Face Swap API Reference

Complete API documentation for advanced AI-powered face swapping in images and videos.

Quick Start

Get started with Face Swap API in minutes

Base URL

https://api.qubico.ai/v1/inference

Header Params

x-api-key: YOUR_API_KEY

Model ID

Qubico/image-toolkit, Qubico/video-toolkit

API Examples

Explore the different face swap options

Single Face Swap Request

{
    "model": "Qubico/image-toolkit",
    "task_type": "face-swap",
    "input": {
        "target_image": "https://i.ibb.co/LnLYwhR/66f41e64b1922.jpg",
        "swap_image": "https://i.ibb.co/m9BFL9J/ad61a39afd9079e57a5908c0bd9dd995.jpg"
    }
}

Parameters Reference

Details about the different parameters

Required Parameters

model

string

required

Model identifier. Use Qubico/image-toolkit for image processing or Qubico/video-toolkit for video processing.

task_type

string

required

Task type: face-swap for single face or video, multi-face-swap for multiple faces.

target_image

string (URL)

required

URL of the target image where faces will be replaced. Supports JPEG, PNG formats.

swap_image

string (URL)

required

URL of the source image containing the face(s) to be swapped in. Supports JPEG, PNG formats.

Optional Parameters

target_video

string (URL)

optional

URL of the target video for video face swap. Supports MP4, AVI, MOV formats. Use with video-toolkit model.

swap_faces_index

string

optional

Comma-separated indices of faces in the swap image to use. Default: "0" (first face). Example: "0,1,2".

target_faces_index

string

optional

Comma-separated indices of faces in the target image/video to replace. Default: "0" (first face). Example: "0,1,2".

Configuration Parameters

webhook_config

object

optional

Webhook configuration for receiving completion notifications. Contains endpoint and secret fields.

Response Format

Understand the structure of the API response

Successful Response

{
    "task_id": "task_12345678",
    "status": "completed",
    "result": {
        "output_url": "https://storage.qubico.ai/results/faceswap_result.jpg"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:15Z"
}

Error Handling

Learn how to handle errors

If you encounter an error, check the response status code and message for details.

Code Examples

Implement the API in different languages

cURL Request

curl -X POST "https://api.qubico.ai/v1/inference" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qubico/image-toolkit",
    "task_type": "face-swap",
    "input": {
        "target_image": "https://i.ibb.co/LnLYwhR/66f41e64b1922.jpg",
        "swap_image": "https://i.ibb.co/m9BFL9J/ad61a39afd9079e57a5908c0bd9dd995.jpg"
    }
}'

Rate Limits & Pricing

Understand the usage limits and pricing

Please refer to our Pricing Page for detailed information on rate limits and pricing.

Best Practices & Tips

✅ Recommended

•Use high-resolution images (1024x1024 or higher) for better results
•Ensure faces are clearly visible and well-lit
•Use frontal or near-frontal face angles for optimal swapping
•Test with single face swap before attempting multi-face
•Use webhook for long-running video processing tasks

❌ Avoid

•Very low resolution or blurry images
•Extreme face angles or profile views
•Images with multiple overlapping faces
•Using incorrect face indices for multi-face swap
•Processing very long videos without webhook setup

Technical Specifications

Image Support

Formats: JPEG, PNG, WebP
Max Size: 50MB per image
Resolution: Up to 4096x4096
Min Resolution: 256x256

Video Support

Formats: MP4, AVI, MOV
Max Size: 500MB per video
Max Duration: 60 seconds
Resolution: Up to 1920x1080