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

Chave opcional fornecida pelo usuário (até 255 caracteres). Quando definida, uma resposta bem-sucedida (2xx) fica em cache por 7 dias. Uma nova tentativa com a mesma chave e o mesmo corpo de requisição retorna a resposta em cache (sem cobrança extra de créditos); uma nova tentativa com a mesma chave, mas com um corpo diferente, retorna 409. Use para que repetir um POST após falhas de rede seja seguro. Em uploads multipart/form-data, as requisições são comparadas pelos campos do formulário e pelo conteúdo dos arquivos, então um upload repetido é reproduzido mesmo que o cliente escolha um novo boundary multipart.

Idempotency-Key

image_url

Modelo que faz a ampliação. O padrão é `codia_image_v2`. Os créditos seguem a tabela de preços de `image_upscale`.

| Modelo | Padrão | 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

Dimensões de saída opcionais no formato WIDTHxHEIGHT. Os tamanhos de saída suportados dependem do modelo selecionado. O preço usa a faixa de resolução de saída solicitada. Para GPT Image 2 e 2.5, se o tamanho for omitido ou auto, é usada uma saída 1K adaptada à proporção da entrada e às restrições de tamanho suportadas. No upscale com nano_banana_2 e nano_banana_pro, valores explícitos 1K/2K/4K selecionam essa faixa de saída e de cobrança. Para dimensões em pixels, é escolhida a proporção suportada mais próxima e, em seguida, a menor faixa cuja largura e altura suportadas cubram o alvo, com limite de 4K. Por exemplo, 1280x720 usa 1K, 2560x1440 usa 2K e 3840x2160 usa 4K. A cobrança segue a faixa selecionada. Se o tamanho for omitido ou auto, é usado 1K. Os limites de tamanho de cada modelo continuam valendo.

target_size

image

Campo compatível para o arquivo da imagem de origem (obsoleto: use `image`).

file

URL da imagem de origem quando a imagem não é enviada

Imagem ampliada e detalhes finais de cobrança

code

message

image_urls

Créditos finais cobrados por este resultado.

credits_charged

data

O corpo da requisição está malformado ou faltam parâmetros obrigatórios

A chave de API está ausente, é inválida ou foi revogada

O saldo da conta é insuficiente ou a assinatura expirou

Idempotency-Key reutilizada com um corpo de requisição diferente.

Limite de taxa atingido. Aguarde o número de segundos indicado no cabeçalho `Retry-After` antes de tentar novamente.

Amplia uma imagem e reconstrói os detalhes, em vez de simplesmente esticar os pixels.

Aumentar resolução

Entrada

Saída

APIs relacionadas