face-swap

Key Features

• FaceFusion-based face swap — replaces faces in images, videos and GIFs with advanced AI feature mapping.
• Multi-media support — works with images (up to 50 MB), GIFs (up to 50 MB) and videos (up to 15 min / 500 MB).
• Automatic face detection — detects faces in both source and target media without manual annotation.
• Seamless blending — produces natural-looking results with smooth skin tone and lighting matching.
• Simple two-input API — provide a source face URL and target media URL; the server handles the rest.
• Asynchronous processing with status polling for long-running video swaps.

Parameters

How to Use

1. Call POST /api/v3/face-swap/detect with a source_image URL to detect faces (free, no charge).
2. Check the returned faces array — if empty, try a different photo with a clearer frontal face.
3. Call POST /api/v3/face-swap with the source_face_url from step 1 and your target_media URL (paid).
4. Poll GET /api/v3/status/:id with the returned generation ID until the result is ready.

Code Examples

import os
import time
import requests

API_KEY = os.environ["AIRCUBE_API_KEY"]
HEADERS = {
    "Authorization": "Bearer " + API_KEY,
    "Content-Type": "application/json",
}

# Step 1: Detect face (free)
detect_resp = requests.post(
    "https://aircube.ai/api/v3/face-swap/detect",
    headers=HEADERS,
    json={"source_image": "https://example.com/face.jpg"},
    timeout=300,
)
detect_data = detect_resp.json()

faces = detect_data["data"]["faces"]
if not faces:
    print("No face detected, try another photo")
    exit(1)

source_face_url = faces[0]
print(f"Detected {len(faces)} face(s)")

# Step 2: Submit face swap (paid)
swap_resp = requests.post(
    "https://aircube.ai/api/v3/face-swap",
    headers=HEADERS,
    json={
        "source_face_url": source_face_url,
        "target_media": "https://example.com/target-video.mp4"
    },
    timeout=300,
)
swap_data = swap_resp.json()

if not swap_data["success"]:
    print("Error:", swap_data["error"]["message"])
    exit(1)

generation_id = swap_data["data"]["id"]
print(f"Swap submitted, generation ID: {generation_id}")

# Step 3: Poll for result
while True:
    status_resp = requests.get(
        f"https://aircube.ai/api/v3/status/{generation_id}",
        headers={"Authorization": "Bearer " + API_KEY},
    )
    status_data = status_resp.json()["data"]

    if status_data["status"] == "completed":
        print("Output URL:", status_data["output_url"])
        break
    elif status_data["status"] == "failed":
        print("Swap failed")
        break

    print(f"Status: {status_data['status']}, waiting...")
    time.sleep(5)

Pricing

Billing rules

• Image swap: $0.10 per swap.
• GIF swap: $0.10 per swap.
• Video swap: $0.10 per 15-second block (rounded up).
• Failed swaps are not charged.

Best Use Cases

• Content creation — create face-swapped videos and images for social media and marketing.
• Entertainment — produce fun face swap content for apps and platforms.
• Creative projects — experiment with face replacement for artistic and storytelling purposes.
• Batch processing — programmatically swap faces across large media libraries via the API.

Pro Tips

• Use clear, frontal face photos with good lighting as the source for the best swap quality.
• High-resolution target media produces higher-quality results.
• For videos, shorter clips process faster — trim to the essential segment before swapping.
• The source image should contain only one prominent face for the most predictable results.

Notes

• Outputs are saved to your generation history for 7 days.
• Video processing time scales with clip length — longer videos take more time.
• Content policy applies — harmful or prohibited content will be filtered.