Skip to content

Usage guide

How to use ImageProAPI from registration to download

ImageProAPI is built around an asynchronous workflow. Authentication is optional, but the recommended path is to create an account, log in to get an access token, upload an image with processing instructions, poll the image detail resource, and download the processed output when the job completes.

1. Authenticate first

Authentication is optional, but registration and login are the best starting point because they unlock the fuller upload flow and higher request limits.

Registration

Send POST /accounts/register/ with username, email, and password.

Login

Send POST /accounts/login/ with credentials to receive access and refresh tokens. 

Authorization: Bearer <access_token>

2. Upload an image job

Uploads are sent to POST /api/images/ as multipart form data. The request has two important fields.

If you do not want to handcraft the request body yourself, use the guided playground. It is the UI route intended to help users build upload requests without manually typing JSON.

original_image

The source image file. Supported formats are jpg, png, and webp.

operations

A JSON array describing the transformations to run in sequence. 

[
  {"operation_type": "resize", "parameters": {"width": 1200, "height": 900}},
  {"operation_type": "compress", "parameters": {"quality": 80}},
  {"operation_type": "convert", "parameters": {"format": "webp"}}
]

3. Supported operations

Resize

Requires width and height in pixels.

Compress

Requires quality. Authenticated users can use 10-95, anonymous users 40-80.

Convert

Requires format. Allowed values are jpg, png, and webp.

Filter

Requires type. Allowed values are grayscale, blur, and sharpen.

4. Track processing state

A successful upload creates an image resource. Use the returned detail URL, or request GET /api/images/{uuid}/, to monitor progress.

Pending

The job has been accepted and is waiting to be processed.

Processing

The worker is handling the image. The response may include an estimated ready time.

Completed

The detail response includes a download URL once the processed image is ready.

5. Download before expiry

Download through GET /api/images/{uuid}/download/ after processing completes. Downloads are only available for a limited time.

Initial expiry window

  • Authenticated users: 1 hour
  • Anonymous users: 10 minutes

After a download

  • Authenticated users: 5 minutes
  • Anonymous users: 20 seconds

6. Limits and request policy

Upload limits

  • Authenticated file size limit: 10 MB
  • Anonymous file size limit: 2 MB
  • Anonymous users can only submit up to 2 operations

Throttle limits

  • Authenticated users: 20 requests per minute
  • Anonymous users: 5 requests per minute
Open Playground Open Swagger Open ReDoc