DEVELOPER REFERENCE

Image upscaler API

The same session-based workflow used by the website: upload an image, follow its progress, and download the result.

This is a shared, session-based service. There are no API keys or guaranteed processing times. Keep the same session cookie across requests, respect usage limits, and avoid submitting images concurrently.

Base path

https://freeaiupscaler.app/upscale/api

1. Start a session and read the limits

A configuration request establishes an HttpOnly session cookie. Store the cookie and use it for every subsequent request.

curl -c cookies.txt \
  https://freeaiupscaler.app/upscale/api/config

Setting	Current limit
Upload formats	Static JPEG, PNG, WebP
Maximum file size	20 MB
Maximum input pixels	24 megapixels
Scale	2 or 4
Maximum output edge	4096 pixels
Maximum output pixels	16 megapixels
Job retention	24 hours after completion or failure, then periodic cleanup

The configuration response is the source of truth for current upload, queue, and hourly limits. One active job is allowed per session. Hourly limits also apply per requesting network.

2. Upload an image

Send a multipart form with one file and a scale of 2 or 4. A successful request returns HTTP 202 and a job object.

curl -b cookies.txt -c cookies.txt \
  -F 'file=@./photo.jpg' \
  -F 'scale=2' \
  https://freeaiupscaler.app/upscale/api/jobs

{
  "id": "YOUR_JOB_ID",
  "status": "queued",
  "progress": 0,
  "queue_position": 1,
  "scale": 2,
  "input_url": "/upscale/api/jobs/YOUR_JOB_ID/input",
  "result_url": null
}

3. Follow the job

Poll every two seconds or less frequently. Status is queued, running, succeeded, or failed. Processing continues if you disconnect.

curl -b cookies.txt \
  https://freeaiupscaler.app/upscale/api/jobs/YOUR_JOB_ID

Completed jobs include a result_url and a result object with source_size, working_size, output_size, and elapsed_seconds. Dimensions are arrays in [width, height] order. Treat stage and error as human-readable information rather than stable machine-readable codes.

4. Download the result

Use the returned result URL with the same session cookie. The endpoint returns a PNG attachment.

curl -b cookies.txt \
  https://freeaiupscaler.app/upscale/api/jobs/YOUR_JOB_ID/result \
  --output upscaled.png

Errors and retrying

Status	Meaning
400 / 422	Invalid upload form or scale
403	Cross-origin submission rejected
404	Job missing, expired, or owned by another session
409	Session already has an active job, or result is not ready
413	File or pixel limit exceeded
415	Unsupported, animated, or unreadable image
429	Hourly limit reached or queue full
507	Storage temporarily at capacity

For rate limits or capacity errors, respect the Retry-After response header when present. Repeated submission attempts will not accelerate an existing job.

Processing details

The model uses a working canvas capped at 960 × 1280 pixels or the rotated equivalent, then exports according to the requested scale and output limits. Large outputs may include interpolation. AI-generated detail can differ from the original; separate face restoration and text-preservation stages are not included.

Read the privacy policy and terms before submitting images.