Image API documentation

One request to a smaller image

Start with the synchronous API.

Send a file with an API key. Tinify validates the decoded image, reserves usage atomically, and returns a two-hour download URL.

Only successful operations count toward usage.
File names and image contents are never used for analytics.
Inputs and results expire after two hours.

cURLPOST /compress

curl --request POST https://tinify.dev/api/v1/images/compress \
  --header "Authorization: Bearer tnf_live_..." \
  --header "Idempotency-Key: 8f349a5b-..." \
  --form "file=@hero.png" \
  --form "quality_mode=balanced"

Core endpoints

One contract across every operation.

Request IDs, quota headers, idempotency, and the error envelope stay the same while operation fields remain explicit.

POST/api/v1/images/compress

Optimize one image and never return a larger result.

POST/api/v1/images/resize

Resize by width, height, scale, or fit strategy.

POST/api/v1/images/crop

Crop with explicit pixel coordinates and dimensions.

GET/api/v1/usage

Read included, reserved, and completed operations.

Asynchronous batches

Upload directly, then track one durable job.

The API keeps large file transfer away from the gateway and exposes a clear status for every file.

1
Create
Request a signed upload session.
POST /api/v1/batches
2
Upload
Send each file directly to its short-lived URL.
3
Commit
Validate the uploaded objects and queue processing.
POST /api/v1/batches/{id}/commit
4
Observe
Poll per-file progress or cancel idempotently.
GET /api/v1/batches/{id}

Honest results

Useful metadata, not optimistic labels.

Compression returns the original with optimized=false when an encoded result would be larger. Resize and crop report increases plainly.

{
  "data": {
    "job_id": "job_01...",
    "status": "succeeded",
    "optimized": true,
    "original_bytes": 1842032,
    "result_bytes": 428119,
    "download_url": "https://...",
    "expires_at": "2026-07-20T14:00:00Z"
  },
  "request_id": "req_01..."
}

Stable error model

Errors you can handle in code.

401: Authentication is missing or invalid
403: The credential lacks the required scope
413: The file exceeds 40 MB or 50 megapixels
415: The decoded image format is not supported
422: The requested operation is invalid
429: A rate or account quota was reached
503: Processing capacity is temporarily unavailable

Retryable responses include Retry-After and every error includes the request ID used by support.