Panduan media
Pembuatan gambar
Buat atau edit gambar dan tangani file yang sudah selesai atau tugas asinkron
TokenLab mendukung text-to-image, image-to-image, dan pengeditan gambar. Parameter berbeda-beda tergantung modelnya, jadi periksa kolom permintaan model yang dipilih sebelum mengirim permintaan.
Pilih endpoint
| Apa yang Anda butuhkan | Endpoint | Gunakan saat | Bukan untuk |
|---|---|---|---|
| Text-to-image | POST /v1/images/generations | Pengguna memulai hanya dengan teks | Mengedit file GPT Image yang sudah ada |
| Image-to-image | POST /v1/images/generations | Model menerima operation: "image-to-image" dan URL gambar | Model yang memerlukan input edit multipart |
| Edit gambar | POST /v1/images/edits | Model edit yang didukung mengubah gambar yang sudah ada | Pembuatan referensi gaya Nano Banana |
| Variasi | POST /v1/images/variations | Integrasi yang sudah ada menggunakan API variasi | Fitur gambar referensi baru |
| Status | GET /v1/tasks/{id} | Respons pembuatan mengembalikan task_id, status: "pending", atau poll_url | Respons pembuatan sudah berisi data[] akhir |
Selalu kirim model; API gambar tidak memilih model default untuk Anda.
Pilih model
Temukan model gambar saat ini dengan:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
-H "Authorization: Bearer sk-your-api-key"Buka detail model yang dipilih untuk mengonfirmasi:
- Operasi yang didukung, seperti
text-to-image,image-to-image, atauimage-edit. - Endpoint permintaan yang diharapkan oleh model.
- Cara mengirim referensi:
image_url,image_urls,reference_image_urls, multipartimage, atau JSONimages[]. - Apakah model menerima
size,aspect_ratio,resolution,quality,background,output_format, atauresponse_format.
Kolom khusus model
- Permintaan gaya
gpt-image-2menggunakansize,quality, dan kolom edit seperti OpenAI. Untuk pembuatan dan pengeditan dengan model ini,backgroundmenerimaautoatauopaque;transparenttidak didukung. Hilangkan kolom opsional untuk menggunakan default otomatis. - Keluarga gambar Gemini dan Nano Banana biasanya menggunakan
aspect_ratio; hanya kirimresolutionjika detail model menampilkannya. Pada model dengan tingkatan resolusi,sizesebesar1K,2K, atau4Kdikirim sebagairesolution; tingkatan yang berbeda dariresolutionakan ditolak. - Image-to-image Nano Banana ditempatkan pada
/v1/images/generationsdenganoperation: "image-to-image"dan URL gambar referensi. /v1/images/generationstidak menerimaimages[]ataufile_idtingkat atas; itu adalah bentuk alur edit.- Referensi gambar jarak jauh harus berupa URL
httpatauhttpspublik. Jangan mengirim URL jaringan pribadi, kredensial yang disematkan, fragmen URL, atau URL bertanda tangan yang mungkin kedaluwarsa sebelum pemrosesan dimulai.
Contoh text-to-image
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
"size": "1024x1024",
"response_format": "url"
}'Contoh gambar referensi
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"operation": "image-to-image",
"prompt": "Keep the product shape, change the background to a bright studio setup",
"image_urls": ["https://example.com/input/product.png"],
"aspect_ratio": "1:1"
}'Dapatkan gambar
Respons gambar bisa bersifat sinkron atau asinkron:
- Respons sinkron mengembalikan
data[]akhir denganurlataub64_json. - Respons asinkron mengembalikan
id,task_id,status, dan biasanyapoll_url. Kirim"async": truepada model yang mendukung eksekusi asinkron publik untuk mendapatkan tugas alih-alih menunggu gambar. - Untuk memeriksa tugas asinkron, panggil
GET /v1/tasks/{id}denganidatautask_idyang dikembalikan. - Gunakan permintaan sinkron saat Anda memerlukan
b64_json; hasil gambar asinkron menggunakan URL.
URL hasil gambar adalah URL hasil media TokenLab yang tetap valid selama 30 hari. media_retention.items melaporkan status penyimpanan setiap item dan expires_at; respons dapat menghilangkan media_retention jika status penyimpanan tidak diketahui tepat waktu, dan URL tersebut tetap berfungsi. Hasil Base64 inline berada di luar retensi salinan URL ini. Menyimpan gambar secara manual ke Media Library akan memberikannya siklus hidup yang terpisah. Lihat Retensi data.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Simpan URL gambar, ID tugas, model, serta ID pengguna/pekerjaan Anda sendiri yang dikembalikan. Jangan terus melakukan polling setelah status terminal tercapai.
Sebelum peluncuran
- Validasi input pengguna sebelum memanggil TokenLab: panjang prompt, jumlah gambar, keterjangkauan URL, dan jenis file.
- Atur timeout HTTP cukup tinggi untuk permintaan resolusi tinggi yang sinkron. Gunakan
async: truedi mana model mendukungnya untuk pekerjaan yang lama. - Simpan
request_id,task_id,poll_url, model, endpoint, dan nama kolom yang dikirim. - Saat permintaan gambar mengembalikan tugas,
Idempotency-Keymembuat permintaan pembuatan aman untuk dicoba kembali: setelah timeout klien, kirim permintaan yang sama dengan kunci yang sama untuk mendapatkan tugas tersebut. Untuk permintaan yang mengembalikan gambar secara langsung, percobaan ulang dengan kunci yang sama dapat mengembalikan status tugas alih-alih gambar, atau409denganidempotent_response_not_replayable. Tanpa kunci, periksa apakah tugas telah dibuat sebelum Anda mencoba kembali. - Gunakan Usage dan
billing_transaction_iduntuk penagihan akhir.
Kesalahan umum
| Gejala | Penyebab yang mungkin | Perbaikan |
|---|---|---|
400 dengan param: "model" | Model eksplisit tidak ada | Kueri /v1/models?recommended_for=image dan kirim model |
| Kolom tidak didukung | Kolom tidak didokumentasikan untuk model tersebut | Hapus kolom atau pilih model/endpoint yang mendokumentasikannya |
Tidak ada b64_json pada hasil asinkron | Tugas gambar asinkron mengembalikan hasil berbasis URL | Gunakan mode sinkron untuk output base64 |
| Gambar referensi ditolak | Endpoint salah atau URL pribadi/kedaluwarsa | Sesuaikan dengan bentuk referensi yang didokumentasikan model dan gunakan URL yang dapat dijangkau |
Referensi API
| Topik | Referensi |
|---|---|
| Buat Gambar | Buat Gambar |
| Edit Gambar | Edit Gambar |
| Buat Variasi Gambar | Buat Variasi Gambar |
| Dapatkan Status Gambar | Dapatkan Status Gambar |
| Dapatkan Status Tugas | Dapatkan Status Tugas |