Name: PhotoMaker – Personalized AI Photos | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-photo-avatar-style-generator
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Versatile Photo & Avatar Style Generator API (PhotoMaker)

## Overview
The PhotoMaker API quickly transforms uploaded images into unique photos, avatars, and paintings in various artistic styles. Powered by a flexible stylization engine, you can generate high-quality, personalized images for diverse applications—ranging from social profile avatars to concept art.

This API is particularly useful for creating imaginative portraits, ultra-realistic or artistic renditions, and custom images that blend multiple input photos or adhere to a style prompt. Results are delivered via an asynchronous processing workflow.

## Features
- Rapid image stylization in multiple styles (cinematic, digital art, fantasy, etc.).  
- Ability to generate up to four images in parallel.  
- Configurable guidance scale (for style intensity), negative prompts, and style strength ratio.  
- Asynchronous processing with easy integration for polling the status of predictions.  
- Safe default settings; optional disabling of the safety checker.  
- Customizable prompts and negative prompts for fine-grained control over outputs.

## Use Cases
1. Profile Avatars: Create stylized personal avatars for social media, gaming, or professional profiles.  
2. Digital Art Concepts: Rapidly draft unique concepts for characters, environments, or marketing materials.  
3. Merch & Product Designs: Generate custom designs for t-shirts, posters, or album covers.  
4. Visual Storyboarding: Quickly visualize scene concepts for film, animation, or comics.  
5. Photo Enhancements: Apply stylized overlays to add artistic flair to existing images.

## Visual Examples

Below are some example inputs and outputs showcasing the API’s capabilities. These are pulled from sample references within the schema.

### Sample Input Image (Lenna)
![Sample input image (Lenna)](https://replicate.delivery/pbxt/KFRveCbE71qFTQGSF509CXYC16qB1bcZmAWq8O172ael04Ga/lenna.jpg)

### Sample Output Images
When applying certain style prompts or configurations, example outputs might look like these:

![Sample output image 1 from PhotoMaker](https://replicate.delivery/pbxt/WwkQofrF9CQuJ6v3slDfyha3YB1teWJpnWLBsVSdvfeFh2tRC/image_0.png)

![Sample output image 2 from PhotoMaker](https://replicate.delivery/pbxt/0eNDe5B73njlkkSJfJeZ4Riiww3OYci679bnbaf0cNzLh2tRC/image_1.png)

## Pricing
• 1 API unit = 1 image generated  
• Checking prediction status with GET /api/v1/magicapi/ai-photo-avatar-style-generator/predictions/{id} is free and does not consume API units  
• Multiple pricing tiers are available depending on monthly usage volume  

Contact the API.market team for detailed pricing options.

## API Documentation

Below is a comprehensive reference for integrating with the PhotoMaker API.

### Base URL
All requests should be made to:

```
https://prod.api.market/api/v1/magicapi/ai-photo-avatar-style-generator
```

### Authentication
Use your API key from API.market to authenticate all requests. Include the following header:

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

### Asynchronous Processing
Predictions (image generation) take place asynchronously:
1. Send a POST request to create a new prediction.  
2. Receive a prediction ID in the response.  
3. Poll the GET endpoint with the prediction ID to retrieve the status.  
4. Continue polling until the status changes to "succeeded" (or "failed").  

If "succeeded," the response includes one or more output image URLs. If "failed," the response includes an error message.

**Recommended Polling Guidelines**
- Wait 1 second between each status check.  
- Implement a maximum timeout of 600 seconds (10 minutes).  

### Endpoints

#### 1. Create a prediction
POST /api/v1/magicapi/ai-photo-avatar-style-generator/predictions

Creates a new prediction job.

• Method: POST  
• Path: /predictions  
• Body Params (JSON):
  - version (string, optional): Defaults to "467d062309da518648ba89d226490e02b8ed09b5abc15026e54e31c5a8cd0769"  
  - input (object): Contains parameters such as "input_image", "prompt", "num_outputs", etc.

Example Request:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-style-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "467d062309da518648ba89d226490e02b8ed09b5abc15026e54e31c5a8cd0769",
    "input": {
      "prompt": "A girl img riding dragon over a whimsical castle, 3d CGI, art by Pixar, half-body, screenshot from animation",
      "input_image": "https://replicate.delivery/pbxt/KFRveCbE71qFTQGSF509CXYC16qB1bcZmAWq8O172ael04Ga/lenna.jpg",
      "style_name": "(No style)",
      "num_steps": 50,
      "num_outputs": 2,
      "guidance_scale": 5,
      "negative_prompt": "realistic, photo-realistic, worst quality, greyscale, bad anatomy, bad hands, error, text",
      "style_strength_ratio": 35
    }
  }'
```

Example Successful Response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "467d062309da518648ba89d226490e02b8ed09b5abc15026e54e31c5a8cd0769",
  "status": "starting",
  "created_at": "2025-04-23T20:02:17.128Z"
}
```

#### 2. Get prediction status & results
GET /api/v1/magicapi/ai-photo-avatar-style-generator/predictions/{id}

Retrieves the status and (if completed) the outputs of a prediction.

• Method: GET  
• Path: /predictions/{id}  
• Path Params:
  - id: The prediction ID returned by the create operation.

Example Request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-style-generator/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example Success Response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://replicate.delivery/pbxt/WwkQofrF9CQuJ6v3slDfyha3YB1teWJpnWLBsVSdvfeFh2tRC/image_0.png",
    "https://replicate.delivery/pbxt/0eNDe5B73njlkkSJfJeZ4Riiww3OYci679bnbaf0cNzLh2tRC/image_1.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"
}
```

### Status Codes
- 200 OK: Request succeeded.  
- 201 Created: The resource (prediction) was successfully created.  
- 400 Bad Request: Missing or invalid parameters in the request.  
- 401 Unauthorized: Invalid or missing API key.  
- 403 Forbidden: Valid key but insufficient permissions.  
- 404 Not Found: Resource or prediction ID doesn’t exist.  
- 429 Too Many Requests: Exceeded API usage limit or rate limit.  
- 500 Internal Server Error: Something went wrong on the server side.  
- 503 Service Unavailable: Temporary infrastructure issue. Retry later.

## Rate Limits
Requests may be subject to rate limiting. If you receive a 429 status code, reduce your request frequency and consider increasing your plan. Always implement graceful error handling and retry logic with exponential backoff.

## Error Handling
Responses that indicate errors typically include an "error" key with a message describing the issue. Example:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'input_image' is required",
    "status": 400
  }
}
```

**Common Errors**  
- invalid_parameter: One or more parameters are malformed or missing.  
- authentication_failed: Missing or invalid API key.  
- rate_limit_exceeded: The service has throttled or denied the request due to usage limits.

**Recommended Handling**  
1. Validate inputs before making requests.  
2. On transient errors (5xx or 429), implement retries with exponential backoff.  
3. If you encounter unrecoverable errors, log them and/or alert your development team.

## Implementation Guide

### Example Code

Below are sample implementations in JavaScript, Python, and cURL that show the recommended approach for asynchronous requests with polling.

#### JavaScript (Node.js) Example
```javascript
// Replace with your actual API key
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-style-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({
        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

  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 prediction.output;
    }

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

    await delay(POLL_INTERVAL);
  }

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

// Usage example
(async () => {
  try {
    const results = await createAndWaitForPrediction({
      prompt: "A girl img riding dragon over a whimsical castle, 3d CGI, art by Pixar",
      input_image: "https://example.com/image.jpg"
    });
    console.log("Prediction results:", results);
  } 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/ai-photo-avatar-style-generator"

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={"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

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

    while time.time() - start_time < MAX_TIMEOUT:
        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()

        if prediction["status"] == "succeeded":
            return prediction["output"]
        elif prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

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

# Usage:
if __name__ == "__main__":
    try:
        input_data = {
            "prompt": "A fantasy scene with img wearing a medieval costume",
            "input_image": "https://example.com/image.jpg"
        }
        outputs = create_and_wait_for_prediction(input_data)
        print("Generated Images:", outputs)
    except Exception as e:
        print("Error:", e)
```

#### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-style-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "prompt": "A futuristic portrait of img in neonpunk style",
      "input_image": "https://example.com/image.jpg"
    }
  }'

# Response might look like:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Check status
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-style-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
  
# Repeat GET requests until status = "succeeded"
```

### Performance Optimization
- Use a single prompt and minimal style references for faster generation.  
- Bundle required images or references into one request to reduce overhead.  
- Maintain a 1-second polling interval to avoid unnecessary requests.

## FAQ
1. **Do I need to supply a seed value?**  
   You can optionally specify a seed for reproducibility. If omitted, a random seed is used.  

2. **Can I generate multiple styles at once?**  
   You can only select one style_name per request, but you can create simultaneous requests with different style_name parameters.  

3. **What format are the output images in?**  
   URLs typically point to PNG or JPEG images.  

4. **How long are generated images stored?**  
   Images are hosted temporarily. For long-term storage, download and store them in your system.

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

Enjoy experimenting with the Versatile Photo & Avatar Style Generator API (PhotoMaker)!

Generate custom photos, avatars, and art from images. Preserves identity from just one photo. From $0.05/call. Try it free on API.market.