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.

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://test.src.img.pro/4j2/abc12345.jpg",
  "page_url": "https://test.img.pro/abc12345",
  "sizes": {
    "small":  { "url": "https://test.src.img.pro/4j2/abc12345.jpg?size=s", "width": 426,  "height": 320 },
    "medium": { "url": "https://test.src.img.pro/4j2/abc12345.jpg?size=m", "width": 853,  "height": 640 },
    "large":  { "url": "https://test.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",
  "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": {},
  "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. Append transform parameters to resize, convert, or otherwise change the served rendition. 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. 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 retained historical rows whose dimensions were unavailable.
height number|null: Source height in pixels. null only for retained historical rows whose dimensions were unavailable.
bytes number|null: Stored size in bytes. null only when the byte size is unavailable.
status ready: Every Image object is complete and servable. Internal processing rows, blocked media, and failed media aren’t Image objects at all (see Lifecycle).
public boolean: Whether the viewer page is publicly accessible. Set it on create or via PATCH; omitted on create it follows the bucket’s saved default: private for new App buckets; migrated collections retain their previous default. When false, page_url is still returned but 404s for anyone outside the owning workspace, while url and every sizes variant keep serving. Private images still appear in your own authenticated list.
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, effects, or the social/OG card (?size=social); see Transformations.

Lifecycle

Uploads return status: "ready" or fail synchronously. A failed size or decoder capability check creates no Image state.

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. See the Error Reference for the error shapes.