API reference

This page provides the complete endpoint and query parameter reference for Perfectly Clear Web API v2.

Base URL

https://api.perfectlyclear.io/v2

Authentication

Send your API key in the request header:

X-API-KEY: <your_api_key>

Endpoints

Endpoint	Method	Description
`/upload`	`GET`	Get a pre-signed upload URL and `fileKey`
`/pfc`	`GET`	Start a correction job
`/status/{jobID}`	`GET`	Check correction job status
`/presets`	`GET`	List available presets
`/presets/`	`POST`	Create a preset upload request
`/presets/{presetId}`	`GET`	Get a preset
`/presets/{presetId}`	`DELETE`	Delete a preset

Query parameters

`GET /upload`

Parameter	Type	Required	Default	Description
`fileType`	`string`	No	`image`	File type for the upload request. Use `image` or `video`.

`GET /pfc`

Resize-related settings are mutually exclusive. Use only one resize dimension strategy per request (width, height, long, short, or scale).

Parameter	Type	Required	Default	Allowed / Range	Description
`fileKey`	`string`	Yes	—	—	ID of the uploaded file returned by `/upload`.
`fileType`	`string`	No	`image`	`image`, `video`	File type for correction. Must match the uploaded file type.
`preset`	`string`	No	AI preset selection	Any preset name or `none`	Preset to apply. Use `none` to skip correction and perform resize/output-only operations.
`cache`	`boolean`	No	`true`	`true`, `false`	Reuse existing corrected output for identical settings when available.
`outputType`	`string`	No	`original`	`jpg`, `png`, `original`	Output format. `original` keeps source format when supported.
`resize`	`string`	No	`auto`	`auto`, `general`, `smallDetails`	Upscaling mode used when resizing is requested.
`width`	`integer`	No	—	`32` to `10000`	Target width in pixels. Height is derived from aspect ratio.
`height`	`integer`	No	—	`32` to `10000`	Target height in pixels. Width is derived from aspect ratio.
`long`	`integer`	No	—	`32` to `10000`	Target long edge in pixels.
`short`	`integer`	No	—	`32` to `10000`	Target short edge in pixels.
`scale`	`integer`	No	—	Integer percent	Scale percentage. Example: `200` doubles width and height.
`outputQuality`	`integer`	No	`90`	`40` to `100`	JPEG quality setting. Ignored for non-JPEG output.
`autocrop`	`boolean`	No	`false`	`true`, `false`	Enable auto-cropping.
`autocropDetectOnly`	`boolean`	No	`false`	`true`, `false`	Return crop coordinates without applying crop. Requires `autocrop=true`.
`autocropSize`	`string`	No	—	Workbench value	Head size factor for autocrop.
`autocropX`	`string`	No	—	Workbench value	Relative horizontal head offset for autocrop.
`autocropY`	`string`	No	—	Workbench value	Relative vertical head offset for autocrop.
`cropARW`	`string`	No	—	Workbench value	Crop aspect ratio width component.
`cropARH`	`string`	No	—	Workbench value	Crop aspect ratio height component.
`autocropTopHeadGap`	`string`	No	—	Positive value to enable	Top-of-head gap target for autocrop. Zero or negative disables this behavior.
`skip`	`string`	No	`clipart`	`clipart`, `legacy`, `none`	Non-photo skip mode. Ignored when AI preset selection is active.
`removeGlares`	`boolean`	No	`false`	`true`, `false`	Enable glasses glare detection and removal.
`removeBackground`	`boolean`	No	`false`	`true`, `false`	Enable background removal. If output type is omitted, output is PNG with transparency.
`bgColor`	`string`	No	transparent	Hex with `#` or named color	Background color used when `removeBackground=true`.
`preserveMetadata`	`boolean`	No	`true`	`true`, `false`	Preserve source EXIF metadata, especially for upscaling/background-removal workflows.
`updateThumbnail`	`boolean`	No	`false`	`true`, `false`	Regenerate embedded thumbnail metadata.
`includeDetectionData`	`boolean`	No	`false`	`true`, `false`	Include scene detection, face detection and other image data in the `/status` output.

`POST /presets/`

Uploading a custom preset is a two-step process:

Step 1 — Request an upload URL

Send a POST request with the preset metadata. The API returns a pre-signed uploadUrl and a presetId.

Request body (JSON):

{
  "name": "My Custom Preset",
  "description": "Portrait retouching for studio shots"
}

Example:

curl -X POST "https://api.perfectlyclear.io/v2/presets/" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Custom Preset", "description": "Portrait retouching"}'

Response:

{
  "presetId": "abc123",
  "uploadUrl": "https://storage.example.com/presigned-url..."
}

Step 2 — Upload the preset file

Use the uploadUrl from Step 1 to upload your preset file with an HTTP PUT request. No API key is required for this request — authentication is embedded in the pre-signed URL.

curl -X PUT "<uploadUrl>" \
  --upload-file /path/to/your/preset.pcp

Once the upload completes, the preset is available in your account and can be referenced by name in /pfc requests via the preset parameter.

`GET /presets`

Parameter	Type	Required	Default	Description
`limit`	`integer`	No	`20`	Maximum number of presets returned.
`offset`	`integer`	No	`0`	Number of presets to skip before returning results.

Path parameters

Endpoint	Parameter	Type	Description
`/status/{jobID}`	`jobID`	`string`	Correction job identifier returned in `statusEndpoint`.
`/presets/{presetId}`	`presetId`	`string`	Preset identifier.

Status responses

GET /status/{jobID} can return these states:

PENDING
PROCESSING
COMPLETED
FAILED
REJECTED

The /status endpoint will also return different HTTP status codes to indicate the status of the job. These include:

200 the job is still processing
302 the job is complete and the corrected file is ready to download

When the 302 status is returned from the /status endpoint, the location header will contain the URL to download the corrected file. You can use curl -L to follow that redirect and download the corrected file. Other tools will redirect automatically, which makes it simple to check the status and also retrieve the corrected file in one call. You can also prevent this redirect behavior by including the noRedirect=true query parameter in the status call. This will allow you to check the status without automatically downloading the file when it is ready.

Along with these status values, the message will also contain statusText that explains any errors or the processing in a little more detail. Once the job is COMPLETED, the status call will return a correctedFile parameter in the reply, like this:

{
   "status":"COMPLETED",
   "_id":"1234512345",
   "statusText":"done",
   "createdAt":"2023-02-16T23:13:43.821Z",
   "updatedAt":"2023-02-16T23:13:51.831Z",
   "correctedFile":"https://outputdomain.com/images/pfc-54321-12345-123451234_corrected_scene.jpg"
}

If you included includeDetectionData=true in your original correction request, the status response will also include a detectionData object with AI-detected scene, face, and other image data. For example:

{
  "_id": "69d694003274e636c06e4384",
  "status": "COMPLETED",
  "statusText": "",
  "code": 0,
  "correctedFile": "https://outputdomain.com/images/pfc-54321-12345-123451234_corrected_scene.jpg",
  "createdAt": "2025-04-08T17:44:32.164Z",
  "updatedAt": "2025-04-08T17:44:39.004Z",
  "usage": {
    "size": "MEDIUM",
    "imageCorrectionCount": 1,
    "imageResizeCount": 0,
    "classicResizeCount": 0,
    "glaresDetectorCount": 0,
    "videoCorrectionCount": 0,
    "removeBackgroundCount": 0,
    "removeGlaresCount": 0,
    "autoCropCount": 0,
    "removeGlaresTotalCount": 0
  },
  "aiserver": true,
  "timeTaken": 1.56,
  "originalDimensions": {
    "width": 2380,
    "height": 3597
  },
  "detectionData": {
    "facesCount": 1,
    "faces": [
      {
        "confidence": 94,
        "angle": 2,
        "blink": 8,
        "smile": 67,
        "yawAngle": 0,
        "left": 971,
        "top": 431,
        "width": 497,
        "height": 581,
        "leftEye": {
          "x": 1333.879150390625,
          "y": 620.4785766601562
        },
        "rightEye": {
          "x": 1088.085693359375,
          "y": 608.4886474609375
        }
      }
    ],
    "scene": 8,
    "noise": "unknown",
    "redEye": "disabled",
    "warnings": [],
    "message": "",
    "status": "ok"
  }
}

WEB-API Version 2 built on 02-26-2026.

API reference

On this page