**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 หากไม่ระบุหรือตั้งเป็น 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 key หรือ key ไม่ถูกต้องหรือถูกเพิกถอนแล้ว

ยอดคงเหลือในบัญชีไม่เพียงพอหรือการสมัครใช้งานหมดอายุแล้ว

บัญชีไม่มีสิทธิ์เข้าถึง endpoint นี้

ใช้ Idempotency-Key ซ้ำกับเนื้อหาคำขอที่ต่างออกไป

ถูกจำกัดอัตราการเรียกใช้ (rate limit) ให้รอตามจำนวนวินาทีในเฮดเดอร์ `Retry-After` ก่อนลองใหม่

เกิดข้อผิดพลาดที่ไม่คาดคิดบนเซิร์ฟเวอร์

ขยายรูปภาพและสร้างรายละเอียดขึ้นใหม่ แทนที่จะแค่ยืดพิกเซล

เพิ่มความละเอียดรูปภาพ

อินพุต

เอาต์พุต

API ที่เกี่ยวข้อง