Name: PuLID – Generate Custom Image IDs | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-lightning-id-image-customization
Availability: InStock
Author: API Market

Shashank Agarwal

# ⚡ Ultra-Fast Image ID Customization API (PuLID)

## Overview
PuLID (Pure and Lightning ID Customization) is an ultra-fast image-based AI model designed to instantly create high-quality, personalized image IDs. This is particularly useful for rapid onboarding, visual branding, user profile images, and any situation requiring a quick turnaround for identity-based imagery. By leveraging contrastive alignment, PuLID ensures your images maintain critical identity features while still allowing for stylistic customization.

## Features
- Lightning-fast image processing for ID customization
- High-fidelity personalization through adjustable “identity scale”
- Option to combine (mix) multiple faces in a single output image
- Fine-tuned generation controls:
  - Adjustable CFG scale (speed vs. fidelity)
  - Different generation modes (from high fidelity to more stylized outputs)
  - Flexible output format (webp, jpg, png) and customizable quality
- Works asynchronously, allowing you to retrieve results once processing completes

## Use Cases
1. Rapid Onboarding: Automatically generate professional profile photos from a single headshot.  
2. Secure ID Creation: Create unique, visually consistent IDs for staff badges or visitor passes.  
3. Visual Branding: Produce on-brand ID images with specific styles or backgrounds for event badges.  
4. Multi-Face Compositions: Merge multiple team member photos into a single ID for collaboration announcements.  
5. Artistic Exploration: Experiment with impressionist, cinematic, or other artistic styles while preserving recognizable identity features.

## Visual Examples

### Sample Input Image
Below is an example of a face image used as the main input (highlighting what the user might upload):
![Sample main face input image (one of the images used as input)](https://replicate.delivery/pbxt/Kr6iendsvYS0F3MLmwRZ8q07XIMEJdemnQI3Cmq9nNrauJbq/zcy.webp)

Notice the prompt in the example points to generating a portrait with vibrant colors, soft light, and a detailed face. 

### Sample Output Images
After processing, the model can return multiple output images in an array. Here is an example set of outputs—each image is personalized based on the prompt and input settings:
![Sample output image 1](https://replicate.delivery/pbxt/nDciJ2jxtSYcCVxGxprSzvycVWR6fIHyJYQFeyDDwDSqrswSA/output_image_0.webp)  
![Sample output image 2](https://replicate.delivery/pbxt/f8UCxdcfXNrYokQMYOUFPzBnVsiRY6Ok1Eotaorg14ZrrswSA/output_image_1.webp)  
![Sample output image 3](https://replicate.delivery/pbxt/k7YRRLjBos7EBhiOz8OD7kGrgFwdbemQTbvsQAOmizo1VWYJA/output_image_2.webp)  
![Sample output image 4](https://replicate.delivery/pbxt/Tif4TmIemNjDiksQWaGTUzG4momOuqeGcEqAMhQHxUdYXZhlA/output_image_3.webp)

These demonstrate how PuLID can produce multiple variations from the same input parameters.

## Pricing
• 1 API unit equals 1 image processed  
• Checking prediction status (GET /api/v1/magicapi/ai-lightning-id-image-customization/predictions/{id}) is free and does not count toward API usage  
• Tiered pricing based on total monthly image processing volume  

Contact API.market for the latest pricing details and volume discounts.

## API Documentation

### Base URL
All API requests should be sent to:
```
https://prod.api.market/api/v1/magicapi/ai-lightning-id-image-customization
```

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

### Asynchronous Processing
This API uses asynchronous processing. The workflow is:

1. POST a prediction request to create a new job.  
2. Receive a unique prediction ID in the response.  
3. Poll the GET endpoint to check the prediction’s status.  
4. Continue polling until the status is “succeeded” or “failed.”  

Typical steps:
- Wait 1 second between each status check.  
- Implement a maximum timeout of 600 seconds (10 minutes).  
- On success, consume the output from the response.  
- On failure or timeout, handle errors accordingly.

### Endpoints

#### Create a Prediction
• Endpoint: POST /api/v1/magicapi/ai-lightning-id-image-customization/predictions  
• Description: Creates a prediction job with the specified input parameters.

Example Request (JSON):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-lightning-id-image-customization/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "43d309c37ab4e62361e5e29b8e9e867fb2dcbcec77ae91206a8d95ac5dd451a0",
    "input": {
      "main_face_image": "https://example.com/image.jpg",
      "prompt": "portrait, impressionist painting, loose brushwork, vibrant color",
      "cfg_scale": 1.2,
      "num_steps": 4,
      "image_width": 768,
      "image_height": 1024,
      "num_samples": 4,
      "output_format": "webp",
      "identity_scale": 0.8,
      "mix_identities": false,
      "output_quality": 80,
      "generation_mode": "fidelity",
      "negative_prompt": "flaws in the eyes, flaws in the face, low quality"
    }
  }'
```

Possible 201 Response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "43d309c37ab4e62361e5e29b8e9e867fb2dcbcec77ae91206a8d95ac5dd451a0",
  "status": "starting",
  "created_at": "2025-04-20T19:10:51.993Z"
}
```

#### Get Prediction Status
• Endpoint: GET /api/v1/magicapi/ai-lightning-id-image-customization/predictions/{id}  
• Description: Retrieves the current status and (if complete) the output of the prediction.

Example Request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-lightning-id-image-customization/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example 200 Response (when succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://somewhere.com/output_image_0.webp",
    "https://somewhere.com/output_image_1.webp",
    "https://somewhere.com/output_image_2.webp",
    "https://somewhere.com/output_image_3.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 successful, typically for GET predictions operations  
- 201 Created: Resource (prediction) successfully created  
- 400 Bad Request: Invalid input parameters or malformed request  
- 401 Unauthorized: Missing or invalid API key  
- 403 Forbidden: Valid API key but insufficient permissions  
- 404 Not Found: The requested resource (e.g., prediction ID) was not found  
- 429 Too Many Requests: Rate limit exceeded; consider a delay or request a higher tier  
- 500 Internal Server Error: An unexpected error occurred on the server  
- 503 Service Unavailable: The service is temporarily overloaded or down for maintenance  

## Rate Limits
PuLID may enforce rate limits to prevent abuse and ensure service availability. If you reach the limit, you will receive a 429 Too Many Requests error. In that case:
- Slow down request frequency  
- Contact API.market to discuss higher rate limits if your usage is consistently high  

## Error Handling
When requests fail, the API will return an error response in JSON. Example:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'main_face_image' is required",
    "status": 400
  }
}
```
Recommended steps:
- Check the “message” field for details on what went wrong.  
- Correct the request and retry.  
- For transient issues (500, 503), implement a backoff strategy before retrying.  
- For 429 Too Many Requests, slow down or contact support for higher limits.

## Implementation Guide

### Example Code

Below are sample implementations demonstrating how to:
1. Authenticate using an API key.  
2. Create a prediction (POST).  
3. Poll for status (GET) until completion or failure.  
4. Handle errors and timeouts (max 10 minutes).  

#### JavaScript (Node.js) Polling Example
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-lightning-id-image-customization";

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: "43d309c37ab4e62361e5e29b8e9e867fb2dcbcec77ae91206a8d95ac5dd451a0",
        input: inputData
      })
    });

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

    const prediction = await response.json();
    const predictionId = prediction.id;
    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
  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");
}
```

#### Python Polling Example
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-lightning-id-image-customization"

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": "43d309c37ab4e62361e5e29b8e9e867fb2dcbcec77ae91206a8d95ac5dd451a0",
        "input": input_data
    }

    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=payload)
    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"]
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 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"]

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

        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-lightning-id-image-customization/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "43d309c37ab4e62361e5e29b8e9e867fb2dcbcec77ae91206a8d95ac5dd451a0",
    "input": {
      "main_face_image": "https://example.com/image.jpg",
      "prompt": "portrait, impressionist painting, vibrant color"
    }
  }'

Example response:
{"id":"abcd1234","status":"starting"}

Step 2: Check prediction status by ID (repeat until "succeeded" or "failed")
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-lightning-id-image-customization/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Use the lowest required image resolution to speed up processing.  
- Keep CFG scale to 1.0 or slightly above if you want faster generation.  
- Limit the number of samples if you only need one final output.  
- Cache successful results if you repeatedly request identical parameters.

## FAQ
1. **Where are my generated images stored?**  
   They are provided as URLs in the “output” array. You can download them and store them locally if needed.  

2. **Can I generate multiple styles from the same input?**  
   Yes, use the “num_samples” parameter to specify how many variations to produce in one request.  

3. **What if I need higher resolution images?**  
   You can increase “image_width” and “image_height” up to 2024 for more detailed outputs, though it may take slightly longer.  

4. **Why am I receiving a 429 Too Many Requests error?**  
   You’ve reached your rate limit. Either slow down or contact API.market for a higher usage tier.  

5. **What is the recommended prompt style?**  
   Clear, concise descriptions focusing on the desired outcome. Combine descriptors (e.g., “cinematic, vibrant color, soft lighting”) for best results.

## 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 high-fidelity, personalized image IDs from photos in seconds. Create unique visuals and custom avatars for apps or bran Try it free on API.market.

PuLID – Generate Custom Image IDs | $0.05/call | API.market