> ## Documentation Index > Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Image Upscaler > APIXO image upscaling API for single-image 2k, 4k, and 8k enhancement ## Overview Image Upscaler is an asynchronous image-to-image API for enlarging and enhancing one source image. Use it when you already have an image URL and want a higher-resolution output without writing a text prompt. | Capability | Value | | ---------------- | -------------------------- | | Model ID | `image-upscaler` | | Mode | `image-to-image` only | | Input images | Exactly 1 public image URL | | Prompt | Not supported | | Resolution tiers | `2k`, `4k`, `8k` | | Output formats | `jpg`, `png`, `webp` | ## Endpoint and authentication Base URL: ```text theme={null} https://api.apixo.ai/api/v1 ``` | Method | Endpoint | Purpose | | ------ | -------------------------------------------- | ------------------------------------- | | `POST` | `/generateTask/image-upscaler` | Submit an upscaling task | | `GET` | `/statusTask/image-upscaler?taskId={taskId}` | Poll task status and retrieve results | All requests require your APIXO API key: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` Submit requests also require: ```http theme={null} Content-Type: application/json ``` ## Copy-paste async quickstart This minimal request submits a 4k JPG upscaling task and returns a `taskId`. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/image-upscaler" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "async", "input": { "mode": "image-to-image", "image_urls": [ "https://example.com/input.jpg" ], "resolution": "4k", "output_format": "jpg" } }' ``` Successful response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678" } } ``` Save the `taskId`; you need it to poll for the final result. ## Poll for result ```bash theme={null} curl -X GET "https://api.apixo.ai/api/v1/statusTask/image-upscaler?taskId=task_12345678" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Processing response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "processing", "createTime": 1767965610929 } } ``` Success response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "success", "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/upscaled-image.jpg\"]}", "createTime": 1767965610929, "completeTime": 1767965652317, "costTime": 41388 } } ``` Failed response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "failed", "failCode": "Unknown error", "failMsg": "Unknown error.", "createTime": 1767965610929, "completeTime": 1767965620132 } } ``` Parse `resultJson` after `state` becomes `success`: ```javascript theme={null} const payload = JSON.parse(data.resultJson); const imageUrls = payload.resultUrls; ``` Parse `resultJson` only after `state` becomes `success`. ## Request body ### Default 4k JPG ```json theme={null} { "request_type": "async", "input": { "mode": "image-to-image", "image_urls": [ "https://example.com/input.jpg" ], "resolution": "4k", "output_format": "jpg" } } ``` ### 8k WebP ```json theme={null} { "request_type": "async", "input": { "mode": "image-to-image", "image_urls": [ "https://example.com/product-shot.png" ], "resolution": "8k", "output_format": "webp" } } ``` ## Parameters Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery. Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks). Image Upscaler input parameters. Upscaling mode. The only supported value is `image-to-image`. If omitted, the backend defaults to `image-to-image`. Source image URLs. Must contain exactly 1 non-empty public image URL. Target resolution tier. Supported values: `2k`, `4k`, `8k`. Values are case-insensitive and normalized to lowercase. Output image format. Supported values: `jpg`, `png`, `webp`. `jpeg` is accepted as an input alias for `jpg`. ## Response format ### Submit task response `POST /generateTask/image-upscaler` returns a task ID when the task is accepted: API status code. `200` means the task was accepted. Human-readable status message. Unique task identifier used with the status endpoint. ### Status response fields Unique task identifier. Current task state: `pending`, `processing`, `success`, or `failed`. JSON string containing the upscaled image URL in `resultUrls`. Present when `state` is `success`. Machine-readable failure code. Present when `state` is `failed`. Human-readable failure message. Present when `state` is `failed`. Task creation timestamp in Unix milliseconds. Task completion timestamp in Unix milliseconds. Present after completion. Processing duration in milliseconds when available. For polling success responses, Image Upscaler reads this from the upstream inference timing. ## Webhook callback mode Use callback mode when your backend should receive the final result automatically instead of polling. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/image-upscaler" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "callback", "callback_url": "https://your-server.com/webhooks/apixo", "input": { "mode": "image-to-image", "image_urls": [ "https://example.com/input.jpg" ], "resolution": "4k", "output_format": "jpg" } }' ``` Successful callback payload: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "success", "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/upscaled-image.jpg\"]}", "createTime": 1767965610929, "completeTime": 1767965652317, "costTime": 41388 } } ``` See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior. ## Billing Image Upscaler is billed per submitted image at `$0.01 / image`. In the current backend implementation, billing is fixed for the model and does not vary by `resolution` or `output_format`. | Billing dimension | Value | | --------------------------- | --------------- | | Unit | `PER_IMAGE` | | APIXO price | `$0.01 / image` | | Parameter-based tiers | None | | Affected by `resolution` | No | | Affected by `output_format` | No | For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing). ## Latency and polling Image Upscaler tasks run asynchronously. Actual latency varies by source image size, selected target resolution, upstream queue load, and result storage time. | Phase | Status you may see | Client behavior | | ------------------- | ------------------ | ----------------------------- | | Upstream processing | `processing` | Keep polling | | Completed | `success` | Parse `resultJson` | | Failed | `failed` | Read `failCode` and `failMsg` | Recommended polling pattern: | Use case | Recommended first poll | Poll interval | | -------------------------------- | --------------------------- | ----------------------------- | | Normal workloads | 10s-15s after task creation | 5s-10s | | 8k or high-concurrency workloads | Prefer callback mode | If polling, use 10s or longer | For production queues or large batches, use callback mode to avoid frequent polling and to handle longer 8k jobs more cleanly. Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system). ## Errors and troubleshooting ### HTTP errors | Code | Meaning | What to do | | ----- | ------------------------------------------------------------------------- | ------------------------------------------------ | | `400` | Invalid request body, mode, image URL shape, resolution, or output format | Fix the request before retrying | | `401` | Missing or invalid API key | Check the `Authorization` header | | `402` | Insufficient balance or quota | Add balance or switch account/key | | `403` | Key or route cannot access the model | Check permissions and route strategy | | `404` | Task not found | Verify the `taskId` and model ID | | `429` | Rate limit or concurrency limit reached | Retry with exponential backoff | | `500` | Server or unmapped upstream error | Retry with backoff | | `502` | Upstream service error | Retry with backoff | | `504` | Upstream timeout | Retry or use callback mode for long-running jobs | ### Request validation | Condition | Backend behavior | | ------------------------------- | -------------------------------------------------------------------------------- | | Missing `input` | Returns `The required parameter {{input}} is missing.` | | Invalid `mode` | Returns `Invalid mode type. Supported: image-to-image` | | Missing `image_urls` | Returns `The required parameter {{image_urls}} is missing.` | | `image_urls` is not an array | Returns `The parameter {{image_urls}} must be Array type.` | | `image_urls` length is not 1 | Returns `The parameter {{image_urls}} must contain exactly 1 image.` | | `image_urls[0]` is not a string | Returns `The parameter {{image_urls}} Array elements must be String type.` | | `image_urls[0]` is empty | Returns `The parameter {{image_urls}} cannot contain empty string.` | | Invalid `resolution` | Returns `The parameter {{resolution}} must be either '2k', '4k' or '8k'.` | | Invalid `output_format` | Returns `The parameter {{output_format}} must be either 'jpg', 'png' or 'webp'.` | ### Task failure codes | Fail code | Meaning | What to do | | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------- | | `ImageFormatIncorrect` | The upstream service rejected the input image format | Use a direct public JPG, PNG, or WebP image URL | | `SensitiveContent` | Input or generated content was rejected by safety checks | Use a different image | | `RateLimited` | Upstream rate limit was reached | Retry with backoff | | `Timeout` | Upstream service did not finish in time | Retry or use callback mode | | `Unknown error` | Upstream service returned an unmapped failure | Retry with backoff or contact support with the `taskId` | See [Error Codes](/api-reference/errors) for the full error reference. ## Related links * [Generation API Overview](/models) * [Generate Task](/api-reference/generate-task) * [Status Task](/api-reference/status-task) * [Webhooks](/api-reference/webhooks) * [Error Codes](/api-reference/errors) * [Parameter Specification](/api-reference/parameters) * [Routing Strategies](/concepts/routing-strategies) * [Pricing](https://apixo.ai/pricing)