API Edit Gambar GPT di TokenLab: Endpoint dan Format Input Gambar yang Benar

Pengeditan gambar adalah salah satu bagian yang paling menuntut dari antarmuka produk AI: pengguna mengunggah foto, mendeskripsikan perubahan, dan mengharapkan hasilnya. Pengeditan yang menggunakan beberapa gambar sumber, kanvas besar, atau prompt yang lebih berat memerlukan waktu lebih lama daripada yang dapat ditangani secara nyaman oleh panggilan HTTP sinkron pada umumnya. Panduan ini membahas endpoint TokenLab yang benar, dua bentuk input gambar yang didukung, pengeditan multi-gambar, serta jalur asinkron untuk permintaan yang lambat.

Endpoint

Pengeditan gambar berada di POST /v1/images/edits — perhatikan bentuk jamak edits. (Kesalahan umum adalah menuliskan /images/edit, yang bukan merupakan jalur terdokumentasi.)

Endpoint ini mendukung dua bentuk permintaan:

• Alur unggah multipart/form-data yang kompatibel dengan OpenAI.
• Permintaan JSON yang menyediakan image_url, image_urls, atau referensi resmi images[] untuk kelompok image-to-image yang didukung.

Bidang permintaan dan respons lengkap didokumentasikan dalam referensi API Edit Image.

Apa yang diterima gpt-image-2 di sini

• Unggahan image multipart.
• image_url atau image_urls JSON.
• Referensi images[] resmi, di mana setiap objek berisi tepat satu dari image_url atau file_id.
• Hingga 16 gambar sumber per permintaan.

Beberapa batasan yang perlu diketahui sebelum Anda menulis kode:

• Pengeditan gpt-image-2 tidak menerima resolution; gunakan size untuk dimensi output (antara auto atau WIDTHxHEIGHT, dengan dimensi kelipatan 16, sisi terpanjang maksimal 3840px, rasio sisi panjang/pendek maksimal 3:1).
• background menerima auto atau opaque; transparent tidak didukung.
• input_fidelity bukan bagian dari bidang yang didukung untuk gpt-image-2; mengirimkannya akan mengembalikan 400 unsupported_parameter.
• Untuk permintaan JSON, sediakan tepat satu dari image_url, image_urls, atau images. Setiap objek images[] harus berisi tepat satu dari image_url atau file_id. Nilai untuk file_id harus dibuat melalui /v1/files terlebih dahulu.
• Permintaan gambar referensi Nano Banana berada di /v1/images/generations dengan operation: "image-to-image" dan image_urls — bukan di /v1/images/edits.

Unggahan multipart vs referensi gambar JSON

Keduanya berfungsi untuk gpt-image-2. Pilih yang sesuai dengan lokasi bita gambar Anda berada saat ini.

Multipart — gunakan ini ketika aplikasi memegang file tersebut, baik dari unggahan pengguna maupun aset yang dihasilkan. Ulangi bidang image untuk mengirim beberapa sumber. File harus berformat PNG, JPEG, atau WebP, masing-masing maksimal 50 MiB.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

URL gambar JSON — gunakan ini ketika gambar sudah berada di URL publik, atau Anda telah membuatnya dalam permintaan TokenLab sebelumnya dan sudah memiliki URL-nya.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

URL jarak jauh harus berupa http/https publik, tanpa kredensial atau fragmen yang disematkan, dan tidak boleh mengarah ke localhost, privat, atau rentang IP yang dicadangkan. TokenLab mengambil bita tersebut dan menyerahkannya ke model sebagai bagian image multipart. Batas per gambar adalah 50 MiB; batas agregat untuk gambar yang diambil melalui URL dalam satu permintaan adalah 200 MiB; batas waktu pengambilan (fetch timeout) adalah 30 detik; hingga 3 pengalihan (redirect) akan diikuti.

Pengeditan multi-gambar dan polling asinkron

Pengeditan multi-gambar adalah kasus paling jelas untuk penggunaan async: true. Mengirimkan beberapa gambar dengan rangkaian instruksi yang kompleks melalui panggilan sinkron berarti membiarkan koneksi tetap terbuka selama yang dibutuhkan oleh model. Tetapkan async: true pada gpt-image-2 (dan pada model edit FLUX/BFL resmi) untuk menerima tugas (task) sebagai gantinya:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Lakukan polling pada poll_url yang dikembalikan, atau beralih ke GET /v1/tasks/{task_id}. Statusnya adalah pending, processing, completed, dan failed. Tugas gambar yang selesai akan mengembalikan data[].url. Memeriksa setiap 3–5 detik sudah cukup; berhentilah pada status terminal daripada terus melakukan polling.

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Tugas edit asinkron mengembalikan URL gambar akhir terlepas dari response_format yang diminta. Jika Anda memerlukan b64_json mentah, gunakan permintaan sinkron.

Penagihan dapat mencadangkan estimasi jumlah saat tugas dibuat; tugas yang selesai ditagihkan berdasarkan penggunaan aktual, dan tugas yang gagal atau mengalami batas waktu habis (timeout) akan melepaskan atau mengembalikan dana reservasi tersebut. Lihat Tugas asinkron dan polling untuk siklus proses lengkap, dan Get Image Status untuk bidang respons.

Kapan harus menggunakan masing-masing mode

Gunakan async: true saat:

• Anda mengirimkan beberapa gambar sumber dalam satu permintaan.
• Prompt atau rangkaian instruksi Anda cukup kompleks sehingga waktu pembuatan tidak dapat diprediksi.
• Anda menjalankan pengeditan dalam pekerjaan latar belakang (background job), antrean, atau proses batch alih-alih permintaan langsung yang dihadapi pengguna.

Tetap gunakan sinkron saat:

• Anda melakukan pengeditan satu gambar dengan prompt singkat.
• Klien Anda lebih memilih untuk gagal dengan cepat (fail fast) daripada melakukan polling.

Untuk panggilan sinkron, atur batas waktu (timeout) klien HTTP Anda ke setidaknya 120s; permintaan resolusi tinggi atau kualitas tinggi dapat memakan waktu hampir satu menit atau lebih. Jika respons pembuatan masih kembali dengan status: "pending", task_id, atau poll_url, beralihlah ke alur polling yang dikembalikan.

Kesalahan input yang perlu diantisipasi

Kegagalan pengambilan gambar jarak jauh dikembalikan sebagai kesalahan input sebelum pembuatan dimulai. URL yang tidak dapat dijangkau, batas waktu habis (timeouts), respons 403/404, host privat atau internal, kredensial atau fragmen di dalam URL, konten bukan gambar, format yang tidak didukung, dan pelanggaran batas ukuran akan mengembalikan 400 atau 413 serta mengidentifikasi image_url atau image_urls[n] yang bermasalah. Untuk aset privat atau yang dilindungi header, unggah file image multipart secara langsung, atau buat referensi /v1/files dan teruskan sebagai images[].file_id.

Model edit gambar xAI Grok Imagine (misalnya grok-imagine-image dan grok-imagine-image-quality) menggunakan bidang input yang sama tetapi membatasi gambar sumber hingga 3; lebih dari itu akan mengembalikan 400 too_many_images.

Daftar periksa integrasi

• Targetkan POST /v1/images/edits dan kirim model secara eksplisit.
• Pilih unggahan multipart atau referensi JSON berdasarkan lokasi gambar Anda saat ini.
• Kirim tepat satu dari image_url, image_urls, atau images[] dalam permintaan JSON; setiap entri images[] memiliki tepat satu dari image_url atau file_id.
• Gunakan async: true untuk pengeditan multi-gambar atau pengeditan berat; lakukan polling pada poll_url yang dikembalikan hingga tugas mencapai completed atau failed.
• Atur batas waktu (timeout) klien setidaknya 120 detik untuk permintaan sinkron dan tangani respons pending dengan mengikuti poll_url.
• Jika terjadi timeout pada klien, periksa apakah tugas telah dibuat sebelum mencoba kembali permintaan pembuatan untuk menghindari tagihan ganda.

Mulai sekarang

Jalankan kueri GET /v1/models?recommended_for=image untuk melihat model gambar saat ini, lalu buka halaman detail model untuk memastikan operasi dan bidang permintaan yang didukung sebelum mengirimkan permintaan. Buat API key dari konsol untuk menguji endpoint edit dengan gambar Anda sendiri.