Old photographs fade, scratch, and lose detail over time, but the faces in them still carry irreplaceable memories. A face restoration API uses deep learning to reconstruct facial details that have been lost to age, compression, or low resolution — sharpening eyes, smoothing skin artifacts, and recovering natural textures that make a face look lifelike again. In this tutorial, you will learn how to integrate the Face Restoration API into your application using an asynchronous three-step workflow, with complete code examples in cURL, Python, and JavaScript.
Why Use a Face Restoration API?
Building a face restoration model from scratch requires training on millions of degraded and high-quality face pairs, managing GPU infrastructure, and constantly tuning for edge cases like extreme blur or heavy noise. A hosted API abstracts all of that complexity. Here is what you get out of the box:
- AI-powered detail recovery — The model reconstructs fine facial features like eyes, eyebrows, lips, and skin texture from heavily degraded inputs, producing results that look natural rather than artificially sharpened.
- No ML expertise required — You do not need to understand GANs, super-resolution architectures, or training pipelines. You send an image and get an enhanced version back.
- Asynchronous processing — The API uses a submit-poll-retrieve pattern that handles heavy processing gracefully. Your application stays responsive while the model works on the image in the background.
- Flexible input options — Upload an image file directly or pass a public URL. The API accepts common formats like JPEG, PNG, and WebP.
Getting Started with the Face Restoration API
Unlike synchronous APIs that return a result immediately, the Face Restoration API uses an asynchronous three-step workflow. This design makes sense for face restoration because the underlying model needs several seconds to analyze and reconstruct facial details at high quality. Here is how the workflow works:
- Submit — Send a POST request to
/submitwith your image (as a file upload or a URL). The API returns ajobIdimmediately. - Poll status — Send a GET request to
/status/{jobId}to check whether the job has finished processing. Repeat every few seconds until the status indicates completion. - Retrieve result — Once the job is complete, send a GET request to
/result/{jobId}to download the restored image.
This pattern keeps your application responsive. You can show a progress indicator to the user while the API works, or process multiple images concurrently by submitting several jobs and polling them in parallel.
cURL
Here are all three steps as standalone cURL commands. Run them sequentially, replacing the job ID from step one into steps two and three.
# Step 1: Submit the image for restoration
curl -X POST "https://face-restoration.p.rapidapi.com/submit" \
-H "x-rapidapi-key: YOUR_API_KEY" \
-H "x-rapidapi-host: face-restoration.p.rapidapi.com" \
-F "image=@old_photo.jpg"
# Response: { "jobId": "abc123" }
# Step 2: Poll the job status
curl -X GET "https://face-restoration.p.rapidapi.com/status/abc123" \
-H "x-rapidapi-key: YOUR_API_KEY" \
-H "x-rapidapi-host: face-restoration.p.rapidapi.com"
# Response: { "status": "completed" } (or "processing" — keep polling)
# Step 3: Retrieve the restored image
curl -X GET "https://face-restoration.p.rapidapi.com/result/abc123" \
-H "x-rapidapi-key: YOUR_API_KEY" \
-H "x-rapidapi-host: face-restoration.p.rapidapi.com" \
--output restored_photo.jpg
# You can also submit a URL instead of a file:
curl -X POST "https://face-restoration.p.rapidapi.com/submit" \
-H "x-rapidapi-key: YOUR_API_KEY" \
-H "x-rapidapi-host: face-restoration.p.rapidapi.com" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "url=https://example.com/old_photo.jpg"Python
This Python script handles the full async workflow with automatic polling. It submits the image, waits for the job to complete, and downloads the restored result.
import requests
import time
HOST = "face-restoration.p.rapidapi.com"
HEADERS = {
"x-rapidapi-host": HOST,
"x-rapidapi-key": "YOUR_API_KEY",
}
# Step 1: Submit the image
with open("old_photo.jpg", "rb") as f:
submit_resp = requests.post(
f"https://{HOST}/submit",
headers=HEADERS,
files={"image": f},
)
job_id = submit_resp.json()["jobId"]
print(f"Job submitted: {job_id}")
# Step 2: Poll until the job is complete
while True:
status_resp = requests.get(
f"https://{HOST}/status/{job_id}",
headers=HEADERS,
)
status = status_resp.json()["status"]
print(f"Status: {status}")
if status == "completed":
break
elif status == "failed":
print("Job failed:", status_resp.json())
exit(1)
time.sleep(3)
# Step 3: Download the restored image
result_resp = requests.get(
f"https://{HOST}/result/{job_id}",
headers=HEADERS,
)
with open("restored_photo.jpg", "wb") as f:
f.write(result_resp.content)
print("Restored image saved as restored_photo.jpg")JavaScript (fetch)
The same three-step workflow in JavaScript, suitable for Node.js or any environment that supports the Fetch API.
import fs from "fs";
const HOST = "face-restoration.p.rapidapi.com";
const HEADERS = {
"x-rapidapi-host": HOST,
"x-rapidapi-key": "YOUR_API_KEY",
};
// Step 1: Submit the image
const form = new FormData();
form.append("image", fs.createReadStream("old_photo.jpg"));
const submitResp = await fetch(`https://${HOST}/submit`, {
method: "POST",
headers: HEADERS,
body: form,
});
const { jobId } = await submitResp.json();
console.log("Job submitted:", jobId);
// Step 2: Poll until complete
let status = "processing";
while (status !== "completed") {
const statusResp = await fetch(
`https://${HOST}/status/${jobId}`,
{ headers: HEADERS }
);
const statusData = await statusResp.json();
status = statusData.status;
console.log("Status:", status);
if (status === "failed") {
console.error("Job failed:", statusData);
process.exit(1);
}
if (status !== "completed") {
await new Promise((resolve) => setTimeout(resolve, 3000));
}
}
// Step 3: Download the restored image
const resultResp = await fetch(
`https://${HOST}/result/${jobId}`,
{ headers: HEADERS }
);
const buffer = Buffer.from(await resultResp.arrayBuffer());
fs.writeFileSync("restored_photo.jpg", buffer);
console.log("Restored image saved as restored_photo.jpg");See the Results
The image below shows the Face Restoration API in action. A degraded, low-quality face has been reconstructed with sharper details, clearer eyes, and smoother skin textures — all without manual retouching.
The model is particularly effective on portraits where the face occupies a significant portion of the frame. It recovers details like individual eyelashes, skin pores, and lip texture that were completely lost in the degraded input. The result looks natural rather than over-sharpened, which is a common problem with simpler upscaling approaches.
Real-World Use Cases
Face restoration is not just a technical demo. It solves real problems for real users across multiple industries. Here are four scenarios where the API delivers immediate value.
Old Family Photos
This is the most emotionally resonant use case. Millions of family photographs from the pre-digital era are fading in shoeboxes and albums. When these photos are scanned, the resulting digital files often suffer from low resolution, scratches, and faded tones. The Face Restoration API can recover facial details that the scanner could not capture, turning a blurry ancestor portrait into a sharp, lifelike image that families can treasure. Consumer apps can build a "restore your family photos" feature that drives deep engagement and word-of-mouth sharing, especially around holidays and family reunions.
Profile Picture Enhancement
Not every profile picture starts as a high-quality studio portrait. Many users crop their face from a group photo, use an old webcam shot, or grab a frame from a video call. The result is a small, blurry, or compressed face that looks unprofessional on LinkedIn, dating apps, or internal company directories. Running these images through the Face Restoration API produces a noticeably sharper result that looks polished without requiring the user to take a new photo. Combine this with face detection to automatically crop and enhance the face region before setting it as a profile picture.
Historical Archive Digitization
Museums, libraries, and government archives hold massive collections of historical photographs where faces are often the most important element. A wartime portrait, a civil rights march, or an immigration record gains immense value when the faces are clear enough to identify or connect with living descendants. The API can process entire collections programmatically, restoring thousands of faces in hours rather than weeks of manual retouching. Pair this with anime-style transformation to offer creative alternative views of historical imagery alongside the restored originals.
Real Estate and ID Photos
Real estate listings sometimes include interior shots where people appear in reflections or through windows, and those faces are typically tiny and blurry. Identity verification workflows may receive low-quality scans of passports or driver's licenses where the photo is barely legible. In both cases, the Face Restoration API can enhance the face region enough to improve usability — making a listing look more professional or helping an agent verify a document without requesting a rescan.
Tips and Best Practices
Start with the Best Available Input
The restoration model can recover a remarkable amount of detail, but it is not magic. If you have access to the original print, scan it at 300 DPI or higher before sending it to the API. A higher-quality input gives the model more information to work with and produces a more natural result. Avoid sending heavily JPEG-compressed thumbnails when a larger version of the same photo exists.
Handle the Async Workflow Gracefully
Since the API uses a submit-poll-retrieve pattern, your application needs to handle the waiting period gracefully. Show a progress indicator or loading animation to the user. Poll every 3 to 5 seconds rather than hammering the status endpoint continuously. If a job takes longer than expected, set a reasonable timeout (60 seconds is a good starting point) and show an error message rather than leaving the user waiting indefinitely.
Process Multiple Images Concurrently
The async pattern makes it easy to parallelize. Submit all your images at once, collect the job IDs, and then poll them in a single loop or use Promise.all in JavaScript. This is dramatically faster than processing images one at a time, especially for batch workflows like archive digitization where you may have hundreds of photos to restore.
Combine with Other Enhancement Steps
Face restoration works best as part of a pipeline. Consider running images through a denoising or scratch removal step before sending them to the Face Restoration API, and follow up with color correction or AI colorization if the original was black and white. Each step builds on the previous one, and the cumulative result is far better than any single step alone.
Respect Privacy and Get Consent
Face restoration can make previously unrecognizable individuals identifiable. This is powerful and comes with responsibility. If you are processing photos of people other than the uploader, ensure you have appropriate consent. For historical archives, follow your institution's policies on digitizing and publishing identifiable faces. Clearly communicate to users how their uploaded photos are processed and stored, and comply with privacy regulations like GDPR or CCPA.
Old photographs deserve better than a dusty shoebox. The Face Restoration API gives you the tools to bring faded faces back to life with a simple three-step workflow. Whether you are building a consumer photo app, digitizing a historical collection, or adding an enhancement feature to your existing platform, the async submit-poll-retrieve pattern keeps your application responsive while the AI handles the heavy lifting. Grab your API key and start restoring.
