Image Optimization Endpoint

Authoritative technical reference for the core POST /v1/optimize image processing endpoint.

Image Optimization Endpoint

The primary endpoint for optimizing, transcoding, and resizing images is:

POST https://api.smallpict.app/v1/optimize
(Alias: POST https://api.smallpict.app/v1/convert)

📥 Request Format (JSON Payload)

POST /v1/optimize HTTP/1.1
Host: api.smallpict.app
X-API-Key: sp_live_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
X-Timestamp: 1716301234
X-Signature: 3a9f8b2c4d6e8a0f1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a
Content-Type: application/json
Idempotency-Key: c9b8a7f6-e5d4-4c3b-2a1f-0e9d8c7b6a5f

Request Body Schema

{
  "filename": "hero-banner.jpg",
  "mime_type": "image/jpeg",
  "filesize": 1654200,
  "options": {
    "format": "avif",
    "quality": 80,
    "max_width": 1920,
    "lossless": false,
    "strip_metadata": true
  }
}

Field	Type	Required	Description
`filename`	string	Yes	Original filename of the asset (e.g. `banner.png`)
`mime_type`	string	Yes	MIME type (e.g. `image/jpeg`, `image/png`, `image/webp`)
`filesize`	integer	Yes	Total file size in bytes (must be > 0)
`options.format`	string	No	Target format: `avif`, `webp`, `jpg`, `png` (Default: `webp`)
`options.quality`	integer	No	Compression quality between `1` and `100` (Default: `80`)
`options.max_width`	integer	No	Downscale maximum long-edge dimension in pixels
`options.lossless`	boolean	No	Enable pixel-perfect lossless compression (Default: `false`)
`options.strip_metadata`	boolean	No	Strip camera EXIF / color profile metadata (Default: `true`)

📤 Response (200 OK)

Upon initialization, SmallPict returns a secure presigned upload URL and an asynchronous job tracker ID:

{
  "upload_url": "https://smallpict-staging.s3.amazonaws.com/uploads/user@example.com/a1b2c3d4/hero-banner.jpg?X-Amz-Signature=...",
  "job_id": "job-a1b2c3d4",
  "object_key": "uploads/user@example.com/a1b2c3d4/hero-banner.jpg",
  "bucket": "smallpict-staging",
  "status": "queued"
}

🔄 Checking Job Status

Query conversion progress using:

GET https://api.smallpict.app/v1/optimize/status?job_id=job-a1b2c3d4

Completed Response (200 OK)

{
  "job_id": "job-a1b2c3d4",
  "status": "completed",
  "url": "https://cdn.smallpict.app/opt/hero-banner.avif",
  "format": "avif",
  "bytes_saved": 1456200,
  "savings_percentage": 88.03,
  "created_at": "2026-08-23T08:00:00Z",
  "updated_at": "2026-08-23T08:00:01Z"
}