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

# Hy-Image-3.5 Preview Pembuatan Gambar

> Teks-ke-gambar, hingga 5 gambar referensi, keluaran 1K / 2K / 4K atau dimensi piksel presisi. Satu gambar per permintaan.

<Info>
  Endpoint ini asinkron. Setelah pengiriman, ambil ID dari `data[0].task_id` dan gunakan [Kueri Tugas](/id/api-reference/tasks/status) untuk status dan gambar. Lakukan polling setiap 3–5 detik; batas waktu total klien disarankan 5 menit. Berhenti pada `completed` atau `failed`.
</Info>

<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": "hy-image-v3.5-preview",
      "prompt": "A golden retriever running on a beach in warm evening light",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

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

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "hy-image-v3.5-preview",
          "prompt": "A golden retriever running on a beach in warm evening light",
          "size": "16:9",
          "resolution": "2K"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "hy-image-v3.5-preview",
      prompt: "A golden retriever running on a beach in warm evening light",
      size: "16:9",
      resolution: "2K"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

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

## Header permintaan

<ParamField header="Authorization" type="string" required>
  Autentikasi Bearer: `Bearer <token>`; `<token>` adalah APIMart API Key Anda.
</ParamField>

## Parameter permintaan

<ParamField body="model" type="string" required>
  Nilai tetap: `hy-image-v3.5-preview`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Deskripsi untuk pembuatan atau pengeditan gambar. Mendukung bahasa Mandarin dan Inggris; tidak boleh kosong.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Rasio aspek keluaran atau dimensi piksel presisi.

  * Rasio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
  * Piksel presisi: misalnya `2000x1104`, sesuai batas piksel di bawah.
  * `auto` atau dihilangkan: model menentukan rasio berdasarkan prompt.

  Dengan piksel presisi, `resolution` tidak menentukan dimensi keluaran.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Tingkat resolusi: `1K`, `2K`, atau `4K`; default `1K`.

  Dengan piksel presisi, kolom ini tidak menentukan ukuran. Tetap gunakan nilai yang didukung; nilai lain mengembalikan HTTP 400.
</ParamField>

<ParamField body="width" type="integer">
  Lebar keluaran presisi dalam piksel. Wajib bersama `height`; prioritas lebih tinggi daripada `size` dan `resolution`.

  Lebar 256–8192; lebar × tinggi tidak boleh melebihi 8.294.400. Kelipatan 16 disarankan.
</ParamField>

<ParamField body="height" type="integer">
  Tinggi keluaran presisi dalam piksel. Wajib bersama `width`.

  Tinggi 256–8192; lebar × tinggi tidak boleh melebihi 8.294.400. Kelipatan 16 disarankan.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Daftar URL gambar referensi publik, maksimal 5. Hilangkan untuk teks-ke-gambar; sertakan untuk pembuatan berbasis referensi pada endpoint yang sama.

  Mendukung JPEG, PNG, WEBP. Tiap gambar disarankan di bawah 7MB. URL harus dapat diakses publik.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Konten yang tidak diinginkan dalam gambar.
</ParamField>

<ParamField body="seed" type="integer">
  Seed acak; wajib bilangan bulat nonnegatif. `0` atau dihilangkan berarti acak.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Hanya satu gambar per permintaan. Hanya `1` diterima; nilai lain mengembalikan HTTP 400.
</ParamField>

## Pemilihan dimensi

Prioritas: pasangan `width` / `height` → piksel presisi dalam `size` → rasio atau `auto` dalam `size` bersama `resolution`.

Untuk piksel presisi, lebar dan tinggi masing-masing 256–8192, dengan total maksimal 8.294.400 piksel. Kelipatan 16 disarankan untuk keduanya.

### Contoh piksel presisi

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}
```

Anda juga dapat menghilangkan `width` dan `height` lalu mengirim `"size": "2000x1104"`.

### Contoh gambar referensi

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "Make the car in the reference image red, preserving the original background and lighting",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "blur, text watermarks",
  "seed": 42,
  "n": 1
}
```

Ganti URL contoh dengan alamat gambar publik yang sebenarnya. Untuk beberapa referensi, tambahkan URL ke `image_urls`, maksimal 5 gambar total.

## Respons pengiriman

<ResponseField name="code" type="integer">
  Kode status respons; `200` berarti berhasil.
</ResponseField>

<ResponseField name="data" type="array">
  Hasil pengiriman tugas.

  <Expandable title="Tampilkan kolom tugas">
    <ResponseField name="status" type="string">
      `submitted` berarti pengiriman berhasil, bukan gambar telah selesai dibuat.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID tugas untuk memeriksa status dan hasil.
    </ResponseField>
  </Expandable>
</ResponseField>

## Memeriksa hasil tugas

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Contoh respons berhasil (URL gambar adalah placeholder):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}
```

* `pending` / `processing`: lanjutkan polling.
* `completed`: ambil URL dari `data.result.images[0].url[0]`; `url` berupa array string.
* `failed`: hentikan polling dan baca penyebab dari `data.error.message`. Dana dikembalikan penuh. Pelanggaran prompt dan kegagalan moderasi konten juga diperlakukan sebagai kegagalan.

Gambar disimpan di CDN platform. Unduh dan simpan sebelum waktu `expires_at` pada hasil kueri.

## Penagihan

Ditagih per gambar. Lihat [Harga Model](https://apimart.ai/pricing).

* Dengan rasio aspek, biaya mengikuti tingkat `resolution`.
* Dengan piksel presisi, sisi yang lebih pendek menentukan tingkat:

| Tingkat | Sisi lebih pendek |
| - | - |
| 1K | Hingga 1024 piksel |
| 2K | 1025–2048 piksel |
| 4K | Di atas 2048 piksel |

Tugas gagal mendapat pengembalian dana penuh.

## Kesalahan parameter umum

Kasus berikut mengembalikan HTTP 400 secara sinkron, tanpa membuat tugas atau mengenakan biaya:

| Masalah | Tindakan |
| - | - |
| `prompt` kosong | Berikan prompt yang tidak kosong |
| `n` bukan `1` | Minta satu gambar setiap kali |
| `seed` negatif | Gunakan bilangan bulat nonnegatif; `0` berarti acak |
| `resolution` tidak didukung | Gunakan `1K`, `2K`, atau `4K` |
| Rasio `size` tidak didukung | Gunakan salah satu dari 10 rasio di atas atau `auto` |
| Piksel di luar batas | Lebar dan tinggi masing-masing 256–8192, total maksimal 8.294.400 piksel |
| Lebih dari 5 gambar referensi | Kurangi `image_urls` menjadi maksimal 5 gambar |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.