# CodeFormer - Core.Today AI API

> Robust face restoration for old photos and AI-generated faces (54M+ runs). Its signature fidelity dial balances restoration quality against staying true to the original face, with Real-ESRGAN background enhancement built in.

- **Provider**: CodeFormer
- **Model ID**: sczhou/codeformer
- **Category**: Image Generation
- **Credits**: 8 per image
- **Speed**: Fast
- **Quality**: High

## Features
- Quality vs fidelity balance dial (codeformer_fidelity)
- Robust on heavily degraded faces
- Built-in Real-ESRGAN background enhancement
- Face upsampling for high-resolution output
- Adjustable final upscale factor

## Use Cases
- Severely degraded photo restoration
- AI face artifact correction
- Historical archive restoration
- Video frame face cleanup
- Identity-preserving enhancement

## 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
- **image**: string - Input image with faces to restore

### Optional
- **codeformer_fidelity**: number (default: 0.5) - Balance between quality (lower) and fidelity to the original face (higher), 0-1
- **background_enhance**: boolean (default: true) - Enhance the background with Real-ESRGAN
- **face_upsample**: boolean (default: true) - Upsample restored faces for high-resolution output
- **upscale**: integer (default: 2) - Final upsampling scale of the image

## Examples

### Degraded Photo Restoration
Restore a heavily degraded photo, balancing quality and identity
```json
{
  "model": "sczhou/codeformer",
  "input": {
    "image": "https://example.com/degraded-photo.jpg",
    "codeformer_fidelity": 0.7,
    "upscale": 2,
    "background_enhance": true,
    "face_upsample": true
  }
}
```

## 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
- Raise codeformer_fidelity (0.7-0.9) to keep the person recognizable; lower it (0.3) for maximum cleanup
- Keep background_enhance on for complete photo restoration in one pass
- More robust than GFPGAN on severely degraded inputs; GFPGAN can look more natural on mild cases
- upscale 2 is usually enough — chain Real-ESRGAN if you need larger output

## Documentation
https://replicate.com/sczhou/codeformer