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

Clé facultative fournie par l’utilisateur (jusqu’à 255 caractères). Si elle est définie, une réponse réussie (2xx) est mise en cache pendant 7 jours. Une nouvelle tentative avec la même clé et un corps de requête identique renvoie la réponse en cache (sans crédit supplémentaire facturé) ; une nouvelle tentative avec la même clé mais un corps différent renvoie 409. Permet de relancer un POST sans risque en cas d’erreur réseau. Pour les envois multipart/form-data, les requêtes sont comparées sur la base des champs du formulaire et du contenu des fichiers : un envoi relancé est donc bien rejoué même si le client choisit une nouvelle frontière multipart.

Idempotency-Key

image_url

Modèle qui effectue l’agrandissement. Par défaut : `codia_image_v2`. Les crédits suivent la grille tarifaire `image_upscale`.

| Modèle | Par défaut | 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

Dimensions de sortie cibles facultatives, au format WIDTHxHEIGHT. Les tailles de sortie prises en charge dépendent du modèle choisi. Le tarif dépend du palier de résolution de sortie demandé. Pour GPT Image 2 et 2.5, une taille cible omise ou auto produit une sortie 1K adaptée au format de l’image d’entrée et aux contraintes de taille prises en charge. Pour l’agrandissement avec nano_banana_2 et nano_banana_pro, les valeurs explicites 1K/2K/4K sélectionnent le palier de sortie et de facturation correspondant. Pour des dimensions en pixels, le format pris en charge le plus proche est retenu, puis le palier le plus bas dont la largeur et la hauteur prises en charge couvrent la cible, dans la limite de 4K. Par exemple, 1280x720 utilise 1K, 2560x1440 utilise 2K et 3840x2160 utilise 4K. La facturation suit le palier retenu. Une taille cible omise ou auto utilise 1K. Les limites de taille du modèle restent applicables.

target_size

image

Champ de fichier image source conservé pour compatibilité (obsolète : utilisez plutôt `image`).

file

URL de l’image source si aucune image n’est téléversée

Image agrandie et détails de facturation finaux

code

message

image_urls

Crédits finalement facturés pour ce résultat.

credits_charged

data

Le corps de la requête est mal formé ou des paramètres obligatoires sont manquants

La clé d’API est manquante, invalide ou révoquée

Le solde du compte est insuffisant ou l’abonnement a expiré

Le compte n’a pas accès à cet endpoint

Idempotency-Key réutilisée avec un corps de requête différent.

Limite de débit atteinte. Attendez le nombre de secondes indiqué dans l’en-tête `Retry-After` avant de réessayer.

Une erreur inattendue s’est produite sur le serveur

Agrandit une image en reconstituant les détails au lieu de simplement étirer les pixels.

Agrandir l'image

Entrée

Sortie

APIs associées