# PuLID - Core.Today AI API

> ByteDance PuLID: tuning-free identity customization on SDXL. Give it one face photo and a prompt to generate portraits in any scene or style — no training, 4-step fast sampling, and even two-identity blending. Extremely cost-effective at 2 credits per image.

- **Provider**: ByteDance
- **Model ID**: bytedance/pulid
- **Category**: Image Generation
- **Credits**: 6 1 credit x num_samples (default 4 images = 6 credits)
- **Speed**: Fast
- **Quality**: High

## Features
- Tuning-free identity preservation from a single face photo
- Lightning-fast 4-step sampling on SDXL
- mix_identities: blend two different faces into one person
- fidelity vs 'extremely style' generation modes
- Up to 8 images per run at just 2 credits each

## Use Cases
- Bulk avatar and profile picture generation on a budget
- Stylized portraits — paintings, cinematic, illustration
- Rapid identity-consistent concept exploration
- Blending two faces for fictional character design
- Batch persona imagery for games and communities

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **main_face_image**: string - ID image (main face photo)

### Optional
- **prompt**: string (default: portrait,color,cinematic,in garden,soft light,detailed face) - Text prompt describing the scene and style
- **auxiliary_face_image1**: string - Additional ID image — the second face when mix_identities is on
- **auxiliary_face_image2**: string - Additional ID image (auxiliary)
- **auxiliary_face_image3**: string - Additional ID image (auxiliary)
- **negative_prompt**: string (default: flaws in the eyes, flaws in the face, flaws, lowres, non-HDRi, low quality, worst quality,artifacts noise, text, watermark, glitch, deformed, mutated, ugly, disfigured, hands, low resolution, partially rendered objects,  deformed or partially rendered eyes, deformed, deformed eyeballs, cross-eyed,blurry) - Negative Prompt
- **cfg_scale**: number (default: 1.2) - CFG, recommend value range [1, 1.5], 1 will be faster
- **num_steps**: integer (default: 4) - Sampling steps (1-100). 4 is the fast lightning default
- **image_height**: integer (default: 1024) - Output height in pixels (512-2024)
- **image_width**: integer (default: 768) - Output width in pixels (512-2024)
- **identity_scale**: number (default: 0.8) - ID scale (0-5). Higher preserves the face more strongly
- **generation_mode**: string (default: fidelity) - 'fidelity' prioritizes likeness; 'extremely style' prioritizes stylization
  Options: fidelity, extremely style
- **mix_identities**: boolean (default: false) - Turn on to mix two ID images into one identity (use auxiliary_face_image1)
- **seed**: integer - Random seed. Leave blank to randomize
- **num_samples**: integer (default: 4) - Number of images to generate (1-8). Billed at 2 credits per image
- **output_format**: string (default: webp) - Format of the output images
  Options: webp, jpg, png
- **output_quality**: integer (default: 80) - Quality of the output images, from 0 to 100. 100 is best quality, 0 is lowest quality.

## Examples

### Impressionist Portrait Set
Four impressionist-painting portraits of the same person from one photo
```json
{
  "model": "bytedance/pulid",
  "input": {
    "main_face_image": "https://example.com/face.webp",
    "prompt": "portrait, impressionist painting, loose brushwork, vibrant color, light and shadow play",
    "num_samples": 4,
    "identity_scale": 0.8,
    "generation_mode": "fidelity"
  }
}
```

### Two-Face Identity Mix
Blend two face photos into a single new character
```json
{
  "model": "bytedance/pulid",
  "input": {
    "main_face_image": "https://example.com/face-a.jpg",
    "auxiliary_face_image1": "https://example.com/face-b.jpg",
    "mix_identities": true,
    "prompt": "portrait, color, cinematic, soft light, detailed face",
    "num_samples": 2
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- num_samples defaults to 4 (8 credits) — set it to 1 for a 2-credit test run
- Raise identity_scale toward 1.2-2 if the face drifts; lower it if outputs look stiff
- Use 'extremely style' mode for heavy stylization like paintings; 'fidelity' for realistic likeness
- For mix_identities, provide the second face via auxiliary_face_image1 and keep both photos front-facing
- Only use photos of real people with their consent

## Documentation
https://replicate.com/bytedance/pulid