Name: GFPGAN – Restore & Enhance Faces | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-face-restoration-old-photo-enhancer
Availability: InStock
Rating: 5.00 (2 reviews)
Author: API Market

Shashank Agarwal

# 🧑‍🦳 AI Face Restoration & Old Photo Enhancer API (GFPGAN)

## Overview
This API enables you to restore and enhance faces in old or AI-generated photos using a powerful face-restoration algorithm. It's especially useful for repairing vintage photographs, improving AI-generated portraits, and upscaling or improving clarity in images containing human faces. The underlying model (GFPGAN) applies advanced facial restoration techniques to produce high-quality outputs.

Below is an example of input and output images to help illustrate what this API can do:

**Example Input (Old or Low-Quality Photo)**
![An example old or low-quality photo with a human face](https://replicate.delivery/mgxm/59d9390c-b415-47e0-a907-f81b0d9920f1/187400315-87a90ac9-d231-45d6-b377-38702bd1838f.jpg)

**Example Output (Restored and Enhanced Photo)**
![Restored version of the face with improved clarity and details](https://replicate.delivery/mgxm/85f53415-0dc7-4703-891f-1e6f912119ad/output.png)

## Features
- Accurate face restoration for old, blurred, or AI-generated images.
- Enhanced image clarity and vibrant detailing.
- Configurable rescaling (up to 2x or more) to upscale the final output.
- Flexible version selection for different levels of detail (v1.2, v1.3, v1.4, or RestoreFormer).
- Asynchronous prediction processing to handle large or complex images efficiently.

## Use Cases
1. Revitalizing family portraits and historic photos.  
2. Improving clarity of AI-generated faces for artistic or design purposes.  
3. Upscaling small, low-resolution facial images for high-quality digital displays.  
4. Repairing old photos where faces are faded or damaged.  
5. Restoring images for genealogy research or archiving projects.

## Examples
Here are direct example references you can use to see the before/after transformations:

- Input image (faded, low-quality photo)  
  ![Original vintage photo with fading and low resolution](https://replicate.delivery/mgxm/59d9390c-b415-47e0-a907-f81b0d9920f1/187400315-87a90ac9-d231-45d6-b377-38702bd1838f.jpg)

- Output image (restored with enhanced clarity and detail)  
  ![Photo after restoration with sharper facial details and richer tones](https://replicate.delivery/mgxm/85f53415-0dc7-4703-891f-1e6f912119ad/output.png)

These samples demonstrate how effectively the API can re-introduce missing details and refine overall facial structure.

## Pricing
- 1 API unit = 1 image processed.
- GET requests to check prediction status (GET /api/v1/magicapi/ai-face-restoration-old-photo-enhancer/predictions/{id}) are FREE and do not count toward usage.
- Various pricing tiers exist based on usage volume. Contact us or visit API.market to learn more about available plans.

## API Documentation

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

### Authentication
All requests require the following header for authentication:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```
Replace YOUR_API_MARKET_KEY with your actual API key obtained from API.market.

### Asynchronous Processing
This API uses asynchronous processing for image predictions:
1. Send a POST request to create a prediction.
2. Receive a prediction ID in the response.
3. Poll the GET endpoint with that ID to check the status.
4. Continue polling until the status is "succeeded" or "failed."

The time needed for a prediction depends on complexity and server load. Ensure your client application:
- Polls every 1 second for status changes.
- Has a maximum timeout of 600 seconds (10 minutes).
- Stops polling when the status is "succeeded" (use the output URL) or "failed" (handle errors accordingly).

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• Endpoint: /api/v1/magicapi/ai-face-restoration-old-photo-enhancer/predictions  
• Description: Submits the image and processing parameters to initiate face restoration.

Request Body (JSON):
```json
{
  "version": "0fbacf7afc6c144e5be9767cff80f25aff23e52b0708f17e20f9879b2f21516c",
  "input": {
    "img": "https://replicate.delivery/mgxm/59d9390c-b415-47e0-a907-f81b0d9920f1/187400315-87a90ac9-d231-45d6-b377-38702bd1838f.jpg",
    "scale": 2,
    "version": "v1.4"
  }
}
```

Example curl command:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photo-enhancer/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "0fbacf7afc6c144e5be9767cff80f25aff23e52b0708f17e20f9879b2f21516c",
    "input": {
      "img": "https://replicate.delivery/mgxm/59d9390c-b415-47e0-a907-f81b0d9920f1/187400315-87a90ac9-d231-45d6-b377-38702bd1838f.jpg",
      "scale": 2,
      "version": "v1.4"
    }
  }'
```

Typical Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "0fbacf7afc6c144e5be9767cff80f25aff23e52b0708f17e20f9879b2f21516c",
  "status": "starting",
  "created_at": "2025-04-21T10:44:14.372Z"
}
```

#### 2. Get Prediction Status and Results
• Method: GET  
• Endpoint: /api/v1/magicapi/ai-face-restoration-old-photo-enhancer/predictions/{id}  
• Description: Retrieve the current status and, if complete, the restored output image URL.

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

Typical Response (200 OK, when succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/mgxm/85f53415-0dc7-4703-891f-1e6f912119ad/output.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"
}
```

## Status Codes
- 200 OK: Request was successful.
- 201 Created: The prediction request was accepted, and an ID has been generated.
- 400 Bad Request: Possibly malformed request or invalid input data.
- 401 Unauthorized: The provided API key is missing or invalid.
- 403 Forbidden: The API key is valid but does not have the required permissions.
- 404 Not Found: The specified resource (prediction ID) does not exist.
- 429 Too Many Requests: You have exceeded the allowed rate limit or usage quotas.
- 500 Internal Server Error: An unexpected server-side error occurred.
- 503 Service Unavailable: Temporary server overload or maintenance.

## Rate Limits
Depending on your plan, rate limits may apply to ensure fair usage. If you reach the rate limit, you will receive a 429 Too Many Requests response. In this scenario, throttling or exponential backoff is recommended before retrying.

## Error Handling
Error responses typically follow this format:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'img' is required",
    "status": 400
  }
}
```
- "code" briefly indicates the type of error.  
- "message" describes the error.  
- "status" is the HTTP status code.

Common errors:
- Missing required fields: Ensure "img" is included in the request.
- Invalid URL format: Provide a valid, publicly accessible image URL.
- Model version not recognized: Make sure "version" is one of the valid enumerations (v1.2, v1.3, v1.4, RestoreFormer).

Recommended retry strategy for transient errors:
1. If the error appears to be a server-side or rate-limit issue, implement exponential backoff (e.g., wait 1 second, then 2, then 4, up to a maximum interval).
2. If the error persists, contact support.

## Implementation Guide

### Example Code

#### JavaScript (Node.js) Example
```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-photo-enhancer";

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: "0fbacf7afc6c144e5be9767cff80f25aff23e52b0708f17e20f9879b2f21516c",
        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

  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"}`);
    }

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

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

#### Python Example
```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-photo-enhancer"

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={
            "version": "0fbacf7afc6c144e5be9767cff80f25aff23e52b0708f17e20f9879b2f21516c",
            "input": input_data
        }
    )

    if response.status_code not in [200, 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  # seconds (10 minutes)
    POLL_INTERVAL = 1  # seconds
    start_time = time.time()

    headers = {
        "x-magicapi-key": API_KEY
    }

    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":
            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")
```

#### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photo-enhancer/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "0fbacf7afc6c144e5be9767cff80f25aff23e52b0708f17e20f9879b2f21516c",
    "input": {
      "img": "https://replicate.delivery/mgxm/59d9390c-b415-47e0-a907-f81b0d9920f1/187400315-87a90ac9-d231-45d6-b377-38702bd1838f.jpg",
      "scale": 2,
      "version": "v1.4"
    }
  }'

# Response will contain a prediction ID like:
# {"id": "ufawqhfynnddngldkgtslldrkq", "status": "starting"}

# Step 2: Check prediction status (replace the ID below with your actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-face-restoration-old-photo-enhancer/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

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

### Performance Optimization
- Optimize the size of your input images (avoid excessively large images if unnecessary).
- Choose the most suitable version (e.g., v1.4 for higher detail, v1.3 for better identity preservation).
- Cache results if you plan to process the same image multiple times.

## FAQ
1. **Why is my photo taking a long time to process?**  
   It may be higher resolution, or the system may be under heavy load. Consider reducing scale or waiting for the process to complete.
2. **Can I restore multiple faces in one image?**  
   Yes, the model attempts to restore all recognizable faces.
3. **What if the restoration doesn’t meet my expectations?**  
   Try different versions (e.g., v1.3 or RestoreFormer) or adjust the scale parameter.
4. **Is the output publicly accessible for everyone?**  
   The returned output URL is typically a public link. Use it as needed, but handle it securely if the content is sensitive.
5. **Do GET requests cost me anything?**  
   No. Checking the prediction status by GET requests is free and does not consume your API credits.

## 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 and enhance faces in old or AI-generated photos. Upscale images up to 2x. From $0.05/call. Try it free on API.market.