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 butuhkanEndpointGunakan saatBukan untuk
Text-to-imagePOST /v1/images/generationsPengguna memulai hanya dengan teksMengedit file GPT Image yang sudah ada
Image-to-imagePOST /v1/images/generationsModel menerima operation: "image-to-image" dan URL gambarModel yang memerlukan input edit multipart
Edit gambarPOST /v1/images/editsModel edit yang didukung mengubah gambar yang sudah adaPembuatan referensi gaya Nano Banana
VariasiPOST /v1/images/variationsIntegrasi yang sudah ada menggunakan API variasiFitur gambar referensi baru
StatusGET /v1/tasks/{id}Respons pembuatan mengembalikan task_id, status: "pending", atau poll_urlRespons 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, atau image-edit.
  • Endpoint permintaan yang diharapkan oleh model.
  • Cara mengirim referensi: image_url, image_urls, reference_image_urls, multipart image, atau JSON images[].
  • Apakah model menerima size, aspect_ratio, resolution, quality, background, output_format, atau response_format.

Kolom khusus model

  • Permintaan gaya gpt-image-2 menggunakan size, quality, dan kolom edit seperti OpenAI. Untuk pembuatan dan pengeditan dengan model ini, background menerima auto atau opaque; transparent tidak didukung. Hilangkan kolom opsional untuk menggunakan default otomatis.
  • Keluarga gambar Gemini dan Nano Banana biasanya menggunakan aspect_ratio; hanya kirim resolution jika detail model menampilkannya. Pada model dengan tingkatan resolusi, size sebesar 1K, 2K, atau 4K dikirim sebagai resolution; tingkatan yang berbeda dari resolution akan ditolak.
  • Image-to-image Nano Banana ditempatkan pada /v1/images/generations dengan operation: "image-to-image" dan URL gambar referensi.
  • /v1/images/generations tidak menerima images[] atau file_id tingkat atas; itu adalah bentuk alur edit.
  • Referensi gambar jarak jauh harus berupa URL http atau https publik. 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 dengan url atau b64_json.
  • Respons asinkron mengembalikan id, task_id, status, dan biasanya poll_url. Kirim "async": true pada model yang mendukung eksekusi asinkron publik untuk mendapatkan tugas alih-alih menunggu gambar.
  • Untuk memeriksa tugas asinkron, panggil GET /v1/tasks/{id} dengan id atau task_id yang 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: true di 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-Key membuat 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, atau 409 dengan idempotent_response_not_replayable. Tanpa kunci, periksa apakah tugas telah dibuat sebelum Anda mencoba kembali.
  • Gunakan Usage dan billing_transaction_id untuk penagihan akhir.

Kesalahan umum

GejalaPenyebab yang mungkinPerbaikan
400 dengan param: "model"Model eksplisit tidak adaKueri /v1/models?recommended_for=image dan kirim model
Kolom tidak didukungKolom tidak didokumentasikan untuk model tersebutHapus kolom atau pilih model/endpoint yang mendokumentasikannya
Tidak ada b64_json pada hasil asinkronTugas gambar asinkron mengembalikan hasil berbasis URLGunakan mode sinkron untuk output base64
Gambar referensi ditolakEndpoint salah atau URL pribadi/kedaluwarsaSesuaikan dengan bentuk referensi yang didokumentasikan model dan gunakan URL yang dapat dijangkau

Referensi API

TopikReferensi
Buat GambarBuat Gambar
Edit GambarEdit Gambar
Buat Variasi GambarBuat Variasi Gambar
Dapatkan Status GambarDapatkan Status Gambar
Dapatkan Status TugasDapatkan Status Tugas

Di halaman ini