The Image object

Every endpoint returns the same object. 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.

You transform any url by appending query parameters (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",
  "page_url": "https://img.pro/abc12345",
  "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,
  "transformable": true,
  "status": "ready",
  "public": true,
  "published_at": "2024-01-01T00:00:00Z",
  "expires_at": null,
  "created_at": "2024-01-01T00:00:00Z",
  "caption": "Hero shot from launch day",
  "metadata": {},
  "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, transformable CDN URL. Included on every plan.
page_url string: The shareable viewer page. This is the link you send to a person to open the image in a browser.
sizes object: Responsive variants small / medium / large, each { url, width, height }. Included on every plan; {} for non-transformable sources. For a social/OG card, add ?size=social to url.
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 while processing.
height number|null: Source height in pixels. null while processing.
bytes number|null: Stored size in bytes. null while processing.
transformable boolean: false for sources that can’t be CDN-transformed (SVG/BMP/ICO).
status ready|processing: processing while a queued format converts; ready once the image is servable. Blocked and failed media aren’t Image objects at all (see Lifecycle).
public boolean: Whether the viewer page is publicly accessible.
published_at string|null: Publish/display date, ISO-8601 UTC. null = draft. Backdatable, so a 2024 photo uploaded later still sorts under 2024.
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.
nsfw boolean: true when flagged by the moderation pipeline, else false.

sizes covers the common responsive cases. For exact dimensions, format conversion, effects, or the social/OG card (?size=social), apply transform params to url; see Transformations.

Lifecycle

Most uploads return status: "ready" immediately. Formats that need conversion (HEIC, for example) return status: "processing" with null dimensions; poll GET /v1/images/:id until the image is ready.

Two states never appear as objects on the read surface:

Blocked images (moderation-locked) are excluded from lists. Fetching one directly returns 403 media_blocked; if you own the image, 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 (or about to be). See the Error Reference for the error shapes.