# face-swap

> AI Face Swap replaces faces in images, videos and GIFs using advanced FaceFusion technology. Upload a source face photo and target media — the AI detects faces, maps features and produces a seamless swap. Supports video up to 15 minutes / 500 MB, images up to 50 MB, and GIFs up to 50 MB.

- **Provider:** AirCube
- **Category:** face-swap
- **Price:** $0.1000 per run

## 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

| Parameter | Required | Description |
| --- | --- | --- |
| `source_image` | Yes (detect) | URL of the source face photo for the /detect endpoint. Should contain a clear, frontal face. |
| `source_face_url` | Yes (swap) | Detected face URL returned by the /detect endpoint. |
| `target_media` | Yes (swap) | URL of the target image, video or GIF where the face will be swapped. |

## 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

### Python

```python
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)
```

### Node.js

```javascript
const API_KEY = process.env.AIRCUBE_API_KEY;
const headers = {
  "Authorization": "Bearer " + API_KEY,
  "Content-Type": "application/json",
};

// Step 1: Detect face (free)
const detectResp = await fetch("https://aircube.ai/api/v3/face-swap/detect", {
  method: "POST",
  headers,
  body: JSON.stringify({ source_image: "https://example.com/face.jpg" }),
});
const detectData = await detectResp.json();

const faces = detectData.data.faces;
if (!faces.length) {
  console.error("No face detected, try another photo");
  process.exit(1);
}

const sourceFaceUrl = faces[0];
console.log(`Detected ${faces.length} face(s)`);

// Step 2: Submit face swap (paid)
const swapResp = await fetch("https://aircube.ai/api/v3/face-swap", {
  method: "POST",
  headers,
  body: JSON.stringify({
    source_face_url: sourceFaceUrl,
    target_media: "https://example.com/target-video.mp4",
  }),
});
const swapData = await swapResp.json();

if (!swapData.success) {
  console.error("Error:", swapData.error.message);
  process.exit(1);
}

const generationId = swapData.data.id;
console.log("Swap submitted, generation ID:", generationId);

// Step 3: Poll for result
while (true) {
  const statusResp = await fetch(
    `https://aircube.ai/api/v3/status/${generationId}`,
    { headers: { "Authorization": "Bearer " + API_KEY } }
  );
  const statusData = (await statusResp.json()).data;

  if (statusData.status === "completed") {
    console.log("Output URL:", statusData.output_url);
    break;
  } else if (statusData.status === "failed") {
    console.error("Swap failed");
    break;
  }

  console.log(`Status: ${statusData.status}, waiting...`);
  await new Promise(r => setTimeout(r, 5000));
}
```

### cURL

```curl
# Step 1: Detect face (free)
curl -X POST "https://aircube.ai/api/v3/face-swap/detect" \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_image": "https://example.com/face.jpg"}'

# Response: { "success": true, "data": { "faces": ["https://..."] } }

# Step 2: Submit face swap (paid, use face URL from step 1)
curl -X POST "https://aircube.ai/api/v3/face-swap" \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_face_url": "<face_url_from_step_1>",
    "target_media": "https://example.com/target-video.mp4"
  }'

# Response: { "success": true, "data": { "id": "<generation_id>", "status": "processing" } }

# Step 3: Poll for result
curl "https://aircube.ai/api/v3/status/<generation_id>" \
  -H "Authorization: Bearer $AIRCUBE_API_KEY"
```

## Pricing

| Resolution | Duration | Cost |
| --- | --- | --- |
| Image | per swap | $0.10 |
| GIF | per swap | $1.00 |
| Video | per 15s block | $1.00 |

### 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.

## FAQ

**Q: What is the Face Swap API?**

AI Face Swap replaces faces in images, videos and GIFs using advanced FaceFusion technology. Upload a source face photo and target media — the AI detects faces, maps features and produces a seamless swap. Supports video up to 15 minutes / 500 MB, images up to 50 MB, and GIFs up to 50 MB.

**Q: Why are there two endpoints?**

The /detect endpoint is free and lets you verify a usable face exists in the source photo before committing to a paid swap. Only the swap endpoint charges credits.

**Q: What media formats are supported?**

Images (JPEG, PNG, WebP up to 50 MB), GIFs (up to 50 MB), and videos (MP4, MOV up to 500 MB / 15 minutes).

**Q: How does pricing work for videos?**

Videos are priced at $0.10 per 15-second block, rounded up. A 40-second video costs $0.30 (3 blocks).

**Q: How long does processing take?**

Images and GIFs complete in seconds. Videos depend on length — expect roughly 1-2 minutes per minute of video.

**Q: Can I use Face Swap outputs commercially?**

Yes — swapped media is yours to use. Ensure you have rights to the source and target media.