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.

When transformable is true, 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",
  "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": {},
  "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 when transformable is true. 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. When transformable, 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 when dimensions are unavailable, including some ready non-transformable sources.
height number|null: Source height in pixels. null when dimensions are unavailable, including some ready non-transformable sources.
bytes number|null: Stored size in bytes. null only when the byte size is unavailable.
transformable boolean: true requires a supported source format, an original within the Images input ceiling of 20 MB (20,000,000 bytes), and a successful Images probe. Otherwise false.
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. Set it on create or via PATCH; omitted on create it follows the workspace default — public in an ordinary img.pro workspace, private in an app-provisioned one. 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. When transformable is true, apply params to url for exact dimensions, format conversion, effects, or the social/OG card (?size=social); see Transformations.

Lifecycle

Most uploads return status: "ready" immediately. SVG sanitization and transient Images-probe failures may return status: "processing"; poll GET /v1/images/:id until the image is ready or failed.

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.