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

# Buat Gambar

> Membuat gambar berdasarkan prompt

## Ringkasan

Untuk coding agents, cari shortlist gambar yang direkomendasikan saat ini terlebih dahulu dengan `GET /v1/models?recommended_for=image`, lalu kirim `model` yang dipilih secara eksplisit ke endpoint ini.

`gpt-image-2` adalah model GPT Image dengan penagihan berbasis token. TokenLab mengikuti rincian `usage` resmi OpenAI untuk menghitung token input teks, input gambar, input cache jika dilaporkan, dan output gambar; model ini tidak ditagih sebagai harga tetap per gambar.

Untuk pembuatan gambar dengan `gpt-image-2`, parameter publik yang didukung adalah `prompt`, `n`, `size`, `quality`, `response_format`, `async`, `background`, `output_format`, `output_compression` atau `compression`, `moderation`, dan `user`. Jika `size` atau `quality` tidak dikirim, TokenLab memakai `auto`; nilai `size` kustom harus mengikuti kontrak fleksibel `WIDTHxHEIGHT` yang dijelaskan di bawah.

`input_fidelity` bukan bagian dari kontrak publik TokenLab saat ini untuk `gpt-image-2`; hilangkan field ini atau request akan mengembalikan `400 unsupported_parameter`.

### Catatan perilaku model

Google Gemini tidak memakai kontrak selector yang sama:

* `gemini-3.1-flash-image`, `gemini-3-pro-image`, dan `nano-banana-pro` mendukung `aspect_ratio` plus `resolution` (`1k`, `2k`, `4k`) untuk operasi publik text-to-image dan image-edit/image-to-image.
* `nano-banana-2` mendukung `aspect_ratio` plus `resolution` (`1k`, `2k`, `4k`) hanya untuk text-to-image dalam kontrak TokenLab saat ini.
* `gemini-2.5-flash-image`, `nano-banana`, dan `nano-banana-edit` mendukung `aspect_ratio` tetapi tidak menyediakan pemilihan `resolution` publik.
* Untuk request Nano Banana dengan gambar referensi, gunakan `nano-banana-edit` atau `nano-banana-pro` pada endpoint ini (`/v1/images/generations`) dengan `operation: "image-to-image"` dan `image_urls`. Jangan kirim request gambar referensi Nano Banana ke `/v1/images/edits`.
* Untuk request Nano Banana image-to-image, `nano-banana-pro` dapat menyertakan `resolution` (`1k`, `2k`, `4k`); `nano-banana-edit` harus menghilangkannya. `nano-banana` dan `nano-banana-2` adalah model text-to-image dalam detail model saat ini.
* Gambar referensi pada endpoint ini dapat dikirim sebagai JSON `image_url` / `image_urls`, atau sebagai file multipart `image`. `/v1/images/generations` tidak menerima `images[]` atau `file_id`; referensi `/v1/files` hanya untuk model `/v1/images/edits` yang mendokumentasikan `images[].file_id`.

Untuk keluarga gambar Google, utamakan `aspect_ratio` dan hanya kirim `resolution` jika model secara eksplisit mendukungnya.

Model gambar xAI Grok Imagine (`grok-imagine-image`, `grok-imagine-image-quality`, dan legacy `grok-imagine-image-pro`) mendukung `aspect_ratio` plus `resolution` (`1k`, `2k`). `grok-imagine-image-pro` dipertahankan sebagai ID kompatibilitas untuk `grok-imagine-image-quality`.

## Body Request

**Timeout permintaan sinkron:** beberapa request gambar mengembalikan gambar final secara inline dan menunggu proses generasi selesai. Permintaan resolusi tinggi atau kualitas tinggi dapat memakan waktu hampir satu menit atau lebih, jadi atur timeout HTTP client Anda minimal `120s`. Jika respons pembuatan berisi `status: "pending"`, `task_id`, atau `poll_url`, ikuti `poll_url` yang dikembalikan.

<ParamField body="model" type="string" required>
  Model yang digunakan (misalnya `gpt-image-2`, `flux-pro`, `qwen-image-plus`, atau `nano-banana-pro`). Gunakan `GET /v1/models?recommended_for=image` untuk daftar rekomendasi terbaru.
</ParamField>

<ParamField body="prompt" type="string" required>
  Deskripsi teks untuk gambar yang diinginkan.
</ParamField>

<ParamField body="image_url" type="string">
  URL HTTPS publik gambar referensi untuk image-to-image. Untuk request Nano Banana dengan gambar referensi, set `operation` ke `image-to-image`; `nano-banana-pro` dapat menyertakan `resolution`, sedangkan `nano-banana-edit` sebaiknya menghilangkannya.
</ParamField>

<ParamField body="image_urls" type="string[]">
  URL HTTPS publik untuk gambar referensi. Gunakan untuk satu atau beberapa gambar referensi dalam request JSON. Endpoint ini tidak mendukung `file_id` dan `images[]`.
</ParamField>

<ParamField body="reference_image_urls" type="string[]">
  URL gambar referensi tambahan khusus model untuk provider yang membedakan gambar input utama dan referensi.
</ParamField>

<ParamField body="image" type="file">
  File gambar referensi multipart untuk image-to-image. Gunakan saat gambar sumber bersifat privat atau membutuhkan header. Ini berbeda dari `file_id` /v1/files; endpoint ini tidak menerima `file_id`.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Jumlah gambar yang dibuat (1-10, tergantung model).
</ParamField>

<ParamField body="size" type="string" default="1024x1024">
  Ukuran gambar. Gunakan untuk keluarga gambar bergaya OpenAI dan model lain yang menerima ukuran piksel presisi.

  Untuk `gpt-image-2`, `size` menerima `auto` atau `WIDTHxHEIGHT`. Dimensi kustom harus berupa kelipatan 16 pada kedua sisi, sisi terpanjang maksimal `3840px`, rasio sisi panjang/sisi pendek maksimal `3:1`, dan total piksel harus berada antara `655,360` dan `8,294,400`. `aspect_ratio` dan `resolution` saat ini bukan bagian dari detail model TokenLab untuk `gpt-image-2`.

  Untuk keluarga gambar Google Gemini, `size` diperlakukan sebagai alias kompatibilitas yang dipetakan ke detail model `aspect_ratio` model dan, bila didukung, `resolution`. Untuk model tersebut, sebaiknya kirim `aspect_ratio` secara langsung.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Pemilih rasio aspek yang bergantung pada model.

  Nilai umum untuk keluarga gambar Google mencakup `1:1`, `16:9`, `9:16`, `3:2`, dan `2:3`.
</ParamField>

<ParamField body="resolution" type="string">
  Pemilih resolusi output yang bergantung pada model.

  Didukung pada `gemini-3.1-flash-image` dan `gemini-3-pro-image` untuk text-to-image dan image-edit, pada `nano-banana-pro` untuk text-to-image dan image-to-image, serta pada `nano-banana-2` hanya untuk text-to-image. Nilai tipikal adalah `1k`, `2k`, dan `4k`. Jangan kirim parameter ini ke keluarga gambar Gemini yang hanya menerima rasio kecuali modelnya mendokumentasikannya secara eksplisit. Untuk model gambar xAI Grok Imagine, gunakan `1k` atau `2k`.
</ParamField>

<ParamField body="quality" type="string" default="standard">
  Kualitas gambar. Model GPT Image seperti `gpt-image-2` memakai `auto`, `low`, `medium`, atau `high`. Keluarga gambar lain dapat memakai nilai khusus provider; periksa metadata model sebelum mengirim nilai non-default.
</ParamField>

<ParamField body="response_format" type="string" default="url">
  Format respons: `url` atau `b64_json`. Default-nya `url`.

  Untuk `gpt-image-2` melalui Azure Official atau layanan yang kompatibel dengan Azure, TokenLab menerima hasil gambar sebagai `b64_json`. Untuk request `url`, TokenLab mengunggah setiap gambar ke CDN lalu mengembalikan `data[].url`. Jika CDN tidak tersedia atau upload gagal, request gagal dan tidak diubah menjadi respons Base64. Untuk `b64_json`, Base64 mentah dikembalikan.
</ParamField>

<ParamField body="async" type="boolean" default="false">
  Setel ke `true` dengan `gpt-image-2` atau model gambar resmi FLUX/BFL untuk membuat task terlebih dahulu. Task gambar async yang selesai mengembalikan URL apa pun `response_format` yang diminta; gunakan request sinkron jika membutuhkan `b64_json`.
</ParamField>

<ParamField body="style" type="string">
  Selector style opsional. Kirim hanya jika model yang dipilih mendokumentasikannya secara eksplisit; hilangkan untuk `gpt-image-2` kecuali metadata model menyatakan sebaliknya.
</ParamField>

<ParamField body="user" type="string">
  Identifier unik untuk end-user.
</ParamField>

## Respons

### Respons Sinkron

<ResponseField name="created" type="integer">
  Unix timestamp saat pembuatan.
</ResponseField>

<ResponseField name="data" type="array">
  Array gambar yang dihasilkan.

  Setiap object berisi:

  * `url` (string): URL gambar yang dihasilkan
  * `b64_json` (string): Gambar terenkripsi Base64 (jika diminta)
  * `revised_prompt` (string): Revisi prompt opsional jika model yang dipilih mengembalikannya
</ResponseField>

### Respons Task Async

Setel `async: true` dengan `gpt-image-2` atau model gambar resmi FLUX/BFL untuk membuat task alih-alih menunggu gambar final di request pembuatan. Respons berisi `status: "pending"`, `task_id`, dan `poll_url`. Poll `/v1/tasks/{task_id}` hingga task menjadi `completed` atau `failed`.

Task gambar async hanya mengembalikan URL gambar final. Jika membutuhkan data gambar mentah `b64_json`, gunakan request sinkron.

Saat task dibuat, biaya estimasi dapat dicadangkan. Task yang selesai ditagih berdasarkan penggunaan aktual; task yang gagal atau timeout akan melepas atau mengembalikan cadangan biaya.

<ResponseField name="created" type="integer">
  Timestamp Unix saat dibuat.
</ResponseField>

<ResponseField name="task_id" type="string">
  Pengenal tugas unik untuk polling.
</ResponseField>

<ResponseField name="status" type="string">
  Status awal: `pending`.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL relatif untuk polling hasil, misalnya `/v1/tasks/{id}`.
</ResponseField>

<ResponseField name="data" type="array">
  Kosong saat tugas masih pending. Tugas gambar yang selesai mengembalikan URL gambar yang dihasilkan di `data[].url`.
</ResponseField>

Saat Anda menerima `status: "pending"`, gunakan `poll_url` atau `GET /v1/tasks/{task_id}` untuk mengambil hasil.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image",
      "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "n": 1
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

  response = client.images.generate(
      model="gemini-3-pro-image",
      prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
      aspect_ratio="16:9",
      resolution="2k",
      n=1
  )

  print(response.data[0].url)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.images.generate({
    model: 'gemini-3-pro-image',
    prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
    aspect_ratio: '16:9',
    resolution: '2k',
    n: 1
  });

  console.log(response.data[0].url);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/images/generations');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'gemini-3-pro-image',
          'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
          'aspect_ratio' => '16:9',
          'resolution' => '2k',
          'n' => 1
      ])
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  echo $data['data'][0]['url'];
  ```

  Contoh keluarga gambar yang hanya menerima rasio: untuk `gemini-2.5-flash-image`, `nano-banana`, atau `nano-banana-edit`, kirim `aspect_ratio` tetapi jangan kirim `resolution`:

  ```json theme={null}
  {
    "model": "gemini-2.5-flash-image",
    "prompt": "A clean editorial product shot of a citrus soda can",
    "aspect_ratio": "16:9"
  }
  ```

  Contoh Nano Banana Pro dengan gambar referensi: kirim request ke `/v1/images/generations`, bukan `/v1/images/edits`. `resolution` bersifat opsional dan dapat diisi `1k`, `2k`, atau `4k`:

  ```json theme={null}
  {
    "model": "nano-banana-pro",
    "prompt": "Create a clean cinematic character image based on the reference images",
    "operation": "image-to-image",
    "image_urls": ["https://example.com/reference-1.png"],
    "aspect_ratio": "1:1",
    "resolution": "2k"
  }
  ```

  Untuk gambar sumber privat atau lokal, unggah langsung dengan multipart. Jangan kirim `file_id` ke `/v1/images/generations`:

  ```bash theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
    -H "Authorization: Bearer sk-your-api-key" \
    -F "model=nano-banana-pro" \
    -F "prompt=Create a clean cinematic character image based on this reference" \
    -F "operation=image-to-image" \
    -F "image=@reference.png" \
    -F "aspect_ratio=1:1" \
    -F "resolution=2k"
  ```
</RequestExample>

<ResponseExample>
  ```json Respons Sinkron theme={null}
  {
    "created": 1706000000,
    "data": [
      {
        "url": "https://...",
        "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
      }
    ]
  }
  ```

  ```json Respons Asinkron theme={null}
  {
    "created": 1706000000,
    "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "data": []
  }
  ```
</ResponseExample>

## Model Tersedia

Ini adalah contoh model saat ini, bukan katalog tetap. Gunakan `GET /v1/models?recommended_for=image` atau halaman Models untuk ketersediaan dan harga terbaru.

| Model                | Tipe                      | Fitur                                                       |
| -------------------- | ------------------------- | ----------------------------------------------------------- |
| `gpt-image-2`        | Inline atau berbasis task | Model GPT Image berbasis harga token, ukuran fleksibel      |
| `flux-pro`           | Sering berbasis task      | Fotorealistik, kualitas tinggi                              |
| `qwen-image-plus`    | Sering berbasis task      | Rendering teks dan kepatuhan prompt yang kuat               |
| `nano-banana-pro`    | Sering berbasis task      | Workflow gambar referensi dan output resolusi tinggi        |
| `grok-imagine-image` | Sering berbasis task      | Generasi gambar xAI dengan pilihan rasio aspek dan resolusi |
| `ideogram-v3`        | Sering berbasis task      | Rendering teks yang kuat                                    |

Jangan hard-code model sebagai selalu sinkron atau selalu asinkron. Jika response create mengembalikan `status: "pending"`, ikuti `poll_url` dan polling sampai selesai.

## Menangani Respons Berbasis Task

Untuk model gambar, selalu cek apakah respons berisi `status: "pending"`: