**Cost**: configured in `pricing.yaml` (model-dependent — see `model` field).

Image to Image 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/image_to_image' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png' \
  -F 'prompt=make it watercolor'
```

Transform a source image into a new one steered by a text prompt — "this photo, but Studio Ghibli style", "this product shot, but at sunset", "this sketch, refined into a finished painting". Synchronous. Different from `remix` (which preserves more structure) and `replace_background` (which only changes the background).

## What this API is for

Style transfer, refinement, restylization, scene editing — any task framed as "take this image and change it according to this instruction". Holds onto the source's overall composition more loosely than `remix` — use that one when you need tighter structural preservation.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `prompt` | yes | Text description of the desired transformation. |
| `model` | no | Default `nano_banana_2`. Same model menu as `generate_image`: `nano_banana_2`, `nano_banana_pro`, `gpt_image_2_5`, `gpt_image`, `qwen_image_3_pro`, `hy_image_3_5`, `seedream_5_pro`, `seedream_5_flash`, `seedream_5`, `seedream_4_5`, `recraft_v4`, `flux_3`, `flux_2_pro`, `flux_2_max`, `ideogram_v4`. |
| `size` | no | Output dimensions as `WIDTHxHEIGHT`. For GPT Image 2 and 2.5, size is normalized into the pricing resolution bucket (`1K`, `2K`, `4K`). |
| `quality` | no | For `gpt_image`, use `low`, `medium`, `high`, or `auto`. For `gpt_image_2_5` (including Flare and Sunburst), `xhigh` and `max` are also supported. Omitted quality or `auto` uses the medium billing bucket. For non-GPT models, this field may carry the resolution tier (for example `1K` or `2K`). |
| `background` | no | GPT Image only: `transparent`, `opaque`, or `auto`. Ignored by non-GPT models. |
| `reference_images` | no | Additional public image URLs for style or subject guidance. For `qwen_image_3_pro`, `image_to_image` accepts up to 2 `reference_images`. For `flux_3`, the source image plus additional references may total up to 10 images. |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` carries one URL of the transformed image.

## Billing & limits

- Credits come from `pricing.yaml` for the selected model. For GPT Image 2 and 2.5, the billing key combines resolution and quality, e.g. `1K_high`; call `GET /v2/open/limits` for live values.
- Synchronous, single-call.

## When to pick what

- Want a complete transformation? → `image_to_image`.
- Want to keep structure but change style? → `remix`.
- Want to keep subject and only change scene? → `replace_background`.
- Want to start from scratch with optional refs? → `generate_image`.

## Errors

Standard set.

> **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_to_image` instead. Inputs and credit cost are identical.

คีย์ที่ผู้ใช้กำหนดเอง (ไม่บังคับ ยาวสูงสุด 255 อักขระ) เมื่อกำหนดไว้ การตอบกลับที่สำเร็จ (2xx) จะถูกแคชไว้ 7 วัน การลองใหม่ด้วยคีย์เดิม + เนื้อหาคำขอที่เหมือนกันทุกประการจะได้การตอบกลับที่แคชไว้ (ไม่หักเครดิตเพิ่ม) ส่วนการลองใหม่ด้วยคีย์เดิมแต่เนื้อหาคำขอต่างกันจะได้ 409 ใช้เพื่อให้ส่ง POST ซ้ำได้อย่างปลอดภัยเมื่อเครือข่ายขัดข้อง สำหรับการอัปโหลดแบบ multipart/form-data ระบบจะเปรียบเทียบคำขอจากฟิลด์ในฟอร์มและเนื้อหาไฟล์ ดังนั้นการอัปโหลดซ้ำจะได้ผลลัพธ์เดิมแม้ไคลเอนต์จะสร้าง multipart boundary ใหม่

Idempotency-Key

URL สาธารณะของรูปภาพต้นฉบับที่จะแปลง

image_url

ข้อความอธิบายการแปลงที่ต้องการ

prompt

โมเดลที่ใช้แปลงภาพจากภาพ (image-to-image) ค่าเริ่มต้นคือ `nano_banana_2` โมเดลที่รองรับตรงกับ Codia Studio สำหรับการสร้างภาพจากภาพ เครดิตกำหนดไว้ใน `pricing.yaml` และส่งคืนโดย `GET /v2/open/limits`

| โมเดล | เหมาะสำหรับ |
| --- | --- |
| `nano_banana_2` | แก้ไขภาพจากภาพได้รวดเร็วตาม prompt ข้อความ (Gemini 3.1 Flash) |
| `nano_banana_pro` | การแปลงภาพ 4K คุณภาพระดับสตูดิโอ พร้อมการให้เหตุผลขั้นสูง (Gemini 3 Pro) |
| `gpt_image_2_5` | GPT Image 2.5 พร้อมรุ่นย่อย Flare และ Sunburst รองรับคุณภาพ low, medium, high, xhigh, max และ auto |
| `gpt_image` | แก้ไขโดยอิงภาพอ้างอิงด้วยความเที่ยงตรงสูงพร้อมข้อความคมชัด รองรับ `quality` (`low`/`medium`/`high`/`auto`) และ `background` (`transparent`/`opaque`/`auto`) |
| `qwen_image_3_pro` | แก้ไขภาพอย่างละเอียด จัดเลย์เอาต์ได้ดีและเรนเดอร์ข้อความหลายภาษาได้ รองรับเอาต์พุต 512/1K/2K ไม่รองรับ 4K รับ `reference_images` ได้สูงสุด 2 รูป |
| `hy_image_3_5` | แก้ไขภาพสมจริงโดยอิงภาพอ้างอิงที่ 1K/2K ไม่รองรับ 4K รับ `reference_images` ได้สูงสุด 4 รูปนอกเหนือจากภาพต้นฉบับ |
| `seedream_5_pro` | แก้ไขภาพที่แม่นยำสูงด้วยการให้เหตุผลเชิงภาพขั้นสูง รองรับเอาต์พุต 1K และ 2K |
| `seedream_5_flash` | แก้ไขภาพได้เร็วและต้นทุนต่ำ รองรับเอาต์พุต 1K และ 2K ในราคาเดียวกัน |
| `seedream_5` | การแปลงภาพสมจริงที่มีรายละเอียดประณีต ขนาดอิงฐาน 1920 |
| `seedream_4_5` | การแปลงภาพสมจริงที่ให้ผลสม่ำเสมอ ขนาดอิงฐาน 1920 |
| `recraft_v4` | แปลงรูปถ่ายเป็นภาพประกอบ ไอคอน หรืองานสไตล์เวกเตอร์ |
| `flux_3` | แก้ไขภาพ 1K/2K/4K แบบเนทีฟ รับภาพอินพุตรวมได้สูงสุด 10 รูป |
| `flux_2_pro` | การแก้ไขภาพคุณภาพสูงด้วย FLUX |
| `flux_2_max` | FLUX ระดับคุณภาพสูงสุดสำหรับงานแก้ไขระดับพรีเมียม |
| `ideogram_v4` | เส้นทางรีมิกซ์/แก้ไขรุ่นล่าสุดของ Ideogram สำหรับภาพที่เน้นตัวอักษร |

model

ขนาดเอาต์พุตในรูปแบบ `WIDTHxHEIGHT` (ไม่บังคับ) เช่น `1024x1024` สำหรับ GPT Image 2 และ 2.5 ขนาดจะใช้ร่วมกับ `quality` เพื่อกำหนดคีย์ราคา FLUX 2 Pro/Max รองรับพรีเซ็ตขนาด 1K/2K ด้วย คำขอที่ใหญ่เกิน รวมถึง 4K จะถูกลดขนาดลงเหลือไม่เกินประมาณ 4MP (2048x2048 สำหรับภาพสี่เหลี่ยมจัตุรัส) ไม่รองรับเอาต์พุต 4K แบบเนทีฟ การคิดเงินใช้พื้นที่เอาต์พุตหลังปรับขนาดแล้ว: หากรวมไม่เกิน 1,048,576 พิกเซลจะคิดราคา 1K และเอาต์พุตที่ใหญ่กว่านั้นจะคิดราคา 2K ขนาดที่ระบุชัดเจนจะมีลำดับความสำคัญเหนือคำใบ้ความละเอียดใน quality

size

สำหรับ `gpt_image` ให้ใช้ `low`, `medium`, `high` หรือ `auto` สำหรับ `gpt_image_2_5` (รวมถึง Flare และ Sunburst) รองรับ `xhigh` และ `max` ด้วย หากไม่ระบุ quality หรือใช้ `auto` จะคิดเงินในระดับ medium สำหรับโมเดลที่ไม่ใช่ GPT ฟิลด์นี้อาจใช้ระบุระดับความละเอียด (เช่น `1K` หรือ `2K`)

quality

ใช้ได้กับ GPT Image เท่านั้น ขอพื้นหลังแบบโปร่งใสหรือทึบเมื่อรองรับ โมเดลที่ไม่ใช่ GPT จะไม่สนใจค่านี้

background

URL รูปภาพอ้างอิงเพิ่มเติมสำหรับกำหนดสไตล์หรือวัตถุหลัก สำหรับ qwen_image_3_pro นั้น image_to_image รับ reference_images ได้สูงสุด 2 รูป

reference_images

ไฟล์รูปภาพต้นฉบับ

image

ฟิลด์ไฟล์รูปภาพต้นฉบับสำหรับความเข้ากันได้ (เลิกใช้แล้ว: ให้ใช้ `image` แทน)

file

URL รูปภาพต้นฉบับ เมื่อไม่ได้อัปโหลดรูปภาพ

โมเดล (ไม่บังคับ)

URL ของรูปภาพที่ประมวลผลแล้ว

code

message

URL ของรูปภาพที่สร้างหรือประมวลผลแล้ว

image_urls

data

เนื้อหาคำขอมีรูปแบบไม่ถูกต้องหรือขาดพารามิเตอร์ที่จำเป็น

ไม่มี API key หรือ key ไม่ถูกต้องหรือถูกเพิกถอนแล้ว

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

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

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

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

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

แปลงรูปภาพตามคำสั่งข้อความ ตั้งแต่การเปลี่ยนสไตล์ไปจนถึงการแก้ไขฉาก

รูปภาพเป็นรูปภาพ

อินพุต

เอาต์พุต

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