Cara Menggunakan Seedream 5.0 Pro Image API

Anda bisa membuat Seedream 5.0 Pro bekerja dengan satu permintaan POST, satu kunci API, dan satu langkah tindak lanjut: kirim job, dapatkan task_id, lalu periksa status sampai gambar selesai. Jika Anda melewatkan langkah kedua itu, Anda tidak akan mendapatkan file akhir.

Berikut versi singkatnya:

• Saya mengirim permintaan ke https://api.apimart.ai/v1/images/generations
• Saya menambahkan Authorization: Bearer YOUR_API_KEY
• Saya menyetel model ke doubao-seedream-5-0-pro
• Saya menyertakan prompt, size, dan n
• Saya menggunakan teks-ke-gambar untuk ide gambar baru
• Saya menggunakan gambar-ke-gambar ketika saya ingin output tetap lebih dekat ke satu atau lebih gambar referensi
• Saya menyimpan URL gambar dengan cepat, karena kadaluarsa setelah 24 jam
• Saya menggunakan job async untuk output lambat seperti gambar 3K, yang bisa memakan sekitar 35 hingga 50 detik
• Saya mengawasi biaya, karena harga sekitar $0.0320 per gambar

Hal utama yang akan saya ingat: simpan kunci di server, kirim n sebagai angka, dan gunakan polling atau webhook untuk job yang lebih panjang.

Beberapa detail lebih penting dari kelihatannya. Misalnya, 401 sering berarti kunci hilang atau format Bearer salah. 403 sering berarti kunci bekerja, tetapi akun tidak bisa menggunakan model atau saldonya rendah. Dan jika saya menggunakan output Base64, saya perlu menambahkan sendiri prefiks data:image/...;base64, sebelum menampilkannya di browser.

Perbandingan singkat

Singkatnya: panduan ini menunjukkan bagaimana saya akan menyiapkan auth, membangun body permintaan, memilih antara T2I dan I2I, menangani job async, dan menyimpan hasil tanpa kehilangan file atau membuang pengeluaran.

2. Siapkan Akses API dan Autentikasi

2.1 Buat Akun APIMart Anda dan Buat Kunci API

Buka situs web APIMart dan daftar akun baru ^[8]. Kemudian buka API Key Management Page di dasbor Anda dan buat kunci API ^[1][5].

Salin kunci itu segera dan simpan di sisi server. Secret manager atau variabel lingkungan adalah tempat teraman untuknya.

Jangan pernah menaruh kunci API Anda di kode frontend atau repo publik. Jika seseorang mendapatkan kunci itu, mereka bisa menggunakan akun Anda. Di Node.js, simpan dengan process.env.API_KEY. Di lingkungan shell, gunakan export API_KEY="your-key-here" ^[1][6].

Sebelum Anda membangun alur permintaan penuh, kirim permintaan POST kecil untuk memastikan akses bekerja ^[1][2]. Jika Anda mendapatkan respons 200 OK, kunci dan izin Anda sudah diatur dengan benar.

Setelah itu, Anda bisa melanjutkan ke field permintaan, termasuk model dan prompt.

2.2 Setel Base URL dan Header Autentikasi Bearer

Setelah Anda memilih mode T2I atau I2I dan kunci Anda siap, Anda perlu menyiapkan autentikasi sebelum permintaan gambar apa pun bekerja. Kirim header ini dengan setiap permintaan:

Prefiks Bearer penting. Tinggalkan, dan permintaan akan gagal ^[2][5]. Gunakan juga tepat satu spasi setelah Bearer.

Kode status HTTP membantu Anda mengenali masalah auth dengan cepat ^[1][10]. Error 401 Unauthorized biasanya berarti kunci hilang, tidak valid, atau prefiks Bearer tidak disertakan ^[1][10]. Error 403 Forbidden biasanya berarti kunci itu sendiri valid, tetapi akun tidak memiliki akses model atau saldo yang cukup ^[1][10].

Cara yang baik untuk memeriksa ini adalah menguji dengan cURL terlebih dahulu. Jika cURL bekerja tetapi aplikasi Anda tidak, bug-nya kemungkinan ada di kode permintaan aplikasi Anda ^[2][6].

Dengan auth diatur, langkah berikutnya adalah membangun body permintaan gambar.

3. Bangun Permintaan Gambar Seedream 5.0 Pro

3.1 Field Wajib: Model, Prompt, Size, dan Jumlah Gambar

Dengan auth diatur, langkah berikutnya adalah membangun body JSON.

Body permintaan yang valid butuh empat field: model, prompt, size, dan n.

Untuk Seedream 5.0 Pro, setel model ke doubao-seedream-5-0-pro ^[1]. Field prompt menerima deskripsi bahasa alami dan mendukung hingga 5,000 karakter ^[2]. Field size mengontrol dimensi output atau rasio aspek. Nilai umum meliputi 1024x1024, 2K, dan rasio aspek seperti 1:1 atau 16:9 ^[1][2]. Field n menetapkan berapa banyak gambar yang akan dibuat, biasanya dari 1 hingga 15 ^[1][6].

Satu detail kecil bisa menjebak orang: n harus berupa integer, bukan string. Jika Anda mengirim "1" alih-alih 1, API mengembalikan error validasi ^[1][5].

3.2 Field Opsional: Gambar Referensi, Pencarian Web, dan Job Async

image_urls adalah field utama untuk mode gambar-ke-gambar. Gunakan untuk mengirim hingga 14 gambar referensi sebagai URL atau Base64 data URI. Setiap gambar harus di bawah 10 MB dan menggunakan rasio aspek antara 1:3 dan 3:1 ^[1]. Jika Anda menggunakan Base64, sertakan prefiks Data URI penuh - data:image/jpeg;base64, - atau permintaan akan gagal ^[1][5].

web_search bisa membantu dengan prompt faktual atau real-time, seperti acara terkini atau logo merek ^[4][7]. Untuk kebanyakan pembuatan gambar standar, Anda tidak akan membutuhkannya.

Untuk job async atau batch, callback_url menerima endpoint HTTPS publik di mana APIMart akan mem-POST payload penyelesaian tugas ^[2].

3.3 Contoh Panggilan API dalam cURL dan JavaScript

Berikut permintaan cURL minimal yang berfungsi untuk satu gambar 1024×1024:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

Dan berikut permintaan yang sama dalam Node.js dengan fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Jaga permintaan ini di sisi server. Jangan pernah mengekspos kunci API Anda dalam kode sisi klien.

Setelah Anda mengirim permintaan, langkah berikutnya adalah mengurai payload respons.

4. Tangani Respons dan Jalankan Alur Kerja Gambar Umum

4.1 Urai URL Gambar, Output Base64, dan Objek Error

Setelah permintaan selesai, bentuk respons tetap sama baik Anda mengirim satu gambar maupun beberapa.

Respons yang berhasil mengembalikan objek JSON dengan empat field tingkat atas: model, created (timestamp Unix), data (array objek gambar), dan usage ^[6]. Setiap gambar yang dihasilkan muncul di dalam data sebagai string url atau b64_json, berdasarkan format yang Anda minta. Jika n lebih besar dari 1, data menyertakan satu objek gambar per output.

Jika Anda menggunakan format URL, setiap item di data menyimpan tautan gambar di .url. Anda bisa menyetel nilai itu sebagai src gambar di browser. Satu jebakan: ini adalah tautan bertanda tangan sementara, dan kadaluarsa setelah 24 jam ^[6]. Untuk aplikasi produksi, unduh file segera dan simpan ke penyimpanan permanen alih-alih menyimpan URL.

Jika Anda menggunakan format Base64, setiap item di data menyimpan string mentah di .b64_json. Ia tidak menyertakan prefiks data:image/...;base64, ^[6]. Untuk menampilkannya di browser, tambahkan prefiks itu sendiri:

img.src = "data:image/png;base64", + data.b64_json;

Untuk menyimpannya sebagai file di Python, dekode terlebih dahulu:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

Jika permintaan gagal, respons menyertakan field code dan message ^[6]. 400 biasanya berarti ukuran yang tidak didukung atau parameter tidak valid. 401 berarti permintaan tidak terautentikasi. Catat kedua field setiap kali. Dalam kebanyakan kasus, message menunjuk langsung ke masalahnya.

Gunakan field-field ini untuk memutuskan apakah Anda harus menyimpan, mendekode, atau menampilkan output.

---

4.2 Tiga Jenis Gambar Umum yang Bisa Anda Buat dengan Seedream 5.0 Pro

Ketiga pola ini selaras dengan mode yang dibahas sebelumnya: hanya-teks, referensi-tunggal, dan multi-referensi.

• Visual pemasaran hanya-teks. Untuk aset kampanye yang butuh lebih banyak detail, gunakan resolusi 3K (size: "3K") dan tulis prompt terstruktur yang dimulai dengan subjek dan tata letak adegan, lalu tambahkan detail pencahayaan, gaya, dan warna. Pembuatan 3K memakan 35–50 detik, jadi async biasanya lebih cocok.

• Variasi produk referensi-tunggal. Gunakan mode gambar-ke-gambar dengan satu gambar referensi di image_urls dan prompt terfokus yang hanya mengubah yang Anda inginkan, seperti latar belakang, pencahayaan, atau tekstur permukaan. Ini menjaga bentuk dan detail produk lebih dekat ke gambar sumber daripada membuat dari awal. Untuk variasi 3K, gunakan callback_url, karena setiap tugas bisa memakan sekitar 40 detik ^[2].

• Konsistensi multi-referensi untuk konsistensi merek dan karakter. Jika Anda butuh karakter atau elemen bermerek tetap konsisten di beberapa gambar, kirim hingga 14 gambar referensi melalui image_urls ^[2][3]. Setel sequential_image_generation ke auto saat membuat beberapa output dari input referensi sehingga Anda menjaga variasi tanpa kehilangan konsistensi visual ^[5][4]. Ini bekerja baik untuk seri konten sosial, katalog produk, dan lembar karakter.

Pola-pola ini cenderung bekerja paling baik ketika format respons cocok dengan alur kerja.

---

4.3 Permintaan Sync vs. Async dan Respons URL vs. Base64

Gunakan perbandingan ini untuk memilih format respons sebelum Anda mengirim integrasi.

Untuk job async, tunggu sekitar 20 detik sebelum polling pertama, lalu periksa setiap 3 detik ^[2]. Di produksi, callback_url adalah opsi yang lebih baik karena menghindari loop polling dan memangkas overhead server ^[2][9].

Gunakan respons URL secara default. Beralih ke Base64 hanya ketika Anda butuh data gambar dalam respons yang sama.

5. Daftar Periksa Akhir untuk Integrasi Seedream 5.0 Pro yang Andal

Setelah panggilan uji pertama Anda yang berhasil, jalankan daftar periksa ini sebelum Anda menskala ke produksi. Ini cara sederhana untuk menangkap masalah yang cenderung menghentikan peluncuran total.

Autentikasi dan keamanan kunci. Simpan kunci API Anda dalam variabel lingkungan atau secret manager. Kirim permintaan dari backend Anda dengan Authorization: Bearer <your_key>.

Validasi parameter permintaan Anda sebelum mengirimnya. Periksa string model, kirim n sebagai integer, jaga image_urls dalam batas yang diizinkan, dan pastikan size yang diminta didukung.

Untuk job yang memakan lebih lama dari preview cepat, sesuaikan jalur pengiriman Anda. Setel timeout berdasarkan ukuran output, dan gunakan callback_url untuk job berjalan lama alih-alih polling.

Setelah gambar siap, perlakukan pengiriman sebagai masalah penyimpanan, bukan sekadar masalah respons. Jika Anda menggunakan output URL, unduh file segera dan pindahkan ke penyimpanan permanen. URL bertanda tangan kadaluarsa setelah 24 jam ^[6].

Uji prompt pada batch kecil sebelum menskala. Seedream 5.0 ditagih sekitar $0.0320 per gambar yang dihasilkan ^[2]. Catat createTime, completeTime, dan costTime agar Anda bisa mengawasi latensi dan pengeluaran ^[2].

Pertanyaan Umum

Bagaimana saya memeriksa job gambar async setelah mendapatkan task_id?

Gunakan task_id yang dikembalikan untuk memeriksa status job gambar async Anda.

Kirim permintaan GET ke endpoint status yang diberikan API. Di banyak API, itu terlihat seperti:

• /v1/tasks/{task_id}
• atau endpoint gaya-query dengan task_id

Untuk penggunaan produksi, tunggu sekitar 20 detik setelah membuat tugas sebelum pemeriksaan status pertama Anda. Setelah itu, poll setiap 3 detik sampai status job menunjukkan completed.

Setelah job selesai, baca payload respons dan tarik URL gambar darinya.

Kapan saya harus menggunakan output URL alih-alih Base64?

Gunakan output URL dalam kebanyakan kasus. Ia memberi Anda tautan langsung ke gambar yang dihasilkan, yang mempermudah menyambungkannya ke aplikasi web atau mobile.

Gunakan Base64 hanya ketika pengaturan Anda membutuhkan data gambar inline di body respons, seperti pemrosesan berbasis memori atau ketika Anda ingin melewatkan permintaan kedua. Untuk aset 4K resolusi tinggi, output URL biasanya lebih efisien.

Apa cara terbaik untuk menghindari kehilangan gambar yang dihasilkan?

Simpan gambar yang dihasilkan dengan segera, karena tautan gambar API hanya valid selama 72 jam.

API Seedream 5.0 Pro berjalan secara asinkron. Itu berarti Anda tidak akan mendapatkan URL gambar langsung. Pertama, Anda mendapatkan sebuah task ID. Kemudian Anda menggunakan task ID itu untuk mengambil URL gambar.

Untuk menghindari kehilangan output, Anda punya dua opsi utama:

• Poll dengan task ID sampai gambar siap
• Gunakan callback URL agar sistem Anda bisa menerima, menangkap, dan menyimpan gambar sebelum tautan kadaluarsa

Jika Anda menunggu terlalu lama, URL akan kadaluarsa dan gambar mungkin hilang.