Using the Web API

This guide explains authentication, correction parameters, job status handling, and common workflows for Perfectly Clear Web API.

Authentication

Use your API key with the X-API-KEY header:

curl -H "X-API-KEY: ${PFC_API_KEY}" "https://api.perfectlyclear.io/v2/upload"

Core endpoints

The overall workflow uses three core endpoints.

/v2/pfc returns a statusEndpoint URL that contains the job ID.

Job lifecycle

A correction job can return these statuses:

• PENDING
• PROCESSING
• COMPLETED
• FAILED
• REJECTED

When complete, the status response includes correctedFile.

Common correction parameters

Use query parameters on /v2/pfc to control output.

For the complete list of parameters, including defaults and accepted ranges, see API reference.

Presets

Presets are created in Perfectly Clear Workbench and can be saved as .preset files. A preset file can contain:

• A single preset that is always applied
• An AI Scene Detection preset group

To apply a specific preset, set the preset query parameter to the preset name. If preset is omitted, AI Preset Selection is used.

You can also set preset=none when you want use other tools like background removal, glasses glare removal, resizing, and output conversion behavior without applying color correction tools.

For example, to apply a preset named "my preset":

curl -s -X GET "https://api.perfectlyclear.io/v2/pfc?fileKey=${fileKey}&preset=my%20preset" \
  -H "X-API-KEY: ${PFC_API_KEY}"

Resizing and upscaling

You can resize by dimensions or scale percentage:

• scale=200 produces an output at 200% of original dimensions - twice the width and height
• width, height, long, and short values are in pixels

When resizing is requested, resize=auto selects the best available upscaling strategy.

The supported resize modes are:

• auto: Automatically selects the best model
• general: General-purpose upscaling for landscapes, products, and large faces
• smallDetails: Optimized for group photos and images with smaller facial details

Resize dimensions can be set with width, height, long, short, or scale.

Background removal

Set removeBackground=true to extract foreground from background.

• If outputType is omitted, output is returned as PNG with transparency
• Use bgColor to apply a specific background color

Glasses glare detection and correction

Set removeGlares=true to enable automatic glasses glare detection and correction. When glare is detected, the correction is applied automatically.

Auto cropping

Auto crop is designed for single-person portraits and consistent head placement.

Set autocrop=true to enable it, and then set these additional auto crop controls as well:

• autocropSize
• autocropX
• autocropY
• cropARW
• cropARH
• autocropTopHeadGap

These values are typically configured in Workbench and then copied into API requests.

Detect-only mode is available with autocropDetectOnly=true (requires autocrop=true), which returns crop coordinates without applying a crop.

Supported files and requirements

• JPEG and PNG images in RGB or RGBA formats
• Images must be larger than 32x32 pixels and less than 100 megapixels, and no more than 100,000 pixels on the longer side. Less that 21:1 aspect ratio.
• Videos in MP4 and MOV formats. Max filesize is 5GB
• Original and corrected files will be accessible at their public URL's for at least 24 hours and not longer than 7 days, and are automatically deleted after this time
• Default LOOKs that you see in Perfectly Clear Workbench are supported in this API. LOOKs from Add-ons are not yet included. Contact us if you need special support for specific LOOKs.
• When using AI Upscaling:
  • Images must be at least 64 pixels on their shorter side
  • Below 50MB in input file size
  • For our General model: max output size is 20,000 pixels on the longer side
  • For our Small Details model: max output size is 8,192 pixels on the longer side

Example requests

Start correction with AI Preset Selection

curl -s -X GET "https://api.perfectlyclear.io/v2/pfc?fileKey=${fileKey}" \
  -H "X-API-KEY: ${PFC_API_KEY}"

Start correction with explicit preset

curl -s -X GET "https://api.perfectlyclear.io/v2/pfc?fileKey=${fileKey}&preset=school%20portrait" \
  -H "X-API-KEY: ${PFC_API_KEY}"

Resize output to long edge 1200

curl -s -X GET "https://api.perfectlyclear.io/v2/pfc?fileKey=${fileKey}&long=1200" \
  -H "X-API-KEY: ${PFC_API_KEY}"

Use small-details upscaling

curl -s -X GET "https://api.perfectlyclear.io/v2/pfc?fileKey=${fileKey}&scale=200&resize=smallDetails" \
  -H "X-API-KEY: ${PFC_API_KEY}"

Sample scripts

You can find sample scripts here to get started with Web API quickly: https://github.com/EyeQ-Imaging/CloudAPI