Name: PhotoMaker – AI Photo & Avatar Generation | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-photo-avatar-image-generator
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 📸 Ultra-Fast AI Photo & Avatar Generator API (PhotoMaker)

## Overview
The Ultra-Fast AI Photo & Avatar Generator API (PhotoMaker) instantly creates realistic photos, custom avatars, and artistic portraits in any style. Designed for speed and quality, you can generate high-fidelity images—from photographic realism to stylized art—within seconds. Whether you’re enhancing personal photos, designing characters for games, or creating product mockups, this API delivers flexible and rapid results.

## Features
- Generate multiple styles: Photographic, Cinematic, Digital Art, Fantasy, and more  
- High-speed processing for near-instant image results  
- Flexible prompts for diverse output (e.g., full-body portraits, headshots, themed styles, etc.)  
- Customizable parameters: guidance scale, number of outputs, step count, style strength, and more  
- Input multiple images to blend or refine style and details  

## Use Cases
1. Profile and Social Media Avatars: Generate unique, eye-catching avatars for personal or brand use.  
2. Product Visuals and Mockups: Quickly produce product images in various styles or settings for e-commerce listings.  
3. Character Design and Concept Art: Jump-start creative workflows for games, animations, or storytelling.  
4. Marketing and Advertising: Rapidly produce branded visuals for campaigns, featuring different artistic styles.  
5. Personalized Artwork: Transform photos into artistic adaptations (e.g., paintings, cartoons, neonpunk art).

## Visual Examples

Here are some examples demonstrating the API’s capabilities:

### Sample Input Image
![Sample input image that can be used to generate new avatars or artistic portraits](https://replicate.delivery/pbxt/KFkSv1oX0v3e7GnOrmzULGqCA8222pC6FI2EKcfuCZWxvHN3/newton_0.jpg)

In this example, the prompt might be:  
“A photo of a scientist img receiving the Nobel Prize”  
Here 'img' serves as a placeholder/trigger word that will be replaced by the input image.

### Sample Output Image
![Sample output generated from the AI using the input image and specified prompt](https://replicate.delivery/pbxt/WPelbpCPIDTmIiye4CGXbQPBhvegbbUH7fk8DvB4GqsRUC4IB/image_0.png)

The output depicts a stylized version of the scientist receiving an award, showcasing the model’s ability to transform prompts into visually coherent images.

## Pricing
- 1 API unit = 1 image processed.  
- GET requests to check prediction status (GET /api/v1/magicapi/ai-photo-avatar-image-generator/predictions/{id}) are free and do not count toward API unit usage.  
- Different pricing tiers are available based on usage volume; higher-volume tiers provide lower per-image costs.

## API Documentation

### Base URL
All API requests should be made to:
```
https://prod.api.market/api/v1/magicapi/ai-photo-avatar-image-generator
```

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

### Asynchronous Processing
This API uses asynchronous processing for predictions. The typical flow is:
1. Submit a prediction request (POST /api/v1/magicapi/ai-photo-avatar-image-generator/predictions).  
2. Receive a prediction ID in the response.  
3. Poll the GET /api/v1/magicapi/ai-photo-avatar-image-generator/predictions/{id} endpoint to check status  
   - Poll every 1 second.  
   - Apply a maximum timeout of 600 seconds (10 minutes).  
   - Continue polling while status is “starting” or “processing.”  
   - If status is “succeeded,” retrieve and use the output.  
   - If status is “failed,” handle the error.  

### Endpoints

---

#### 1. Create a Prediction
• Method: POST  
• Endpoint: /api/v1/magicapi/ai-photo-avatar-image-generator/predictions  
• Description: Create a new prediction to generate images with custom parameters.

Example Request (JSON):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-image-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ddfc2b08d209f9fa8c1eca692712918bd449f695dabb4a958da31802a9570fe4",
    "input": {
      "prompt": "A photo of a scientist img receiving the Nobel Prize",
      "num_steps": 50,
      "style_name": "Photographic (Default)",
      "input_image": "https://replicate.delivery/pbxt/KFkSv1oX0v3e7GnOrmzULGqCA8222pC6FI2EKcfuCZWxvHN3/newton_0.jpg",
      "num_outputs": 1,
      "guidance_scale": 5,
      "negative_prompt": "nsfw, lowres, bad anatomy, bad hands, text, error, missing fingers, extra digit, fewer digits, cropped, worst quality, low quality, normal quality, jpeg artifacts, signature, watermark, username, blurry",
      "style_strength_ratio": 20
    }
  }'
```

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "ddfc2b08d209f9fa8c1eca692712918bd449f695dabb4a958da31802a9570fe4",
  "status": "starting",
  "created_at": "2025-04-20T10:51:04.253Z"
}
```

---

#### 2. Get Prediction Status
• Method: GET  
• Endpoint: /api/v1/magicapi/ai-photo-avatar-image-generator/predictions/{id}  
• Description: Retrieve the current status and (if completed) the output of a given prediction.

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

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://replicate.delivery/pbxt/WPelbpCPIDTmIiye4CGXbQPBhvegbbUH7fk8DvB4GqsRUC4IB/image_0.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
Below is a list of possible HTTP status codes returned by the API and their meaning:

- 200 OK: Request successful.  
- 201 Created: Resource successfully created (applies to creating predictions).  
- 400 Bad Request: Invalid input parameters or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: Valid API key but insufficient permissions to perform the action.  
- 404 Not Found: Resource (e.g., the specified prediction ID) does not exist.  
- 429 Too Many Requests: Rate limit exceeded—try again later.  
- 500 Internal Server Error: A server-side error has occurred.  
- 503 Service Unavailable: Service is currently unavailable or overloaded.

## Rate Limits
Depending on the plan you’re on, the API may throttle requests if you exceed your usage limits. If you receive a 429 Too Many Requests response, reduce the request rate or upgrade your plan for higher limits.

## Error Handling
When an error occurs, the API returns an error response in JSON format:

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

To handle errors effectively:
- Check the “code” and “message” fields for details on what went wrong.  
- For transient issues (like 503 Service Unavailable), retry with an exponential backoff.  
- For validation errors (400 Bad Request), correct the request parameters before retrying.  

## Implementation Guide

Below are code examples in JavaScript, Python, and cURL for integrating with this API. All examples demonstrate how to handle the asynchronous nature of the prediction process using polling.

### JavaScript Example (Node.js)
```javascript
// JavaScript example with proper polling and timeout

const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-image-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: "ddfc2b08d209f9fa8c1eca692712918bd449f695dabb4a958da31802a9570fe4",
        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) {
    // Check prediction status
    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; // Retrieve the generated images
    }

    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");
}
```

### 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-image-generator"

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

    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=body)

    if response.status_code not in (200, 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
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers={"x-magicapi-key": API_KEY})

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

### cURL Example

Step 1: Create a prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-image-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ddfc2b08d209f9fa8c1eca692712918bd449f695dabb4a958da31802a9570fe4",
    "input": {
      "prompt": "A photo of a scientist img receiving the Nobel Prize",
      "num_steps": 50,
      "style_name": "Photographic (Default)",
      "input_image": "https://replicate.delivery/pbxt/KFkSv1oX0v3e7GnOrmzULGqCA8222pC6FI2EKcfuCZWxvHN3/newton_0.jpg",
      "num_outputs": 1,
      "guidance_scale": 5,
      "negative_prompt": "nsfw, lowres, bad anatomy, bad hands, text, error",
      "style_strength_ratio": 20
    }
  }'

The response will contain a prediction ID. Example:
 {
  "id": "abcd1234",
   "status": "starting"
}

Step 2: Poll the prediction status until it is 'succeeded'
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-photo-avatar-image-generator/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

Continue polling until the "status" field is "succeeded" or "failed".
```

### Performance Optimization
- Reduce the number of output images (num_outputs) if you only need a single result, which lowers costs and speeds up processing.  
- Limit step count (num_steps) for faster generation, if slightly lower image fidelity is acceptable.  
- Keep the polling interval at 1 second to avoid hitting rate limits while still getting prompt status updates.  

## FAQ
1. Can I generate images without any input image?  
   – Yes, but note that many use cases (like stylized portraits) are best served with a base input image for reference.  
2. Are there any restrictions on prompt content?  
   – Certain prompts may be filtered or produce errors if they violate usage guidelines.  
3. How long can a prediction take?  
   – The maximum duration for a single prediction is 600 seconds (10 minutes) before timeout.  

## 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 realistic photos, custom avatars, and artistic portraits in multiple styles. Try it free on API.market.