Upscale an image
POST/upscales
Re-renders an image the account owns at 2K or 4K with an AI model, as a NEW asset (its derivation says so); the original is never changed. It is a faithful re-render, not a pixel-exact resample: keep or delete the result, nothing is refunded for a delivered render. Answers 202 at once; poll GET /upscales/{upscaleId} until status is SUCCEEDED, then read the asset at GET /assets/{assetId}. Credits are held when the request is accepted and charged only for a delivered image. Idempotency-Key is required.
Request
Responses
- 202
- 400
- 401
- 402
- 403
- 404
- 409
- 422
- 429
- 503
Accepted - or the replay of an earlier create with this key.
Response Headers
The upscale: /api/public/v1/upscales/{upscaleId}.
Bad Request. The Idempotency-Key header is missing (IDEMPOTENCY_KEY_REQUIRED) or malformed (INVALID_IDEMPOTENCY_KEY).
Unauthorized. Missing, malformed, unknown, revoked, or expired bearer token — or the token owner no longer holds the required entitlement (ENTITLEMENT_LOST). A uniform problem body is returned with a distinct code; no owner/condition detail (no-leak).
Payment Required (INSUFFICIENT_CREDITS). The account cannot cover the upscale; nothing was held or created.
Forbidden. The key lacks the required scope (API_TOKEN_SCOPE_DENIED): creating needs runs:write, reading runs:read. Or the plan does not include this size (IMAGE_UPSCALE_NOT_ENTITLED).
Not Found (ASSET_NOT_FOUND or PRODUCT_NOT_FOUND). The source is not the account's, is deleted, is not a still image, or the product slot is empty - these are indistinguishable.
Conflict. An upscale of this image to this size is already in progress (IMAGE_UPSCALE_IN_PROGRESS); the active rate card has no price for this size (IMAGE_UPSCALE_UNPRICED); a create with this key is still in progress (IDEMPOTENCY_IN_PROGRESS, retry after Retry-After); or the key was used for a different request (IDEMPOTENCY_KEY_REUSED). Nothing was held or created.
Response Headers
Seconds to wait before retrying.
Unprocessable Content. The body is malformed (VALIDATION_ERROR, every field in errors[]); the image is already as large as the target (IMAGE_UPSCALE_TARGET_NOT_LARGER, detail states the source's size); or it could not be read (IMAGE_UPSCALE_SOURCE_UNREADABLE).
Too Many Requests. More requests per minute on this key than the run plane allows (a plain-text body with Retry-After); or too many image jobs are already running for the account (LIMIT_EXCEEDED).
Service Unavailable (WRITES_PAUSED). Writes are paused for this account; nothing was created and the Idempotency-Key is still usable: retry the SAME request after Retry-After.
Response Headers
Seconds to wait before retrying.