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 — a collection of presets that are automatically applied based on the detected scene

Built-in AI Preset Selection

If you omit the preset parameter (or set preset=Universal), AI Preset Selection is enabled automatically. This uses machine learning to detect scenes in each image and apply the optimal preset.

These AI Model preset groups are available:

Learn more about the AI Scene detection models here.

Uploading custom presets

You can create custom presets or custom AI Preset Groups and upload them to the Web API:

1. Open Perfectly Clear Workbench and customize your corrections
2. Save your preset and export it as a .preset file
3. Upload the file to your Cloud Account, or by using the preset upload endpoint:

# Create a preset upload request
curl -s -X POST "https://api.perfectlyclear.io/v2/presets/" \
  -H "X-API-KEY: ${PFC_API_KEY}"

This returns a pre-signed upload URL. Upload your .preset file to that URL, and it becomes available for use in correction requests.

For a complete walkthrough, see How Do I Use AI Preset Selection in Web API?

Listing available presets

You can find all your presets on your Cloud Account, or use the /v2/presets endpoint::

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

You can paginate results with limit and offset query parameters. See the API reference for details.

Using a preset

To apply a specific preset, set the preset query parameter to the preset name.

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

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

Other image corrections

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. This is useful when you need to review the recommended crop or manually adjust it before actually cropping in an external tool.

Performance optimizations

Metadata copying

Background Removal and AI Upscaling speed can be optimized by NOT copying metadata from the original file to the output file. This can save several seconds of processing time. The output image will not contain any metadata, including EXIF, IPTC, and XMP. To enable this optimization, set preserveMetadata=false in your request. This can cause issues if the source images are not in sRGB color profile, or if you rely on ratings, EXIF orientation, or other metadata in the output file. The default is preserveMetadata=true, which preserves all metadata and color profiles, but can add several seconds to processing time.

Updating thumbnails

JPEG images contain an embedded thumbnail image that some photo viewers or management software use for quick previews. When a JPEG image is processed, the embedded thumbnail is not automatically updated to reflect the corrections applied to the main image. This can lead to discrepancies between the corrected image and its thumbnail preview. To ensure that the thumbnail matches the corrected image, set updateThumbnail=true in your request. This will update the embedded thumbnail to reflect the corrections, but can add some processing time. The default is updateThumbnail=false, which leaves the original thumbnail unchanged.

Supported files and requirements

• JPEG and PNG images in RGB or RGBA formats
• 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.
• Videos in MP4 and MOV formats. Max filesize is 5GB
• Color Correction, Retouching, Creative Filters, Auto Cropping:
  • Images must be larger than 32x32 pixels and no more than 100,000 pixels on the longer side
  • Must be Less than 21:1 aspect ratio.
  • Below 200 Megapixels
• 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
• Background Removal:
  • Below 30MB in input file size
  • Max output size is 5000 pixels on the longer side - images will automatically be resized if they exceed this limit. This is approximately 14 megapixels

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 specific 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 AI Upscaling

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

Remove Glasses Glare and don't apply color correction

curl -s -X GET "https://api.perfectlyclear.io/v2/pfc?fileKey=${fileKey}&removeGlares=true&preset=none" \
  -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