> ## 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 Seedream 5.5

> Buat gambar dari teks atau hingga 10 referensi, dengan latar transparan, pemisahan lapisan yang dapat diatur, dan OCR melalui API asinkron.

```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": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
}'
```

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

payload = {
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
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_example_seedream55"
    }
  ]
}
```

Kirim ke `POST /v1/images/generations`, simpan `data[0].task_id`, lalu periksa `GET /v1/tasks/{task_id}`.

## Mode

| Mode | Pengaturan | Gambar masukan | Prompt |
| - | - | - | - |
| Pembuatan gambar | Default | 0–10 | Wajib |
| Pemisahan lapisan | `layer_decomposition: true` | Tepat 1 | Opsional |

## Autentikasi

**Authorization** `string` *required*

Gunakan `Authorization: Bearer <token>`, dengan `<token>` berupa APIMart API Key Anda.

## Parameter permintaan

**model** `string` *required*

Gunakan `seedream-5-5`.

**prompt** `string`

Wajib untuk pembuatan dari teks maupun gambar. Opsional untuk pemisahan: model mengenali subjek, teks, dan latar secara otomatis. Anda juga dapat menjelaskan elemen yang ingin dipisahkan.

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

Maksimal 10 referensi untuk pembuatan, tepat 1 gambar untuk pemisahan. Mendukung URL gambar publik atau Data URI Base64 gambar. Unggah berkas lokal melalui [API unggah gambar](https://docs.apimart.ai/id/api-reference/uploads/images.md) lalu gunakan `url` hasilnya.

Gunakan URL `http(s)` yang dapat diakses publik atau `data:image/<format>;base64,…` dengan nama format huruf kecil dalam Data URI.

* Mendukung JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, dan HEIF. AVIF serta JP2 tidak didukung.
* Maksimal **30 MiB (31,457,280 byte)** dan **36 juta total piksel** per gambar. Hitung lebar × tinggi; bukan batas 6000 piksel untuk setiap sisi.
* Batas ukuran atau piksel yang terlampaui menghasilkan HTTP 400 sinkron. AVIF dan JP2 dapat membuat tugas sebelum ditolak penyedia; tugas gagal dikembalikan biayanya. Konversikan format sebelum mengirim.

Endpoint unggah gambar memiliki batas format tersendiri. Untuk format yang didukung model tetapi tidak didukung endpoint unggah, gunakan URL publik atau Data URI.

**size** `string`

Pembuatan: default `2K`, mendukung tingkat resolusi, rasio, atau ukuran piksel tepat. Pemisahan: default `auto`, hanya `1K` / `1.5K` / `2K` / `auto`.

Untuk pembuatan gambar, `size: "auto"` berarti `2K`. Rasio aspek tanpa `resolution` juga memakai `2K`. Untuk dimensi piksel tepat, hilangkan `resolution` dan gunakan bilangan bulat positif untuk lebar serta tinggi.

**resolution** `string`

Pada pembuatan, gunakan `1K` / `1.5K` / `2K` bersama rasio pada `size`. Pada pemisahan, ini adalah alias platform untuk `size`: `size` didahulukan, `resolution` dipakai hanya jika `size` tidak dikirim, dan tanpa keduanya berlaku `auto`. Nilai yang diterima: `1K` / `1.5K` / `2K` / `auto`. Rasio atau piksel ditolak secara sinkron dengan HTTP 400. Tidak mendukung `3K` / `4K`.

**background** `string`

Pembuatan: `auto` (default), `transparent`, atau `opaque`. Transparansi tersedia untuk masukan teks maupun gambar. Wajib PNG, tidak boleh bersama `output_format: "jpeg"`. Saat pemisahan, jangan kirim kolom ini, termasuk `auto`.

**output\_format** `string` (default: png)

`png` (default) atau `jpeg`. Saat pemisahan hanya mengatur gambar dasar; lapisan hasil selalu berupa PNG transparan.

**n** `integer`

Hanya `1`. Pembuatan menghasilkan satu gambar per permintaan. Atur jumlah hasil pemisahan melalui `layer_decomposition_options.max_images`.

**watermark** `boolean` (default: false)

Penanda opsional untuk menambahkan tanda air.

**optimize\_prompt\_options** `object`

Hanya menerima `{"mode":"standard"}`. Jika dihilangkan, penyedia tetap mengaktifkan default `standard`; optimasi tidak dapat dimatikan pada Seedream 5.5. Penyedia menolak `disabled` / `none` / `off` dengan HTTP 400 dan `must be one of: standard`. Platform langsung menolak `fast` dengan HTTP 400.

**layer\_decomposition** `boolean`

`true` memisahkan masukan menjadi gambar dasar dan lapisan transparan. Memerlukan tepat satu gambar dan tanpa `background`. `output_format` hanya mengatur gambar dasar.

**layer\_decomposition\_options** `object`

Hanya bersama `layer_decomposition: true`; selain itu HTTP 400.

**Parameter permintaan**

**max\_images** `integer` (default: 30)

Bilangan bulat `2`–`100`, default `30`. Batas total gambar keluaran termasuk gambar dasar, bukan jumlah yang dijamin.

**text\_recognition** `boolean` (default: false)

Boolean opsional. `true` meminta OCR dengan informasi gaya untuk lapisan teks. `text_recognition` hanya mungkin muncul untuk teks reguler yang dapat dikenali.

Saat OCR aktif, menyertakan `prompt` dapat menyebabkan hasil pengenalan teks tidak dikembalikan. Jika OCR menjadi prioritas, coba hilangkan prompt pemisahan. Hasil tetap tidak dijamin; perlakukan kolom OCR sebagai opsional.

## Format ukuran

| Format | Contoh | Aturan |
| - | - | - |
| Tingkat | `"size": "2K"` | `1K` / `1.5K` / `2K`; default `2K`. Model memilih rasio berdasarkan prompt. |
| Rasio + tingkat | `"size": "16:9", "resolution": "1.5K"` | Hanya pembuatan. Rasio tercantum di bawah; notasi `16x9` juga diterima. |
| Piksel tepat | `"size": "2048x1152"` | Hanya pembuatan. Total piksel 921.600–4.624.220; lebar/tinggi 1/16–16. |

Rasio: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `2:1`, `1:2`.

Batas berlaku pada luas piksel dan rasio. Pemisahan hanya menerima tingkat atau `auto`, bukan rasio atau ukuran piksel tepat.

### Ukuran keluaran pemisahan

* Prioritas: `size` → `resolution` → `auto`. `resolution` adalah alias platform; penyedia hanya menerima `size`. `size: "1K"` bersama `resolution: "2K"` memakai `1K`; hanya `resolution: "1.5K"` memakai `1.5K`.

* Dengan `1K` / `1.5K` / `2K`, gambar dasar dan setiap lapisan dikeluarkan pada tingkat pilihan dengan rasio masing-masing tetap terjaga. Salah satu hasil pengukuran dasar `1K` berukuran `840×1248`, dan setiap lapisan juga sekitar 1,05 juta piksel. Ini contoh hasil, bukan ukuran tetap.

* `auto` memakai ukuran asli masukan: masukan di bawah `1K` diperbesar ke `1K`, sedangkan di atas `2K` diperkecil ke `2K`.

## Contoh permintaan

### Penyuntingan dan penggabungan referensi

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "prompt": "Combine the product in the first image with the setting in the second image",
  "image_urls": ["https://example.com/product.png", "https://example.com/setting.jpg"],
  "size": "16:9",
  "resolution": "1.5K",
  "output_format": "png"
}'
```

### Pemisahan lapisan dan OCR

Permintaan ini menghasilkan maksimal 10 gambar termasuk gambar dasar. `prompt` opsional; jangan kirim `background`. Ganti URL dengan gambar yang dapat diakses.

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 10,
    "text_recognition": true
  },
  "size": "1K"
}'
```

## Memeriksa tugas

Gunakan [API status tugas](https://docs.apimart.ai/id/api-reference/tasks/status.md) setiap 3 detik selama 30 detik pertama, lalu setiap 5–10 detik. Pemisahan dapat memakan beberapa menit; server menunggu maksimal 13 menit. Simpan `task_id` dan periksa hingga status akhir tanpa mengirim ulang permintaan pembuatan.

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

Pada `data.status`, `pending` / `processing` berarti diproses dan `completed` berarti berhasil. Untuk `failed`, baca `data.error.message`; biaya dikembalikan otomatis. URL hasil ada di `data.result.images[].url[]`.

> [!WARNING]
>
> Gambar hasil disimpan selama **3 hari**; segera unduh. Catatan tugas juga hanya disimpan 3 hari, setelah itu tidak dapat diperiksa melalui `task_id`.
>
> `data.result.images[].expires_at` saat ini mengembalikan timestamp Unix dalam detik sebesar waktu tugas selesai + 24 jam. Ini adalah penanda konservatif yang lebih awal daripada penghapusan sebenarnya. Jangan gunakan untuk menghitung masa penyimpanan aktual atau hitung mundur penghapusan.

## Hasil lapisan dan OCR

Contoh ini menunjukkan struktur, bukan rekaman eksekusi model. Ukuran, koordinat, dan teks hanya ilustrasi. Metadata dapat tidak tersedia.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_seedream55",
    "status": "completed",
    "progress": 100,
    "completed": 1794302642,
    "result": {
      "images": [
        {
          "url": ["https://example.com/base.png", "https://example.com/title.png"],
          "sizes": ["840x1248", "1512x702"],
          "output_formats": ["png", "png"],
          "backgrounds": ["opaque", "transparent"],
          "expires_at": 1794389042,
          "layer_decomposition": true,
          "layers": [
            {
              "z_index": 0,
              "size": "840x1248",
              "output_format": "png",
              "background": "opaque"
            },
            {
              "z_index": 1,
              "size": "1512x702",
              "output_format": "png",
              "background": "transparent",
              "name": "Sale title",
              "description": "Printed sale title",
              "bounding_box": {
                "absolute": [84, 156, 756, 468],
                "normalized": [100, 125, 900, 375]
              },
              "text_recognition": {
                "text": "SUMMER SALE",
                "lines": [
                  {
                    "bounding_box": {
                      "absolute": [126, 156, 714, 468],
                      "normalized": [150, 125, 850, 375]
                    },
                    "runs": [
                      {
                        "text": "SUMMER SALE",
                        "style": {
                          "similar_font_family": "Arial",
                          "foreground_color": "#222222",
                          "bold": true,
                          "italic": false,
                          "underline": false,
                          "strikethrough": false,
                          "shadow": false,
                          "translucent": false
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}
```

Dalam setiap `data.result.images[]`, `url`, `sizes`, `output_formats`, `backgrounds`, dan `layers` berkorespondensi berdasarkan indeks. Array metadata dapat dihilangkan jika panjangnya tidak sama dengan `url`.

| Kolom | Keterangan |
| - | - |
| `url[]` | URL gambar. Pada mode lapisan, indeks 0 adalah gambar dasar, diikuti lapisan. Segera unduh dan simpan berkas. |
| `sizes[]` / `output_formats[]` | Ukuran dan format aktual setiap gambar. |
| `backgrounds[]` | Latar aktual: `opaque` / `transparent`. Gunakan nilai ini untuk `background: "auto"`. |
| `expires_at` | Saat ini berupa timestamp Unix sebesar waktu tugas selesai + 24 jam (86400 detik). Penanda konservatif ini bukan waktu penghapusan gambar yang sebenarnya; jangan gunakan untuk hitung mundur penghapusan. |
| `layer_decomposition` | Apakah hasil berasal dari pemisahan lapisan. |
| `layers[i].z_index` | Urutan tumpukan: gambar dasar bernilai 0; susun dengan urutan menaik. |
| `layers[i].background` | Dasar: `opaque`; lapisan hasil: `transparent`. |
| `layers[i].name` / `description` | Nama dan deskripsi lapisan opsional. |
| `layers[i].bounding_box` | `absolute`: `[left, top, right, bottom]` dalam piksel gambar dasar. `normalized`: kotak yang sama dinormalisasi ke 0–1000. Tidak ada pada gambar dasar. |
| `layers[i].text_recognition` | Mungkin ada jika OCR aktif dan teks reguler dikenali; tidak ada untuk huruf artistik, tulisan tangan, atau lapisan bukan teks. |

Koordinat absolut: `x=left`, `y=top`, `w=right-left`, `h=bottom-top`. Untuk kanvas `W × H`, konversikan koordinat ternormalisasi sebagai berikut:

```text theme={null}
x = left / 1000 * W
y = top / 1000 * H
w = (right - left) / 1000 * W
h = (bottom - top) / 1000 * H
```

Ukuran setiap berkas lapisan ditentukan sendiri pada tingkat pilihan dan dapat berbeda dari `bounding_box`. Untuk menyusun, ubah ukurannya menjadi `w × h`, lalu tempatkan di `(x, y)`. Jangan langsung memakai piksel berkas lapisan sebagai koordinat gambar dasar.

### Kolom pengenalan teks

`text_recognition` mengikuti struktur OCR model penyedia. Platform meneruskan kolom seperti `text`, `lines`, `runs`, dan `style` tanpa perubahan.

| Kolom | Keterangan |
| - | - |
| `text` | Teks lengkap lapisan, baris dipisahkan dengan `\n`. |
| `lines[].bounding_box` | Kotak baris dalam koordinat gambar dasar. |
| `lines[].runs[]` | Potongan teks dengan gaya berbeda dalam satu baris, masing-masing berisi `text` dan `style`. |
| `runs[].style.similar_font_family` | Font terdekat yang dikenali, atau `unknown`. |
| `runs[].style.foreground_color` | Warna teks dalam format `#RRGGBB`. |
| `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | Penanda gaya boolean yang diperkirakan model; dapat tidak akurat. |

OCR dan informasi font membantu tampilan, penyalinan, atau penyuntingan, tetapi dapat berbeda dari aslinya. Gambar lapisan tetap dapat digunakan tanpa OCR.

## Penagihan

Gambar keluaran dan referensi masukan ditagih terpisah. **Setiap referensi dikenakan biaya, termasuk yang pertama** serta satu gambar masukan untuk pemisahan lapisan.

* Setiap keluaran memakai jumlah piksel aktual: hingga **2,610,000** piksel termasuk batasnya memakai tarif rendah; lebih besar memakai tarif tinggi. `1K` / `1.5K` masuk tarif rendah, `2K` tarif tinggi. Dimensi tepat dihitung dari lebar × tinggi.
* Pembuatan gambar mencadangkan tarif keluaran yang dipilih ditambah jumlah referensi × harga masukan. Tanpa `size` atau dengan `auto`, cadangan memakai `2K`.
* Pemisahan mencadangkan `max_images` × tarif keluaran **ditambah biaya satu gambar masukan**. Default `max_images` adalah 30 termasuk dasar; keluaran aktual bisa lebih sedikit.
* Pemisahan memakai `size` yang berlaku, atau `resolution` jika tidak ada: `1K` / `1.5K` mencadangkan tarif rendah; `2K` / `auto` tarif tinggi. Tanpa keduanya, berlaku `auto` dengan cadangan tarif tinggi.
* Penyelesaian tagihan memakai jumlah keluaran aktual, tarif piksel setiap gambar, dan jumlah masukan; selisih dikembalikan atau ditagih. Dasar dan setiap lapisan dihitung sendiri, bukan semua mengikuti tarif yang diminta tanpa memeriksa piksel aktual. Tugas gagal mendapat pengembalian penuh.

Lihat [harga model](https://apimart.ai/pricing).

## Kesalahan parameter umum

Mencakup validasi platform dan penyedia. Baca `error.message` untuk kegagalan pengiriman dan `data.error.message` untuk kegagalan tugas asinkron.

| Cuplikan kesalahan | Solusi |
| - | - |
| `does not support optimize_prompt_options.mode=fast` | Platform mengembalikan HTTP 400 secara sinkron. Hanya `standard`; menghilangkannya juga tetap mengaktifkan optimasi. |
| `must be one of: standard` | HTTP 400 dari penyedia: `disabled` / `none` / `off` tidak didukung; optimasi tidak dapat dimatikan. |
| `only supports background auto, transparent or opaque` | Gunakan `auto`, `transparent`, atau `opaque`. |
| `cannot combine background=transparent with output_format=jpeg` | Gunakan `output_format: "png"` untuk transparansi. |
| `does not accept background when layer_decomposition=true` | Hapus `background`, termasuk `auto`, pada pemisahan. |
| `layer_decomposition_options requires layer_decomposition=true` | Kirim objek ini hanya pada mode pemisahan. |
| `layer_decomposition_options.max_images must be within [2, 100]` | `max_images`: bilangan bulat 2–100, termasuk gambar dasar. |
| `invalid layer_decomposition_options` | Gunakan bilangan bulat untuk `max_images`, bukan string atau desimal; boolean untuk `text_recognition`. |
| `with layer_decomposition=true requires exactly 1 input image` | Berikan tepat satu gambar untuk pemisahan. |
| `only supports size 1K, 1.5K, 2K or auto` | Pemisahan memakai `size` dahulu, jika tidak ada memakai `resolution`. Hanya `1K` / `1.5K` / `2K` / `auto`; rasio atau piksel menghasilkan HTTP 400 secara sinkron. |
| `` `n` must be 1 `` | Atur `n` ke `1`; pembuatan batch tidak didukung. |
| `does not support stream` / `does not support tools` | Hapus `sequential_image_generation`, `stream`, dan `tools`. |
| `supports up to 10 reference images` | Berikan maksimal 10 gambar referensi. |
| `reference image too large for seedream-5-5` | Setiap referensi maksimal 30 MiB dan 36 juta total piksel. Kompres atau ubah ukurannya. |
| `does not support size` / `requires total pixels` / `requires aspect ratio` | Periksa jumlah piksel, rasio aspek, dan notasi ukuran. 3K / 4K tidak didukung. |
| `` `prompt` parameter is required `` | Pembuatan gambar wajib memakai prompt. Hanya pemisahan lapisan yang boleh menghilangkannya. |

## Alasan kegagalan tugas

Saat `data.status` bernilai `failed`, baca `data.error.message` dan `data.error.reason`. Biaya dikembalikan otomatis. Jika `reason` tidak ada atau tidak dikenal, gunakan `message` sebagai pesan cadangan.

| `data.error.reason` | Tindakan |
| - | - |
| `content_policy_violation` | Masukan atau keluaran gagal pemeriksaan konten. Ubah prompt atau gambar. |
| `invalid_parameter` / `unsupported_option` | Parameter atau kombinasi tidak didukung. Sesuaikan permintaan. |
| `invalid_media` | Gambar rusak atau format tidak didukung. Periksa dan konversikan. |
| `media_unreachable` | URL gambar tidak dapat diakses. Periksa akses publik atau unggah ulang. |
| `generation_timeout` | Pembuatan melewati batas waktu. Coba lagi nanti. |
| `service_unavailable` | Layanan sementara sibuk. Coba lagi nanti. |
| `delivery_failed` / `internal_error` / `unknown_error` | Kesalahan pengiriman atau internal platform. Ikuti pesan yang dikembalikan dan coba lagi nanti. |


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