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

Idempotency-Key

Публичный URL изображения для увеличения

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

URL сгенерированных или обработанных изображений

image_urls

Итоговое количество кредитов, списанных за этот результат.

credits_charged

data

Тело запроса имеет неверный формат или в нём отсутствуют обязательные параметры

API-ключ отсутствует, недействителен или отозван

Недостаточно средств на балансе аккаунта или срок подписки истёк

У аккаунта нет доступа к этому эндпоинту

Idempotency-Key повторно использован с другим телом запроса.

Превышен лимит запросов. Перед повторной попыткой подождите столько секунд, сколько указано в заголовке `Retry-After`.

На сервере произошла непредвиденная ошибка

Увеличивает изображение, восстанавливая детали, а не просто растягивая пиксели.

Увеличение разрешения

Входные данные

Выходные данные

Похожие API