Images

Availability: Images requires explicitly enabled access. Check Images access in Billing before integrating. These guides do not announce general availability.

Before resolving

Your Service Account needs the Images resolve, batch or read scopes for the operations you use. A Customer must configure an active current delivery binding for its Project in the Dashboard. A binding alone does not grant commercial access.

Resolve, batch and polling requests cost no credits and do not consume the CDN delivery allowance. They still use your Service Account's shared API request limit and the Customer traffic-safety policy. Eligible image delivery separately records bytes and operations against the Customer's pooled allowance. Ordinary excess does not automatically charge, upgrade or stop delivery.

Delivery usage counts observed CDN responses, so reports can arrive later and be revised. SteamCall does not estimate or charge for requests missing from provider evidence. For accepted image requests, GET or HEAD 200, partial responses (206), and conditional responses (304) each count as one delivery operation. Their transfer usage includes response headers as well as any image body. An authorized request for a permitted but missing image (404) counts as one operation and zero allowance bytes. Rejected access, rate-limit responses and server errors do not consume delivery allowance.

Resolve and poll

Submit exactly one selector: an existing image ID, an approved source URL, an exact app/name alias, or an app/class/instance alias. Unknown aliases return 404 without fetching a live catalog. Source URL support depends on the approved environment configuration; this API is not an arbitrary URL proxy.

This synthetic request asks for a 128-pixel WebP variant of an existing image:

{
  "selector": {
    "type": "image_id",
    "image_id": "img_11111111111111111111111111111111"
  },
  "sizes": [128],
  "formats": ["webp"]
}

Sizes are 64, 128, 256 and 512. Available formats depend on your enabled Images access. WebP remains the default when formats are omitted. Select AVIF explicitly or request both. Do not submit duplicate selections. Published recipe r1 variants have immutable bytes.

If POST returns 202, wait for Retry-After, then GET the relative Location using the same API origin and your X-API-Key. Follow the exact data.status_url to retain your variant selection.

A polling response uses HTTP 200 even while processing. Inspect data.status and data.settled: partial results can contain ready variants while others are still preparing or have failed. Display ready variants immediately if useful; stop polling when settled is true. Otherwise use retry_after_seconds, add jitter, and stop at your application's deadline. Polling never creates new variants. A 409 image_variants_not_requested requires a new resolve request for those variants.

Batch and retries

Submit 1–100 entries with unique keys. HTTP 200 acknowledges the durable batch; inspect each entry's status code. A pending entry has state: pending and no fabricated image ID. Other entries may already have image resources or terminal errors. Results preserve input order.

Poll the batch's data.status_url with the owning Service Account. A batch is settled when every entry has an outcome and all accepted variants have settled. One failed entry does not discard ready results. Another Service Account cannot recover this private batch.

Use an optional Idempotency-Key of at most 200 characters for POST retries. Reusing an accepted key returns 409 idempotency_replay, including error.detail.original_request_id and a status link. Follow that link with GET. A changed body or different Service Account conflicts. The key scope is Customer, Project and product; rotating a Credential for the same Service Account preserves operation identity.

Delivery URLs and failures

Ready variants include absolute delivery URLs. Save those URLs if needed: ordinary Credential rotation preserves them. Binding disable or access revocation can make them unavailable. Deliberate binding rotation has an explicit overlap deadline; retiring a binding permanently breaks its old URLs. A new binding does not repair the old namespace.

The API response itself is private and must not be shared across workloads. Each read selects the authenticated workload's current binding even when underlying image bytes are shared.

Handle 401 by checking the Credential, 403 by checking scopes and commercial access, and 409 image_binding_required by configuring an active binding. Respect Retry-After on 429 or temporary 503 responses. A 429 can indicate the shared Service Account limit or Customer traffic safety. Do not treat a failed preparation result as a successful image delivery or repeatedly restart work because polling returned a temporary error.

Polling is the MVP readiness path. Notifications are optional and are not required by this flow.

Explore Images

Start with setup, then sources and variants, resolve and polling or batch. Learn how stable URLs, caching, bindings and revocation affect your application. Read usage and corrections, limits and errors, Inventory enrichment, and the request examples.