Name: CodeFormer – AI Face Restoration | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-face-restoration-old-photos
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🧑‍🦳 AI Face Restoration API - Restore Old Photos Fast (CodeFormer)

## Overview
This API enables you to restore and enhance faces in old photographs or AI-generated images using advanced CodeFormer technology. It reconstructs facial features while preserving overall image quality, making it ideal for anyone looking to revive old portrait photos, fix AI face artifacts, or upscale lower-resolution snapshots.

## Features
- Robust face restoration for old or low-quality photos  
- Enhanced background processing that uses Real-ESRGAN for sharper details  
- Fine-tunable fidelity to achieve the desired balance between image quality and faithful restoration  
- Optional upsampling for high-quality output images  
- Fast, asynchronous processing allowing you to handle multiple image restoration tasks in parallel  

## Use Cases
1. Archival Photo Restoration for Museums & Heritage Sites  
   - Museums digitizing and restoring large collections of old or damaged photographs.  
2. E-commerce & Fashion  
   - Enhancing face shots and portrait images for better product listings or editorial content.  
3. Social Media Platforms  
   - Offering users the ability to rejuvenate old family photos or fix AI-generated avatars.  
4. Creative Agencies & Photographers  
   - Upscaling portrait shots, retouching old photos, and ensuring consistent image quality.  
5. Historical Documentary Filmmaking  
   - Restoring archival footage or still images to modern standards while preserving fidelity.  

## Visual Examples
Below is an example input image followed by a sample restored output. The image URLs are from example fields in the API schema.

### Example Input
![Example input showing a portrait photo before restoration](https://blog.api.market/wp-content/uploads/2026/04/face-restore-input.jpg)

### Example Output
![Example output demonstrating a clearer, restored portrait photo](https://blog.api.market/wp-content/uploads/2026/04/face-restore-output-1-scaled.png)

These examples showcase how the API can take a lower-quality or older portrait and restore facial features while also enhancing the background.

## Pricing
• 1 API unit = 1 image processed.  
• Using the GET endpoint to check prediction status (/api/v1/magicapi/ai-face-restoration-old-photos/predictions/{id}) is free and does not consume API units.  
• Multiple pricing tiers are available based on your usage volume. If you need higher throughput or extended features, consider upgrading your plan.

## API Documentation

### Base URL
All requests should be sent to:  
```
https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos
```

### Authentication
Include your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```
Make sure to keep your API key secure and never expose it in public repositories.

### Asynchronous Processing
Predictions are processed asynchronously. The typical workflow is:
1. Send a POST request to create a prediction.  
2. The response returns a prediction ID.  
3. Poll the GET endpoint with this prediction ID to check the status.  
4. Continue polling until the status is "succeeded" or "failed."

Guidelines for best results:  
- Poll every 1 second.  
- Implement a maximum timeout of 600 seconds (10 minutes).  
- Stop polling if status becomes "succeeded" or "failed."  

### Endpoints

#### 1) Create a Prediction
• Method: POST  
• Path: /api/v1/magicapi/ai-face-restoration-old-photos/predictions  
• Description: Create a new face restoration prediction request.  

Example cURL request:

```bash
# Example for creating a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg",
      "upscale": 2,
      "face_upsample": true,
      "background_enhance": true,
      "codeformer_fidelity": 0.1
    }
  }'
```

Example response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "cc4956dd26fa5a7185d5660cc9100fab1b8070a1d1654a8bb5eb6d443b020bb2",
  "status": "starting",
  "created_at": "2025-04-23T22:51:10.446Z"
}
```
A successful response (HTTP 201) means the prediction was created. You’ll receive an ID used to check status.

#### 2) Get Prediction Status and Results
• Method: GET  
• Path: /api/v1/magicapi/ai-face-restoration-old-photos/predictions/{id}  
• Description: Check the status of an ongoing or completed prediction, and retrieve the restored image if ready.  

Example cURL request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example response (when succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/04/face-restore-output-1-scaled.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"
}
```

You can then download the output image from the returned URL.

## Status Codes
- 200 OK: Request was successful.  
- 201 Created: A new resource (prediction) was successfully created.  
- 400 Bad Request: Invalid input or malformed request.  
- 401 Unauthorized: Missing or invalid API key in the header.  
- 403 Forbidden: API key is valid but lacks sufficient permissions.  
- 404 Not Found: The requested resource does not exist.  
- 429 Too Many Requests: Rate limit exceeded; slow down or upgrade plan.  
- 500 Internal Server Error: An error on the server side.  
- 503 Service Unavailable: The service is temporarily unavailable; try again later.

## Rate Limits
Requests may be subject to rate limits based on your plan. If you exceed the allowed rate, you will receive a 429 Too Many Requests error. In such cases, implement a retry strategy with exponential backoff.

## Error Handling
When the API returns an error, it is typically in JSON format with an “error” object:

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

Recommended best practices:
- Check the “code” and “message” fields to understand the cause of the error.  
- Correct any malformed requests or missing parameters.  
- For transient errors (429 or 503), implement retry logic with exponential backoff.  

## Implementation Guide

Below are sample code snippets in JavaScript, Python, and Bash to demonstrate how to create a prediction, poll for results, and handle outcomes.

### Example Code (JavaScript)

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos";

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({ 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 between checks

  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();

    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    // Handle failure
    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

### Example Code (Python)

```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"input": input_data}
    )
    
    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"]
    
    # 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 between checks
    
    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()
    
    while (time.time() - start_time) < MAX_TIMEOUT:
        # Check prediction status
        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()
        
        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        # Handle failure
        if 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")
```

### Example Code (cURL)

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg"
    }
  }'

# The response will include a prediction ID, such as:
# {"id": "abcd1234", "status": "starting"}

# Step 2: Poll to check prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photos/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Continue polling until "status" is "succeeded" or "failed".
```

## Performance Optimization
- Optimize image sizes before sending them to the API to reduce processing times.  
- For larger images, use the background enhancement option selectively if you only need face restoration.  
- Use exponential backoff in polling to avoid high request volume if needed.  

## FAQ
1. **How long does it take to restore a face?**  
   Typically within a few seconds, but can take longer for large images or complex backgrounds.  
2. **Do I get billed for polling GET requests?**  
   No. Checking prediction status is free and does not consume any API units.  
3. **What’s the maximum image size?**  
   Images up to a few megabytes typically work well. Larger images may take more time to process.  
4. **Is there support for batch processing?**  
   You can submit multiple POST requests in parallel, but each image restoration runs as an individual prediction.  

## 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.

Restore faces in old or AI-generated photos using advanced CodeFormer technology. From $0.05/call. Try it free on API.market.