Name: Face to Style – Generate AI Portraits | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-face-to-creative-styles-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧑‍🎨 Face-to-Style Image Generator API (fofr/face-to-many)

## Overview
The Face-to-Style Image Generator API transforms a face photo into a variety of creative styles within seconds. It supports 3D, emoji, pixel art, video game, claymation, and toy styles. Simply provide a portrait image, select the desired style, and receive a series of stylized outputs back. This API is ideal for rapidly generating unique, high-quality face images for games, apps, or media content.

## Features
- Converts human portraits into multiple styles (3D, Emoji, Video Game, Pixels, Clay, Toy)
- Offers adjustable style strength, prompt strength, and denoising parameters
- Maintains high-quality facial details with advanced controls for seeds, negative prompts, and more
- Enables fine-tuning of the output’s depth and LoRA (if desired)
- Returns standardized JSON responses for easy integration

## Use Cases
1. Game Character Creation: Generate unique character faces in a variety of stylized formats.  
2. Social Media Filters: Produce fun, creative transformations for avatars or profile pictures.  
3. Marketing & Advertising: Quickly tailor face imagery to different promotional styles or campaigns.  
4. E-learning & Educational Tools: Create stylized character icons for courses, tutorials, or presentations.  
5. Entertainment & Art Projects: Experiment with artistic transformations of real faces for graphic designs or conceptual artworks.

## Visual Examples

Below are example images that demonstrate how the original input image can be transformed into a creative style. These images come from sample inputs and outputs in the API’s schema. Note that you can specify different styles in your request.

### Sample Input
![Sample input image of a person's face](https://replicate.delivery/pbxt/KW7Getr2zD5ECxySdBZtLmPa322lNkXrpkMdKcmxeaDmq2b1/MTk4MTczMTkzNzI1Mjg5NjYy.webp)

### Sample Output
![Sample output image in a clay style](https://replicate.delivery/xezq/QYCNMyAE6C7fd6GXc5Uy9KfqYKVTUfKpuGePXSFf2qLCkBseE/ComfyUI_00001_.png)

By adjusting parameters such as “style”, “prompt_strength”, and “denoising_strength”, you can create a wide range of results beyond just clay or pixel art—examining different creative looks while preserving fundamental facial features.

## Pricing
• 1 API unit = 1 image processed.  
• GET requests to check prediction status (GET /api/v1/magicapi/face-to-creative-styles-generator/predictions/{id}) are free and do not count toward API unit usage.  
• Various pricing tiers are available based on your usage volume. Contact us for more details or check your API.market dashboard for the latest pricing plans.

## API Documentation

### Base URL
All requests should be sent to:
```
https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator
```

### Authentication
Include your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```
Replace YOUR_API_MARKET_KEY with your actual key.

### Asynchronous Processing
This API processes image transformations asynchronously. After you submit a request, you will receive a prediction ID to query for status. Typical steps:

1. Send a POST request to create a prediction.
2. Receive a prediction ID in the response.
3. Use the prediction ID in a GET request to check status.
4. Poll the status endpoint until the prediction is completed.
5. Once status is "succeeded", retrieve and use the “output” in the response.

Most predictions finish within seconds, but it can take longer depending on complexity. Your implementation should:
- Poll every 1 second.  
- Timeout after 600 seconds (10 minutes).  
- Stop polling if status is "succeeded" or "failed".

### Endpoints

#### 1. Create a Prediction
• Endpoint:  
  POST /api/v1/magicapi/face-to-creative-styles-generator/predictions

• Description:  
  Submits an image and styling parameters to generate a creative face image.

• Example Request (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "a07f252abbbd832009640b27f063ea52d87d7a23a185ca165bec23b5adc8deaf",
    "input": {
      "image": "https://example.com/image.jpg",
      "style": "Clay",
      "prompt": "a person in a post apocalyptic war game",
      "lora_scale": 1,
      "negative_prompt": "",
      "prompt_strength": 4.5,
      "denoising_strength": 0.65,
      "instant_id_strength": 0.8,
      "control_depth_strength": 0.8
    }
  }'
```

• Example Response Body:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "a07f252abbbd832009640b27f063ea52d87d7a23a185ca165bec23b5adc8deaf",
  "status": "starting",
  "created_at": "2025-04-23T20:02:14.556Z"
}
```
A new prediction is now in progress. Use the "id" to check the status.

#### 2. Get Prediction Status
• Endpoint:  
  GET /api/v1/magicapi/face-to-creative-styles-generator/predictions/{id}

• Description:  
  Retrieves the current status of a prediction. If the prediction is complete, the "output" field will contain the stylized image URLs.

• Example Request (cURL):
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

• Example Response Body (Successful Output):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://prod.api.market/output-images/your_generated_image.png"
  ],
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```
If "status" is still "starting" or "processing", continue polling until it becomes "succeeded" (or "failed").

## Status Codes
- 200 OK: Request was successful.  
- 201 Created: Resource (prediction) successfully created.  
- 400 Bad Request: Invalid input parameters or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Your API key is valid but you lack permissions to perform the action.  
- 404 Not Found: The specified prediction or resource does not exist.  
- 429 Too Many Requests: Rate limit exceeded; wait before retrying.  
- 500 Internal Server Error: Something went wrong on the server.  
- 503 Service Unavailable: The service is temporarily unavailable; please retry later.

## Rate Limits
This API enforces rate limits to ensure fair usage and maintain performance. If you exceed the allowed request rate, you will receive a 429 Too Many Requests response. Implement backing-off or retry logic as needed.

## Error Handling
When an error occurs, the API returns standard JSON error messages. For example:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```
To recover:
- Check the “code” and “message” fields for clues.
- Correct the issues in your request (e.g., required fields).
- Retry if the error is transient (e.g., too many requests or temporary unavailability).

## Implementation Guide

Below are code samples in JavaScript, Python, and cURL. These examples illustrate how to properly create a prediction request, poll the status endpoint, and handle asynchronous responses.

### JavaScript Example

```javascript
// Example JavaScript code demonstrating polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator";

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: "a07f252abbbd832009640b27f063ea52d87d7a23a185ca165bec23b5adc8deaf",
        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 a maximum 10-minute 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; // 600000 ms = 10 minutes
  const POLL_INTERVAL = 1000; // 1 second
  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();

    if (prediction.status === "succeeded") {
      // Return the output images
      return prediction.output;
    }
    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait 1 second before checking again
    await delay(POLL_INTERVAL);
  }

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

// Example usage:
(async () => {
  try {
    const outputUrls = await createAndWaitForPrediction({
      image: "https://example.com/image.jpg",
      style: "Clay"
    });
    console.log("Prediction output:", outputUrls);
  } catch (err) {
    console.error(err);
  }
})();
```

### Python Example

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator"

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

    response = requests.post(f"{BASE_URL}/predictions", json=payload, headers=headers)
    if response.status_code not in [200, 201]:
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction.get("id")

    # Step 2: Poll for results (up to 10 minutes)
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # seconds
    POLL_INTERVAL = 1  # second
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        headers = {"x-magicapi-key": API_KEY}
        status_response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        if status_response.status_code != 200:
            raise Exception(f"API error: {status_response.status_code} {status_response.text}")

        prediction_data = status_response.json()
        if prediction_data["status"] == "succeeded":
            return prediction_data["output"]
        if prediction_data["status"] == "failed":
            raise Exception(f"Prediction failed: {prediction_data.get('error', 'Unknown error')}")

        time.sleep(POLL_INTERVAL)

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

# Example usage:
if __name__ == "__main__":
    try:
        result = create_and_wait_for_prediction({
            "image": "https://example.com/image.jpg",
            "style": "3D"
        })
        print("Prediction output:", result)
    except Exception as e:
        print("Error:", str(e))
```

### cURL Example

```bash
# 1. Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "a07f252abbbd832009640b27f063ea52d87d7a23a185ca165bec23b5adc8deaf",
    "input": {
      "image": "https://example.com/image.jpg",
      "style": "3D"
    }
  }'

# Sample response:
# {
#   "id": "abcd1234",
#   "status": "starting",
#   ...
# }

# 2. Poll the prediction status until "succeeded"
curl -X GET "https://prod.api.market/api/v1/magicapi/face-to-creative-styles-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Use minimal prompt complexity for faster results.  
- Keep polling intervals at 1 second to avoid unnecessary requests.  
- Cache or store repeated parameters (e.g., repeated seed) if you need consistent outputs.  
- Adjust “prompt_strength” and “denoising_strength” carefully to balance fidelity with creativity.

## FAQ
1. Can I transform non-human subjects (e.g., pets)?  
   - Yes, but results may vary. This model excels at human-like faces.

2. Is there a limit on image size?  
   - For best results, use standard portrait dimensions (e.g., 512x512). Large images may increase processing time.

3. How do I choose a style?  
   - The “style” parameter supports 3D, Emoji, Video game, Pixels, Clay, and Toy. Select one that meets your creative need.

4. Do I pay for each poll request?  
   - No. GET status checks are free and do not consume API units.

5. What happens if the image is not a face?  
   - The model attempts to stylize any contents, but results may not be optimal if no clear face is present.

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

Transform any portrait into 3D, emoji, pixel art & more. High-quality results in seconds. From $0.05/call. Try it free on API.market.

Face to Style – Generate AI Portraits | $0.05/call | API.market

🧑‍🎨 Face-to-Style Image Generator API (fofr/face-to-many)

PAYG

MagicAPI

Transform any portrait into 3D, emoji, pixel art, and more in seconds—unleash creative faces for games, apps, or media with rapid, high-quality results.