img.pro

The Image object

Every create, get, and update returns the same Image object; list and batch-update responses wrap it in an envelope, while batch delete wraps deletion tombstones. The two fields you’ll use most are url (the image’s direct CDN link) and sizes (ready-made responsive variants); the rest describe the image’s metadata and state.

On this page

Append query parameters to url (for example ?size=social for an OG card); the full list lives in Transformations.

json 
{
  "id": "abc12345",
  "object": "image",
  "url": "https://src.img.pro/4j2/abc12345.jpg",
  "sizes": {
    "small": {
      "url": "https://src.img.pro/4j2/abc12345.jpg?size=s",
      "width": 426,
      "height": 320
    },
    "medium": {
      "url": "https://src.img.pro/4j2/abc12345.jpg?size=m",
      "width": 853,
      "height": 640
    },
    "large": {
      "url": "https://src.img.pro/4j2/abc12345.jpg?size=l",
      "width": 1440,
      "height": 1080
    }
  },
  "filename": "hero-shot.jpg",
  "format": "jpg",
  "width": 4000,
  "height": 3000,
  "bytes": 245678,
  "status": "ready",
  "published_at": "2024-01-01T00:00:00Z",
  "expires_at": null,
  "created_at": "2024-01-01T00:00:00Z",
  "caption": "Hero shot from launch day",
  "metadata": {},
  "labels": {},
  "nsfw": false
}

Fields

Every field is always present. When a value isn’t known or set, it’s null (or an empty {}), never omitted, so your code can read fields without existence checks.

id string
The image id. Also its URL slug.
object "image"
Object type discriminator.
url string
The image itself: a direct, embeddable CDN URL, and the link to use wherever you show or share the image. Anyone with it can load the image. Append transform parameters to resize, convert, or otherwise change the served rendition.
sizes object
Responsive variants small / medium / large, each { url, width, height }. Add ?size=social to url for a social/OG card.
filename string
Original filename; falls back to {id}.{format}.
format string
The output format, normalized. A stored HEIC serves as jpg.
width number|null
Source width in pixels. null only for some older images whose dimensions were never recorded.
height number|null
Source height in pixels. null only for some older images whose dimensions were never recorded.
bytes number|null
Stored size in bytes. null only when the byte size is unavailable.
status ready
Every Image object is complete and servable. Images still processing, blocked or failed are never returned as Image objects (see Lifecycle).
published_at string
Publish/display date, ISO-8601 UTC. Never null: defaults to the upload time. Drives list ordering (newest first): backdatable, so a 2024 photo uploaded later still sorts under 2024, and re-stamping moves the item to the head of the list.
expires_at string|null
Auto-delete timestamp, ISO-8601 UTC. null = permanent.
created_at string
Upload timestamp, ISO-8601 UTC (e.g. 2024-01-01T00:00:00Z).
caption string|null
Your free-text caption. null when unset.
metadata object
Your custom fields, nested so they can never collide with a core field. May be {}. Limits: at most 50 keys, keys up to 64 chars, values up to 1024 chars.
labels object
Your selector labels, the queryable sibling of metadata. Filter lists with ?label[key]=value (see the API reference). May be {}. Limits: at most 20 keys, key ^[a-z0-9_.-]{1,64}$, values up to 128 chars (no commas, no surrounding whitespace).
nsfw boolean
true when flagged by the moderation pipeline, else false.

sizes covers the common responsive cases. Apply params to url for exact dimensions, format conversion, color and filters, or the social/OG card (?size=social); see Transformations.

Lifecycle

Uploads return status: "ready" or fail in the same request. A rejected upload stores nothing.

Two kinds of image are never returned as Image objects:

  • Blocked images (moderation-locked) are excluded from lists. Fetching one directly returns 403 media_blocked, and the error message includes the coarse reason.
  • Failed images (a processing error that won’t recover) are excluded from lists too. Fetching one directly returns 422 media_failed with a human-readable explanation, so you can learn what went wrong and re-upload.

This keeps the object itself simple: if you hold an Image object, the image is servable. See the Error reference for the error shapes.