Face Restoration and Enhancement with GFPGAN
Restore and enhance faces in old, blurry, or low-resolution photos. GFPGAN reconstructs facial detail and can upscale the image at the same time. The whole flow is one hosted call on a single gfpgan client.
Uses: tencentarc/gfpgan, a cheap, hosted Replicate model in the Socaity catalog. It runs TencentARC's GFPGAN face-restoration network to repair facial detail and optionally upscale the result.
face2face, an open-source Socaity library you self-host or deploy via APIPod. See the face2face GitHub repo. This page covers the hosted GFPGAN restoration model, the closest hosted face feature available today. GFPGAN is a catalog model. Install the SDK once, then install the model to make its client importable:
pip install socaity
socaity install tencentarc/gfpgan Import gfpgan from its deep catalog path under socaity.sdk.replicate.tencentarc and instantiate it with your API key. The client holds the service binding and is reusable across calls.
import os
from socaity.sdk.replicate.tencentarc import gfpgan
# gfpgan(api_key: str | None = None). If you leave api_key=None,
# the client falls back to the SOCAITY_API_KEY environment variable.
restore = gfpgan(api_key=os.getenv("SOCAITY_API_KEY")) Wrap your local file in ImageFile so the SDK uploads it correctly. ImageFile().from_file("face.png") reads the file from disk and hands it to the img parameter.
from socaity import ImageFile
# Wrap a local file so the SDK uploads it correctly.
face = ImageFile().from_file("face.png") # replace with your own face photo Call the client with img and an optional scale factor. The call returns a job; .get_result() blocks until the worker finishes and returns a single output file. Call .save() to write it to disk.
from socaity import ImageFile
# img is required; scale upscales the output (2 doubles the resolution).
out = restore(
img=ImageFile().from_file("face.png"), # replace with your own face photo
scale=2,
).get_result() # single output file, no [0] needed
out.save("restored.png")
print("Saved restored.png")get_result() returns the file directly. There is no list to index into, so you do not need [0]. gfpgan are not yet exposed in the JS SDK. Use the Python SDK for full model access. See the JavaScript SDK reference for the current feature set. The JavaScript SDK cannot run models yet, so use the Python SDK above to restore faces.
Key parameters on the predictions endpoint. Defaults apply when omitted.
| Parameter | Type | Default | Description |
|---|---|---|---|
img | ImageFile | str | required | Face image to restore. Wrap a local path with ImageFile().from_file(...). |
scale | number | 2 | Upscale factor applied to the output. Higher values produce a larger image. |
version | str | model default | GFPGAN model version selector. |
- GFPGAN targets faces. For best results, feed it a photo where the face is clearly visible.
- Use
scaleto upscale while you restore. A value of 2 doubles the output resolution. - Reuse one client across many images. The binding is cheap to hold and avoids re-instantiating per call.
- Set
SOCAITY_API_KEYin your environment so you never hardcode the key.
- Installed the hosted
tencentarc/gfpgancatalog model. - Loaded a local face image with
ImageFile().from_file. - Restored and upscaled the face in a single hosted call.
- Saved the result with
get_result().save().
- Python SDK reference for the full catalog client contract and the job handle returned by every call.
- Clone any voice with speechcraft for the same client pattern applied to an official model.
- Run your first service if you want the minimal three-line quickstart before going deeper.
- Job lifecycle for how
.get_result(), polling intervals, and timeouts behave.