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

アップスケールする画像の公開 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 では、target size を省略するか auto を指定すると、入力のアスペクト比とサポートされるサイズの制約に合わせた 1K 出力になります。nano_banana_2 および nano_banana_pro のアップスケールでは、1K/2K/4K を明示的に指定すると、その出力ティアと課金ティアが選択されます。ピクセル寸法を指定した場合は、最も近いサポート対象のアスペクト比が選ばれ、次に、サポートされる幅と高さがターゲットを満たす最小のティアが選ばれます（上限は 4K）。たとえば、1280x720 は 1K、2560x1440 は 2K、3840x2160 は 4K になります。課金は選択されたティアに従います。target size を省略するか auto を指定すると 1K になります。モデルごとのサイズ制限は引き続き適用されます。

target_size

image

互換性のための元画像ファイルフィールド（非推奨: 代わりに `image` を使用してください）。

file

画像をアップロードしない場合の元画像 URL

アップスケール後の画像と最終的な課金情報

code

message

生成または処理された画像の URL

image_urls

この結果に対して最終的に消費されたクレジット。

credits_charged

data

リクエストボディの形式が正しくないか、必須パラメータが不足しています

API キーが指定されていないか、無効か、失効しています

アカウントの残高が不足しているか、サブスクリプションの有効期限が切れています

アカウントにこのエンドポイントへのアクセス権がありません

Idempotency-Key が異なるリクエストボディで再利用されました。

レート制限に達しました。`Retry-After` ヘッダーに示された秒数だけ待ってからリトライしてください。

サーバーで予期しないエラーが発生しました

単にピクセルを引き伸ばすのではなく、ディテールを再構築しながら画像を拡大します。

画像の高解像度化

入力

出力

関連する API