> ## 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 Muse Image Ext

> Buat satu gambar WebP per permintaan dari teks atau hingga 9 gambar referensi.

> [!NOTE]
>
> API ini bersifat asinkron. Simpan ID tugas setelah pengiriman, lalu gunakan `GET /v1/tasks/{task_id}` untuk memeriksa status dan hasil. Dalam respons pengiriman default, ID ada di `data[0].task_id`.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: <unique-operation-key>' \
  --data '{
    "model": "muse-image-ext",
    "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
    "aspect_ratio": "1:1",
    "n": 1
  }'
```

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

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
        "Idempotency-Key": "<unique-operation-key>"
    },
    json={
        "model": "muse-image-ext",
        "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
        "aspect_ratio": "1:1",
        "n": 1
    }
)
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",
    Accept: "application/json",
    "Idempotency-Key": "<unique-operation-key>"
  },
  body: JSON.stringify({
    "model": "muse-image-ext",
    "prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
    "aspect_ratio": "1:1",
    "n": 1
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

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

## Header permintaan

**Authorization** `string` *required*

Gunakan APIMart API Key dalam format `Bearer <token>`. Pengiriman dan polling memerlukan autentikasi dengan identitas pengguna yang sama.

**Idempotency-Key** `string`

Sangat disarankan. Gunakan kunci baru untuk setiap pembuatan yang terpisah (1–191 karakter ASCII yang terlihat; UUID disarankan). Ganti `<unique-operation-key>` pada contoh. Setelah timeout pengiriman atau kegagalan jaringan, ulangi dengan endpoint, isi, versi respons, dan kunci yang sama. Setelah menerima ID tugas, cukup periksa tugas tersebut.

## Parameter permintaan

**model** `string` *required*

Nilai tetap: `muse-image-ext`.

**prompt** `string` *required*

Deskripsi teks tentang konten yang ingin dibuat. Mendukung bahasa Mandarin dan Inggris. Tidak boleh kosong setelah spasi di awal dan akhir dihapus. Tetap wajib meskipun menggunakan gambar referensi.

**image\_urls** `string[]`

Maksimal 9 input gambar referensi yang tidak kosong. Mendukung URL publik, Data URI (seperti `data:image/png;base64,...`), atau base64 mentah. Hilangkan atau kirim `[]` untuk pembuatan dari teks saja. PNG, JPEG, dan WebP disarankan. URL harus dapat diakses langsung oleh server tanpa cookie login browser.

Ukuran asli gabungan semua gambar referensi tidak boleh melebihi **11 MiB (11.534.336 byte)**. Ini batas total, bukan per gambar. base64 menambah ukuran isi permintaan. Jangan kirim URL `blob:`, jalur file lokal, atau objek `File`.

**aspect\_ratio** `string`

Mendukung tujuh rasio di bawah. Jika dihilangkan, pembuatan dari teks memakai `1:1`; dengan referensi, hasil mengikuti komposisi referensi. Rasio eksplisit diutamakan. Untuk pemilihan otomatis, hilangkan bidang ini; jangan kirim `"auto"`.

`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`

**size** `string`

Bidang kompatibilitas yang menerima tujuh rasio di atas atau `auto`, bukan ukuran piksel seperti `1024x1024`. Hanya mengirim `size: "auto"` sama dengan tidak menentukan rasio. Utamakan `aspect_ratio`. Jika keduanya valid, `aspect_ratio` diutamakan, tetapi setiap bidang divalidasi terpisah: rasio valid tidak membatalkan kesalahan `size`.

**n** `integer` (default: 1)

Hanya satu hasil per permintaan. Hanya angka `1` yang diterima. Nilai eksplisit `0`, negatif, atau lebih dari `1` menghasilkan kesalahan.

> [!NOTE]
>
> Mengembalikan URL WebP. Dimensi gambar ditentukan model; ukuran piksel atau tingkat 1K / 2K / 4K tidak dapat dipilih. Jangan kirim `resolution` yang tidak kosong atau bidang durasi apa pun.

### Parameter opsional lainnya

**webhook** `string`

URL dasar backend untuk notifikasi tugas. Platform menghapus garis miring terakhir lalu menambahkan `/callback`: `https://your-backend.example/muse` menjadi `https://your-backend.example/muse/callback`. Hilangkan jika hanya menggunakan polling.

**language** `string`

Mengatur bahasa pesan kesalahan Webhook, bukan konten yang dibuat. Nilai: `zh`, `en`, `ja`, `ko`, `ru`, `fr`, `de`, `id`, `pt`, `es`. Tag regional seperti `zh-CN` tidak diterima. Untuk polling, kirim bahasa secara terpisah sebagai parameter kueri GET.

## Pembuatan dengan gambar referensi

```json theme={null}
{
  "model": "muse-image-ext",
  "prompt": "Keep the cup from the reference image and place it on a wooden cafe table in warm natural light",
  "image_urls": [
    "https://your-cdn.example/cup.png"
  ],
  "n": 1
}
```

Ganti URL contoh dengan URL gambar yang dapat diakses. Contoh ini menghilangkan rasio agar mengikuti komposisi referensi; tambahkan `aspect_ratio` untuk rasio tetap. Tambahkan referensi lain ke `image_urls`, maksimal 9 gambar total.

## Respons pengiriman

Respons default adalah HTTP `200`, dengan `data` berupa array. `submitted` berarti tugas diterima, bukan selesai. Simpan `data[0].task_id`, lalu periksa tugas.

> **Versi respons opsional: 2026-07-27**
>
> Dengan header `X-APIMart-Response-Version: 2026-07-27`, pengiriman mengembalikan HTTP `202`. Baca ID dari `data.id` dan jalur polling dari `data.poll_url`.
>
> ```json theme={null}
> {
>   "code": 202,
>   "request_id": "req_example",
>   "data": {
>     "id": "task_01K...",
>     "object": "generation.task",
>     "type": "image",
>     "status": "pending",
>     "progress": 0,
>     "poll_url": "/v1/tasks/task_01K..."
>   }
> }
> ```
>
> Versi ini tidak mengubah struktur respons GET. Setelah menambahkan header ini, jangan tetap membaca respons pengiriman melalui `data[0].task_id`.

## Memeriksa status dan hasil tugas

Gunakan ID lengkap dari respons pengiriman dan identitas pengguna yang sama. `language` bersifat opsional untuk bahasa pesan kesalahan. Lihat seluruh bidang di [Status tugas](https://docs.apimart.ai/id/api-reference/tasks/status.md).

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

Polling disarankan setiap 5 detik, tanpa kueri bersamaan untuk tugas yang sama. Timeout klien atau penghentian polling tidak membatalkan tugas server. Simpan ID lalu lanjutkan GET nanti; jangan otomatis mengirim pembuatan baru.

| `data.status` | Tindakan |
| - | - |
| `pending` / `processing` | Dalam antrean atau diproses; lanjutkan polling. |
| `completed` | Pembuatan berhasil; hentikan polling dan baca URL hasil. |
| `failed` | Pembuatan gagal; hentikan polling dan baca `data.error.message`. |
| `unknown` / … | Status belum pasti. Simpan ID dan ulangi kueri dalam batas tertentu; jangan anggap berhasil atau otomatis membuat ulang. |

Gunakan `data.status` untuk menentukan penyelesaian. HTTP `200` atau `progress: 100` saja tidak berarti pembuatan berhasil. `polling_error` selama pemrosesan bukan kegagalan terminal.

Contoh respons kueri yang selesai (URL hasil hanya placeholder):

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

Dalam respons kueri, `data` berupa objek dan `url` berupa array string. Hasil pertama ada di `data.result.images[0].url[0]`. Jika ada, `expires_at` adalah waktu kedaluwarsa dalam detik Unix; simpan file yang dibutuhkan sebelum kedaluwarsa. `actual_time` adalah waktu pemrosesan tugas, bukan durasi pemutaran video.

## Batasan dan penanganan kesalahan

Video referensi, audio referensi, mask, kontrol frame awal/akhir, perpanjangan, dan remix tidak didukung. `quality` tidak berpengaruh. Hilangkan `seed`, `negative_prompt`, `width`, `height`, `response_format`, dan `output_format` karena bukan parameter pembuatan model ini. `async: false` tidak mengaktifkan pembuatan sinkron, dan `stream` tidak menyediakan aliran SSE pembuatan.

| HTTP / `error.code` | Tindakan |
| - | - |
| `400 / invalid_request_error` | Periksa prompt, jumlah referensi, rasio, jumlah hasil, dan spesifikasi output tetap. |
| `409 / idempotency_in_progress` | Tunggu sesuai `Retry-After`, lalu ulangi permintaan asli dengan kunci idempotensi yang sama. |
| `409 / idempotency_key_reused` | Kunci yang sama dipakai untuk permintaan berbeda. Perbaiki pengelolaan kunci; gunakan kunci baru untuk setiap pembuatan terpisah. |
| `409 / idempotency_result_indeterminate` | Hentikan pengiriman ulang otomatis dan simpan kunci serta informasi tugas untuk pemeriksaan. |
| `429` | Tunggu sesuai `Retry-After` sebelum mencoba kembali. |

Tugas gagal tetap dapat mengembalikan HTTP `200`; periksa `data.status` dan `data.error.message`. Kesalahan jaringan atau `5xx` saat pengiriman dapat terjadi setelah penerimaan, jadi jangan langsung mengirim ulang dengan kunci baru.


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