Authentication

There are three ways to call img.pro, and the only question that picks one is whose images you're acting on: nobody's yet (just trying it), your own, or your users'.

Which mode

Start at the row that matches you. Each links to the rest of this page and to the dashboard where you get the credential.

Anonymous no credential
Just trying it, or a one-off. Upload with no key at all. Results are public, expire after 30 days, and are rate-limited. How →
API key your images
You upload and manage your own images. They’re permanent and count against your plan. This is what most integrations use. How → · Get a key →
App your users’ images
You’re building a product where your users sign in to img.pro and you act on their images and billing. One machine secret, no per-user tokens. How → · Full guide →

All three hit the same REST API at https://api.img.pro/v1 and get back the same Image object. Only the credential differs.

Anonymous

The create endpoint works with no credential at all, so the very first request needs no account:

Request
bash
curl -X POST "https://api.img.pro/v1/images" \
  -F "file=@photo.jpg"

The response is the standard Image object, with a few limits: results are public, expire after 30 days, cap at 20 MB per file, and the endpoint is rate-limited. It’s meant for trying the API and for throwaway transforms, not for anything you need to keep.

Anonymous is the only mode that can’t list, update, or delete — it has no account to scope those to. The moment you need permanence or management, move to an API key (one step away, same request plus a header).

API key

An API key acts on a single account — the team that owns the key. Uploads land in your collection, count against your plan, and are yours to list, update, and delete. Create an account, then create a key from the dashboard:

Create an API key

Send it as a Bearer token on every request. Keys look like img_live_…:

http
Authorization: Bearer img_live_…
Request
bash
curl -X POST "https://api.img.pro/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"

Each key carries one or both abilities, chosen when you create it:

read
The GET endpoints — get, list, usage.
write
The mutating endpoints — POST, PATCH, DELETE, and the batch routes.

Calling an endpoint your key isn’t scoped for returns 403 forbidden. Authenticated requests also take larger files (up to 70 MB) and skip the anonymous rate limits.

Keep your API key secret

A key is full read/write access to one account. Keep it server-side — never ship it in client-side code, a mobile binary, or a public repository.

App

If you’re building a product where your users sign in to img.pro — their images live in img.pro, they pay img.pro, and your app acts on their behalf — that’s the App API. There’s no OAuth, no per-user tokens, and no password handling on your side: your backend holds one machine secret and names the user with a header.

http
Authorization: Bearer img_sk_live_…   # your app's one secret
X-Img-User: m3k9ab2c                  # the user to act on

You get the img_sk_ secret by registering your app, and the user.id from a one-time hosted-login exchange. Both are covered end-to-end in the integration guide:

Building an app

Register your app at /apps (self-serve for paid img.pro accounts).

Quotas

Every account has a monthly upload quota and a storage quota set by its plan — whether that’s your own account (API key) or each of your users’ workspaces (App). Exceeding either returns 403 quota_exceeded with a usage snapshot in error.usage and an upgrade action. Anonymous traffic has no account quota; it’s capped by rate limits (429 rate_limited) instead.

Check current usage any time with GET /v1/usage, and see the per-plan numbers on Pricing.