Name: FlashFace – AI Face Swaps | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-human-face-personalization-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧑‍🦱 High-Fidelity Face Personalization API (FlashFace)

## Overview
FlashFace is a specialized AI-powered image personalization API that preserves human facial identity with remarkable fidelity. It allows you to transform or generate images featuring an individual’s face based on reference images and textual prompts. Whether you need to generate photorealistic portraits, composite new scenes, or perform identity-preserving face swaps, FlashFace provides ultra-realistic outputs with minimal distortion.

Key strengths:
- High-fidelity identity preservation (keeps the reference face’s unique features recognizable).  
- Lightning-fast inference and image generation.  
- Flexible prompt inputs for controlling style, context, and negative prompts.  
- Multiple reference images to enhance accuracy and detail in the resulting personalized images.

## Features
- Face Preservation: Maintains accurate facial features from user-provided reference images.  
- High Resolution: Produces images with UHD 4K-level details, ensuring professional-grade quality.  
- Control over Style & Prompting: Adjust negative/positive prompts, steps, guidance, and more to achieve your desired look and feel.  
- Multiple Output Formats: Generate images in WEBP, JPG, or PNG format.  
- Fine-tune and Experiment: Easily modify parameters like seed, text guidance scale, and bounding boxes for iterative experimentation.

## Use Cases
1. Personalized Avatars: Generate custom avatars, profile pictures, or stylized images for social media and gaming platforms while keeping the subject instantly recognizable.  
2. Advertising & Marketing: Create variations of a model’s photo shoot or marketing creatives featuring different backgrounds, styles, or themes.  
3. Creative Media & Film: Swiftly mock up scenes or test new character looks without arranging a full studio shoot.  
4. E-Commerce: Display a range of products or attire on models who retain a consistent identity across product catalogs.  
5. Art & Graphic Design: Infuse unique character likeness into illustrations, portraits, or conceptual art projects.

## Visual Examples

Below are some example images referenced in the schema. These images demonstrate how reference faces and output images might look. They help illustrate the input-output transformation that FlashFace performs.

### Reference Face Examples
Here are a few sample reference images (inputs) that could be used to personalize the model. You can provide one or more face images:

![Sample reference face 1 showing a typical user-provided face reference](https://replicate.delivery/pbxt/KnE00y2FMOW0170eWcdyDUe09FZLCKiJrDwYYCUp42yWdni0/avatar.png)

![Another sample face reference image](https://example.com/image.jpg)

### Output Example
The following are example outputs after processing. In this particular example, the user’s prompt was:  
“A handsome young man with long brown hair is sitting in the desert”  

![Sample output image 0 from personalization](https://replicate.delivery/pbxt/dxLVR2tFcuIMLVKvgLStZDLzHbX364z1OXiK8i1GyLlVfiWJA/image_0.webp)  
![Sample output image 1 from personalization](https://replicate.delivery/pbxt/ndKec45tLK2tUCBkIFXqx5AgHtdFYoo9KPRcNVDlmH4reFtSA/image_1.webp)

These examples demonstrate how FlashFace maintains the subject’s identity and integrates them into different contexts.

## Pricing
• 1 API unit = 1 image processed  
• GET requests to check prediction status (GET /api/v1/magicapi/ai-human-face-personalization-api/predictions/{id}) are free and do not count toward usage.  
• Multiple pricing tiers are available based on usage volume. Contact us for details on bulk or enterprise pricing.

## API Documentation

### Base URL
All API requests should be made to:  
```
https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api
```

### Authentication
Include your API key in the request header:

```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes predictions asynchronously. The typical flow is:

1. Submit a POST request for a prediction.  
2. Receive a response containing a prediction ID.  
3. Poll the GET endpoint with the prediction ID to check the status.  
4. Continue polling until the status changes to “succeeded” (or “failed”).

A recommended polling interval is 1 second. If 10 minutes (600 seconds) elapse and the prediction status has not resolved, consider it a timeout.

---

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• Endpoint: /api/v1/magicapi/ai-human-face-personalization-api/predictions  
• Description: Creates a new flash-face prediction job with the specified input parameters.

Example request body (JSON):
```json
{
  "version": "edb17f54faec253ee86e58e0b5f18f24a89c4e31fe7fcefa970e13d8ad934117",
  "input": {
    "seed": 0,
    "steps": 50,
    "num_sample": 2,
    "face_guidance": 2.5,
    "lamda_feature": 0.9,
    "output_format": "webp",
    "output_quality": 80,
    "negative_prompt": "nsfw",
    "positive_prompt": "A handsome young man with long brown hair is sitting in the desert",
    "reference_face_1": "https://replicate.delivery/pbxt/KnE00y2FMOW0170eWcdyDUe09FZLCKiJrDwYYCUp42yWdni0/avatar.png",
    "face_bounding_box": "[0., 0., 0., 0.]",
    "text_control_scale": 7.5,
    "default_negative_prompt": "blurry, ugly, tiling, poorly drawn hands...",
    "default_position_prompt": "best quality, masterpiece, ultra-detailed...",
    "step_to_launch_face_guidance": 700
  }
}
```

Example curl request:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "edb17f54faec253ee86e58e0b5f18f24a89c4e31fe7fcefa970e13d8ad934117",
    "input": {
      "seed": 0,
      "steps": 50,
      "num_sample": 2,
      "face_guidance": 2.5,
      "lamda_feature": 0.9,
      "output_format": "webp",
      "output_quality": 80,
      "negative_prompt": "nsfw",
      "positive_prompt": "A handsome young man with long brown hair is sitting in the desert",
      "reference_face_1": "https://replicate.delivery/pbxt/KnE00y2FMOW0170eWcdyDUe09FZLCKiJrDwYYCUp42yWdni0/avatar.png",
      "face_bounding_box": "[0., 0., 0., 0.]",
      "text_control_scale": 7.5,
      "default_negative_prompt": "blurry, ugly, tiling, poorly drawn hands...",
      "default_position_prompt": "best quality, masterpiece, ultra-detailed...",
      "step_to_launch_face_guidance": 700
    }
  }'
```

Example successful response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "edb17f54faec253ee86e58e0b5f18f24a89c4e31fe7fcefa970e13d8ad934117",
  "status": "starting",
  "created_at": "2025-04-23T20:02:10.882Z"
}
```

---

#### 2. Get Prediction Status
• Method: GET  
• Endpoint: /api/v1/magicapi/ai-human-face-personalization-api/predictions/{id}  
• Description: Retrieve the current status and any output images associated with a prediction.  
• Path Parameters:  
  - id (string) — The unique prediction ID returned by the POST endpoint.

Example curl request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example successful response when the prediction has completed:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://replicate.delivery/pbxt/dxLVR2tFcuIMLVKvgLStZDLzHbX364z1OXiK8i1GyLlVfiWJA/image_0.webp",
    "https://replicate.delivery/pbxt/ndKec45tLK2tUCBkIFXqx5AgHtdFYoo9KPRcNVDlmH4reFtSA/image_1.webp"
  ],
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

---

## Status Codes
- 200 OK: Request was successful.  
- 201 Created: A new resource (prediction) was successfully created.  
- 400 Bad Request: Invalid or missing input parameters.  
- 401 Unauthorized: Missing or invalid API key in headers.  
- 403 Forbidden: The request is understood but you lack permissions to perform it.  
- 404 Not Found: The specified resource or endpoint does not exist.  
- 429 Too Many Requests: You have exceeded your current rate limit.  
- 500 Internal Server Error: A generic server error occurred.  
- 503 Service Unavailable: The service is currently unavailable or under maintenance.

## Rate Limits
API requests may be rate-limited based on your plan. If you exceed your rate limit, you will receive a 429 Too Many Requests response. In such cases:
- Wait before retrying.  
- Implement exponential backoff or other polite retry strategies.

## Error Handling
When the API encounters an error, it typically returns a JSON error structure. Common errors include invalid input parameters or exceeding rate limits. Example:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```
Best practices:
- Check the HTTP status code.  
- If 4xx, correct client-side parameters or request logic.  
- If 5xx, it may be a temporary server issue. Retry with exponential backoff.  
- For rate limits (429), wait until the limit resets before retrying.

## Implementation Guide

Below are code samples demonstrating how to:
1. Authenticate using your API key.  
2. Submit a prediction request.  
3. Poll the prediction status until completion or failure.  
4. Handle errors and timeouts gracefully.

### JavaScript Example

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "edb17f54faec253ee86e58e0b5f18f24a89c4e31fe7fcefa970e13d8ad934117",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    // Handle failure
    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

### Python Example

```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }

    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "edb17f54faec253ee86e58e0b5f18f24a89c4e31fe7fcefa970e13d8ad934117",
            "input": input_data
        }
    )

    if response.status_code != 200 and response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks

    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers=headers
        )

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]

        # Handle failure
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        # Wait before next poll
        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")
```

### cURL Example

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "edb17f54faec253ee86e58e0b5f18f24a89c4e31fe7fcefa970e13d8ad934117",
    "input": {
      "seed": 0,
      "positive_prompt": "A handsome young man with long brown hair is sitting in the desert",
      "reference_face_1": "https://example.com/image.jpg"
    }
  }'

# Response will contain a prediction ID like:
# {"id": "abcd1234", "status": "starting"}

# Step 2: Poll for the prediction status until "succeeded"
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-human-face-personalization-api/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Use minimal, efficient prompts to keep generation times low.  
- Reuse the same reference faces if possible to avoid repeated uploads.  
- Adjust the number of steps to manage speed vs. quality. Higher steps can improve image details but also increase processing times.

## FAQ
1. Can I upload multiple reference faces?  
   • Yes, you can supply up to four reference faces for enhanced accuracy.

2. How does the API preserve identity while also respecting style or negative prompts?  
   • The API uses face reference guidance and lamda_feature to prioritize identity features, while text_control_scale and prompts guide stylistic output.

3. What if the generated images are not sufficiently personalized or contain artifacts?  
   • You can tweak face_guidance, lamda_feature, prompts, and the step_to_launch_face_guidance parameter. Increasing the steps or face guidance can help refine results.

4. Is there a limit to the resolution of the generated images?  
   • The model can produce high-resolution outputs, but exact limits may depend on your usage plan and performance constraints.

5. Do status checks consume API units?  
   • No, GET requests to check prediction status are free and do not count toward usage.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Generate ultra-realistic portraits & face swaps from images. Preserves facial identity with high fidelity. From $0.05/call. Try it free on API.market.