**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

code

message

image_urls

credits_charged

data

请求体格式错误或缺少必填参数

Idempotency-Key 已被用于不同的请求体。

请求频率超限。请等待 `Retry-After` 响应头中指定的秒数后再重试。

放大图片并重建细节，而不是简单地拉伸像素。

图片高清放大

输入

输出

相关 API