# FLUX PuLID - Core.Today AI API

> PuLID identity customization on FLUX-dev: generate photorealistic portraits of a specific person from one face photo, with markedly higher fidelity than SDXL-based variants. Tune id_weight and start_step to balance likeness against prompt editability.

- **Provider**: ByteDance
- **Model ID**: bytedance/flux-pulid
- **Category**: Image Generation
- **Credits**: 47 46 credits x num_outputs (1-4 images)
- **Speed**: Medium
- **Quality**: High

## Features
- FLUX-dev backbone for photorealistic, high-fidelity portraits
- Tuning-free ID preservation from a single face photo
- id_weight (0-3) controls how strongly the face is preserved
- start_step trades fidelity (0) against prompt editability (4)
- 1-4 outputs per run, up to 1536px

## Use Cases
- Photorealistic personal branding and portrait imagery
- Identity-consistent characters across marketing campaigns
- High-fidelity avatars where the face must clearly match
- Editorial-style photos placing a person in new scenes
- Premium profile pictures with text or props in scene

## 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 for face generation

### Optional
- **prompt**: string (default: portrait, color, cinematic) - Text prompt to guide image generation
- **negative_prompt**: string (default: bad quality, worst quality, text, signature, watermark, extra limbs, low resolution, partially rendered objects, deformed or partially rendered eyes, deformed, deformed eyeballs, cross-eyed, blurry) - Enter a negative prompt to specify what to avoid in the image
- **width**: integer (default: 896) - Output width in pixels (256-1536)
- **height**: integer (default: 1152) - Output height in pixels (256-1536)
- **num_steps**: integer (default: 20) - Number of denoising steps (1-20)
- **start_step**: integer (default: 0) - Timestep to start inserting ID (0-10). 0 for highest fidelity, 4 for more editability
- **guidance_scale**: number (default: 4) - Guidance scale for text prompt influence (1.0-10.0)
- **id_weight**: number (default: 1) - Weight of the ID image influence (0.0-3.0)
- **seed**: integer - Random seed (leave blank or -1 for random)
- **true_cfg**: number (default: 1) - Set the Classifier-Free Guidance (CFG) scale. 1.0 uses standard CFG, while values >1.0 enable True CFG for more precise control over generation. Higher values increase adherence to the prompt at the cost of image quality.
- **max_sequence_length**: integer (default: 128) - Set the max sequence length for prompt (T5), smaller is faster (128-512)
- **output_format**: string (default: webp) - Format of the output image
  Options: png, jpg, webp
- **output_quality**: integer (default: 80) - Set the quality of the output image for jpg and webp (1-100)
- **num_outputs**: integer (default: 1) - Number of images to generate (1-4). Billed at 60 credits per image

## Examples

### Portrait Holding a Sign
FLUX handles in-scene text while keeping the face — four variations at once
```json
{
  "model": "bytedance/flux-pulid",
  "input": {
    "main_face_image": "https://example.com/woman.png",
    "prompt": "a woman holding sign with glowing green text \"PuLID for FLUX\"",
    "width": 896,
    "height": 1152,
    "start_step": 4,
    "num_outputs": 4
  }
}
```

### Maximum-Fidelity Headshot
start_step 0 and a single output for the closest likeness
```json
{
  "model": "bytedance/flux-pulid",
  "input": {
    "main_face_image": "https://example.com/face.jpg",
    "prompt": "portrait, color, cinematic, studio lighting, detailed face",
    "start_step": 0,
    "id_weight": 1,
    "num_outputs": 1
  }
}
```

## 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
- start_step is the key dial: 0 gives the strongest likeness, 4 lets the prompt reshape the scene more freely
- Raise id_weight above 1 if the face drifts from the reference; the 0-4 start_step range is recommended
- num_outputs is billed per image (60 credits each) — prototype with 1, then batch 4 for finals
- Prefer bytedance/pulid (2 credits/image) for cheap drafts and switch here for final photorealistic quality
- Only use photos of real people with their consent

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