Web API quickstart

This page explains how to process your first file using the Perfectly Clear Web API v2. The API uses an asynchronous workflow:

Upload
Start correction
Check status
Download result

Prerequisites

Before you begin, ensure that you have:

An active Web API key from EyeQ
curl and jq installed
A sample image or video file

Set your API key as an environment variable:

export PFC_API_KEY="your_api_key_here"

Step 1: Request an upload URL

Request a pre-signed upload URL and a fileKey:

upload_response=$(curl -s -X GET "https://api.perfectlyclear.io/v2/upload" \
  -H "X-API-KEY: ${PFC_API_KEY}")

fileKey=$(echo "${upload_response}" | jq -r '.fileKey')
upload_url=$(echo "${upload_response}" | jq -r '.upload_url')

echo "fileKey: ${fileKey}"

Step 2: Upload your file

Upload your file to the pre-signed URL:

curl -s -X PUT "${upload_url}" --upload-file sample.jpg

Step 3: Start correction

Start a correction job using the same fileKey:

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

status_endpoint=$(echo "${process_response}" | jq -r '.statusEndpoint')
echo "status endpoint: ${status_endpoint}"

By default, Perfectly Clear uses AI Preset Selection when you do not pass a preset parameter.

Step 4: Poll status and download result

Poll the status endpoint until the job is complete:

while true; do
  status_response=$(curl -s -X GET "${status_endpoint}" -H "X-API-KEY: ${PFC_API_KEY}")
  status=$(echo "${status_response}" | jq -r '.status')

  echo "status: ${status}"

  if [ "${status}" = "COMPLETED" ]; then
    corrected_url=$(echo "${status_response}" | jq -r '.correctedFile')
    curl -L -s "${corrected_url}" -o corrected.jpg
    echo "Saved corrected file to corrected.jpg"
    break
  fi

  if [ "${status}" = "FAILED" ] || [ "${status}" = "REJECTED" ]; then
    echo "Job failed: ${status_response}"
    exit 1
  fi

  sleep 2
done

Complete example script

#!/bin/bash
set -e

INPUT=${1:-sample.jpg}
OUTPUT=${2:-corrected.jpg}

if [ -z "${PFC_API_KEY}" ]; then
  echo "Set PFC_API_KEY first"
  exit 1
fi

if [ ! -f "${INPUT}" ]; then
  echo "File ${INPUT} not found"
  exit 1
fi

upload_response=$(curl -s -X GET "https://api.perfectlyclear.io/v2/upload" \
  -H "X-API-KEY: ${PFC_API_KEY}")

fileKey=$(echo "${upload_response}" | jq -r '.fileKey')
upload_url=$(echo "${upload_response}" | jq -r '.upload_url')

curl -s -X PUT "${upload_url}" --upload-file "${INPUT}" > /dev/null

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

status_endpoint=$(echo "${process_response}" | jq -r '.statusEndpoint')

while true; do
  status_response=$(curl -s -X GET "${status_endpoint}" -H "X-API-KEY: ${PFC_API_KEY}")
  status=$(echo "${status_response}" | jq -r '.status')

  if [ "${status}" = "COMPLETED" ]; then
    corrected_url=$(echo "${status_response}" | jq -r '.correctedFile')
    curl -L -s "${corrected_url}" -o "${OUTPUT}"
    echo "Saved to ${OUTPUT}"
    break
  fi

  if [ "${status}" = "FAILED" ] || [ "${status}" = "REJECTED" ]; then
    echo "Correction failed: ${status_response}"
    exit 1
  fi

  sleep 2
done

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