**Cost**: Model-priced per successful call. See the Credit Matrix for `image_upscale` model and resolution prices.

Image Upscale supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://openapi.codia.ai/v2/open/image/upscale' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Enlarge an image to a higher resolution while reconstructing detail (not just bilinear interpolation). Model-driven — different models trade off sharpness, smoothness, and processing time. Synchronous.

## What this API is for

Recovering print-quality assets from low-resolution sources, preparing low-res user uploads for downstream tasks (e.g. background removal that needs more pixels), or salvaging legacy thumbnails. Use it before any pipeline step that benefits from more pixels — don't chain it after a generative step (those models already output at their target resolution).

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to upscale. |
| `model` | no | Model ID. Defaults to `codia_image_v2`. See the model price table for available models. |
| `target_size` | no | Target output dimensions, such as `3840x2160`. |

Use `target_size` to request output dimensions where supported by the model. For GPT Image 2 and 2.5, omitted or `auto` target size uses a 1K output adapted to the input aspect ratio and supported size constraints. Other models use their own defaults when target size is omitted.

For nano_banana_2 and nano_banana_pro upscale, explicit 1K/2K/4K values select that output and billing tier. For pixel dimensions, the closest supported aspect ratio is selected, then the lowest tier whose supported width and height cover the target, capped at 4K. For example, 1280x720 uses 1K, 2560x1440 uses 2K, and 3840x2160 uses 4K. Billing follows the selected tier. Omitted or auto target size uses 1K. Model size limits still apply.

## Response

`ImageUpscaleSuccess` shape — `data.image_urls` is an array of CDN URLs (length 1 for this endpoint). Use the first entry.

```json
{ "code": 0, "message": "ok", "data": { "image_urls": ["https://cdn.codia.ai/upscale/xyz.png"], "credits_charged": 16 } }
```

## Billing & limits

- Credits follow the `image_upscale` model/resolution table in the global Credit Matrix.
- The response includes `image_urls` and `credits_charged`, which reports the final charge.
- Use `POST /v2/open/estimate` with the same model and target size to estimate credits.
- Synchronous. Latency scales with input size; very large inputs may approach minute-scale.

## Errors

Standard set — `400` bad input, `401`/`403` auth, `402` credits, `429` rate limit, `500` internal.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_upscale` instead. Inputs and credit cost are identical.

選填，由用戶自訂的冪等鍵（最多 255 個字元）。設定後，成功（2xx）的回應會快取 7 天。以相同的鍵 + 相同的請求主體重試時，會返回快取的回應（不另外扣除點數）；以相同的鍵但不同的請求主體重試，則返回 409。可讓 POST 請求在網絡故障時安全重試。對於 multipart/form-data 上載，請求會依表單欄位與檔案內容比對，因此即使客戶端產生新的 multipart boundary，重試的上載仍會重播先前的結果。

Idempotency-Key

image_url

執行放大的模型。預設為 `codia_image_v2`。點數依 `image_upscale` 定價表計算。

| 模型 | 預設 | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| default / `codia_image_v2` | 16 | - | - | - |
| `ideogram_v3` | 16 | 16 | 16 | - |
| `nano_banana_2` | 18 | 18 | 27 | 41 |
| `nano_banana_pro` | 36 | 36 | 36 | 65 |
| `gpt_image` | 57 | 57 | 115 | 190 |
| `gpt_image_2_5` | 57 | 57 | 115 | 190 |

model

選填的目標輸出尺寸，格式為 WIDTHxHEIGHT。支援的輸出尺寸取決於所選模型。定價依請求的輸出解像度級別計算。對於 GPT Image 2 與 2.5，省略或設為 auto 時，會使用依輸入長寬比與尺寸限制調整的 1K 輸出。對於 nano_banana_2 與 nano_banana_pro 放大，明確指定 1K/2K/4K 即可選擇對應的輸出與計費級別。若指定像素尺寸，會先選擇最接近的支援長寬比，再選擇寬高皆能涵蓋目標的最低級別，上限為 4K。例如 1280x720 使用 1K，2560x1440 使用 2K，3840x2160 使用 4K。依所選級別計費。省略或設為 auto 時使用 1K。模型本身的尺寸限制仍然適用。

target_size

image

相容用的來源圖片檔案欄位（已棄用：請改用 `image`）。

file

未上載圖片時使用的來源圖片 URL

code

message

image_urls

credits_charged

data

請求主體格式錯誤或缺少必要參數

Idempotency-Key 已被用於不同的請求主體。

已達速率限制。請等待 `Retry-After` 標頭中指定的秒數後再重試。

放大圖片並重建細節，而非單純拉伸像素。

圖片畫質放大

輸入

輸出

相關 API