> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pembuatan Gambar Qwen Image 3.0

>  - Mode pemrosesan asinkron, mengembalikan ID tugas untuk kueri berikutnya
- Mendukung text-to-image dan image-to-image (1-3 gambar referensi untuk pengeditan)
- Mendukung resolusi 1K / 2K, hingga 6 gambar per permintaan
- Varian Standard dan Pro (Pro lebih kuat untuk layout padat dan teks) 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0",
      "prompt": "A cafe poster with the title Autumn Limited, warm tones, refined layout",
      "size": "16:9",
      "resolution": "1K"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "qwen-image-3.0",
      "prompt": "A cafe poster with the title Autumn Limited, warm tones, refined layout",
      "size": "16:9",
      "resolution": "1K",
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "qwen-image-3.0",
    prompt: "A cafe poster with the title Autumn Limited, warm tones, refined layout",
    size: "16:9",
    resolution: "1K",
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01JGXYZ1234567890ABCDEF"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "Invalid request parameters",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient account balance, please top up and try again",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests, please try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Model yang Didukung

| Model                | Deskripsi                                                                                       | Gambar Maks | Resolusi |
| -------------------- | ----------------------------------------------------------------------------------------------- | ----------- | -------- |
| `qwen-image-3.0`     | Mengikuti instruksi dengan jelas, rendering teks stabil; nilai lebih baik untuk penggunaan umum | 6           | 1K / 2K  |
| `qwen-image-3.0-pro` | Konten lebih kaya; terbaik untuk koran, storyboard, menu, ujian, layout padat                   | 6           | 1K / 2K  |

<Tip>
  Utamakan `-pro` untuk teks/layout padat. Gunakan `qwen-image-3.0` untuk gambar umum. Prompt maks \~**4.5k tokens**. Nama model tidak dapat ditukar dengan seri 2.0.
</Tip>

## Otorisasi

<ParamField header="Authorization" type="string" required>
  Semua endpoint memerlukan autentikasi Bearer Token

  Dapatkan API Key Anda dari [Halaman Manajemen API Key](https://apimart.ai/keys):

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Nama model

  * `qwen-image-3.0` - Standard
  * `qwen-image-3.0-pro` - Pro (teks / layout padat)
</ParamField>

<ParamField body="prompt" type="string" required>
  Deskripsi teks untuk pembuatan gambar, maks \~**4.5k tokens**
</ParamField>

<ParamField body="image_urls" type="string[]">
  Array URL gambar referensi (image-to-image / pengeditan), **1-3 gambar**

  * URL publik `http(s)://` atau `data:image/png;base64,...` (base64 diunggah ulang terlebih dahulu)
  * Format: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF
  * Per file ≤ 10MB; lebar/tinggi disarankan 384-2048 px
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Tingkat resolusi (mempengaruhi tingkat penagihan)

  * `1K` (default; huruf kecil diterima)
  * `2K`

  Anda dapat melewati tingkat dan meneruskan piksel di `size` (mis. `1600x900`). Dengan piksel mentah, area **> 2,25M piksel** ditagih sebagai 2K.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Rasio aspek, atau ukuran piksel eksplisit

  Rasio yang didukung:

  * `1:1` (default)
  * `4:3` / `3:4`
  * `16:9` / `9:16`
  * `3:2` / `2:3`

  Juga menerima gaya `16x9`, atau piksel seperti `1024x1024`. Untuk piksel kustom, **setiap sisi** (lebar dan tinggi) harus **512–2048**, rasio aspek 1:8 \~ 8:1.

  Jika `size` maupun `resolution` tidak diatur, output tetap di **1024×1024**.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Jumlah gambar, **1-6**. Nilai di atas 6 dibatasi menjadi 6.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Prompt negatif: konten yang harus dihindari
</ParamField>

<ParamField body="prompt_extend" type="boolean" default="false">
  Penulisan ulang prompt cerdas

  Default **nonaktif** agar hasil dapat diprediksi. Setel `true` untuk mengaktifkan penulisan ulang cerdas.
</ParamField>

<ParamField body="prompt_extend_mode" type="string">
  Mode penulisan ulang (hanya seri 3.0; memerlukan `prompt_extend: true`)

  * `direct` - bekerja untuk text-to-image dan image-to-image
  * `agent` - **hanya text-to-image**, penulisan ulang lebih agresif

  Nilai tidak valid diabaikan.
</ParamField>

## Tabel Referensi Ukuran

Gabungkan `resolution` (tingkat) + `size` (rasio):

| Resolusi | 1:1       | 4:3       | 3:4       | 16:9      | 9:16      | 3:2       | 2:3       |
| -------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- |
| **1K**   | 1024×1024 | 1152×864  | 864×1152  | 1280×720  | 720×1280  | 1248×832  | 832×1248  |
| **2K**   | 2048×2048 | 2048×1536 | 1536×2048 | 2048×1152 | 1152×2048 | 2048×1360 | 1360×2048 |

## Kasus Penggunaan

### Text-to-image (beberapa)

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "Flat illustration of a city skyline at dusk, warm orange tones",
  "size": "16:9",
  "resolution": "1K",
  "n": 4
}
```

### Layout padat dengan penulisan ulang

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "A Western restaurant menu with appetizers, mains, and desserts columns, five dishes each with prices, serif font, cream background",
  "size": "3:4",
  "resolution": "2K",
  "prompt_extend": true,
  "prompt_extend_mode": "agent"
}
```

### Image-to-image (edit)

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "Change the sign text to Open, keep everything else the same",
  "image_urls": ["https://example.com/shop.jpg"],
  "size": "1:1"
}
```

### Prompt negatif

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "Photorealistic mountain cabin in morning mist",
  "negative_prompt": "text, watermark, people, low resolution",
  "size": "3:2"
}
```

## Batasan

| Item             | Batas                                                 |
| ---------------- | ----------------------------------------------------- |
| Prompt           | ≤ 4.5k tokens                                         |
| Ukuran output    | Piksel kustom: setiap sisi 512–2048; aspek 1:8 \~ 8:1 |
| Jumlah gambar    | 1-6 (kelebihan dibatasi)                              |
| Gambar referensi | 1-3                                                   |
| Format referensi | JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF            |
| Ukuran referensi | ≤ 10MB; lebar/tinggi disarankan 384-2048 px           |

## Response

<ResponseField name="code" type="integer">
  Kode status; 200 saat berhasil
</ResponseField>

<ResponseField name="data" type="array">
  Array data respons

  <Expandable title="Properties">
    <ResponseField name="status" type="string">
      Status tugas; `submitted` saat dibuat
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID tugas untuk polling hasil
    </ResponseField>
  </Expandable>
</ResponseField>

## Perbedaan dari 2.0

|                      | Seri 2.0       | Seri 3.0                        |
| -------------------- | -------------- | ------------------------------- |
| Panjang prompt       | Lebih pendek   | \~4.5k tokens                   |
| `prompt_extend_mode` | Tidak didukung | `direct` / `agent`              |
| Resolusi             | 1K / 2K        | 1K / 2K (Pro 2K biayanya lebih) |
| Gambar referensi     | Didukung       | 1-3 gambar                      |

## Catatan

1. **Asinkron**: pengiriman mengembalikan `task_id`. Poll [Dapatkan Status Tugas](/id/api-reference/tasks/status) setiap **3\~5 detik**; timeout klien \~**3 menit** (2K + multi-gambar lebih lambat).
2. **Penyimpanan**: Gambar di-mirror ke CDN platform untuk akses jangka panjang.
3. **Penagihan**: Per gambar yang dikirim × tingkat resolusi berdasarkan **area piksel aktual** (> 2,25M piksel = 2K). `qwen-image-3.0` mengenakan biaya sama untuk 1K/2K; `-pro` 2K adalah 2× 1K. Kegagalan diganti penuh; gambar referensi gratis.
4. **Error**: Ukuran/rasio tidak valid, `agent` pada image-to-image, referensi tidak terjangkau/terlalu besar → 400; batas laju → 429.

<Note>
  **Kueri hasil**

  Gunakan [Dapatkan Status Tugas](/id/api-reference/tasks/status) untuk progres dan `result.images`.
</Note>