API Pembuatan Gambar Asinkron: Job, Polling, Webhook, dan Percobaan Ulang

API pembuatan gambar asinkron memungkinkan Anda mengirimkan permintaan pembuatan, segera mendapatkan pengenal job (job identifier), dan mengambil gambar yang sudah selesai di lain waktu alih-alih membiarkan koneksi HTTP tetap terbuka. Tutorial ini membahas siklus hidup job, kapan harus menggunakan polling versus webhook, dan cara merancang retry agar job yang lambat atau gagal tidak merusak pengalaman produk Anda.

Poin Penting

• Pembuatan gambar berbasis job, bukan request-response, karena latensi pembuatan (beberapa detik hingga puluhan detik) tidak dapat diandalkan untuk ditahan pada koneksi sinkron.
• Polling lebih sederhana untuk dibangun dan di-debug; webhook mengurangi latensi dan volume permintaan tetapi memerlukan endpoint publik, verifikasi tanda tangan, dan penanganan idempotensi untuk pengiriman ganda.
• Logika retry harus membedakan antara kegagalan pengiriman, job yang macet, dan pengiriman webhook yang terlewat; masing-masing memerlukan jalur pemulihan yang berbeda.
• Nama endpoint, nama field, dan bentuk payload webhook yang tepat berbeda-beda tergantung penyedia dan permukaan API TokenLab sendiri. Selalu konfirmasikan spesifikasi terkini di docs.tokenlab.sh sebelum melakukan rilis.

Mengapa API Pembuatan Gambar Bersifat Asinkron

API penyelesaian teks sering kali dapat mengembalikan respons pada koneksi yang sama karena pembuatan token cukup cepat untuk di-stream. Model pembuatan gambar, baik berbasis difusi maupun autoregresif, biasanya membutuhkan waktu lebih lama dan memiliki latensi yang lebih bervariasi tergantung pada resolusi, pilihan model, dan kedalaman antrean. Menahan permintaan HTTP sinkron terbuka selama puluhan detik sangat rentan: timeout klien, batas idle load balancer, dan gangguan jaringan seluler semuanya meningkatkan kemungkinan kehilangan hasil yang sudah selesai yang telah Anda bayar untuk dibuat.

Pola standar yang digunakan di seluruh penyedia pembuatan gambar adalah model job: Anda mengirimkan permintaan dan menerima pengenal job serta status awal (biasanya seperti queued atau processing). Anda kemudian melakukan polling pada endpoint status atau menerima notifikasi webhook saat job mencapai status terminal, dan Anda mengambil URL gambar akhir atau data biner dalam panggilan terpisah.

TokenLab menyediakan akses ke berbagai model gambar, termasuk keluarga Nano Banana 2, Nano Banana Pro, dan Nano Banana 2 Lite, GPT Image 2, Reve 2.0, dan MAI-Image-2.5, melalui satu permukaan API. Lihat direktori model gambar untuk daftar saat ini dan panduan tugas pembuatan gambar asinkron untuk perilaku endpoint job khusus TokenLab. Pola umum di bawah ini berlaku terlepas dari model dasar mana yang Anda panggil, tetapi nama field dan nilai status yang tepat didokumentasikan di docs.tokenlab.sh dan harus diverifikasi di sana alih-alih diasumsikan dari artikel ini.

Siklus Hidup Job: Kirim, Polling, Ambil

Secara konseptual, job gambar asinkron memiliki tiga tahap:

1. Kirim (Submit): POST prompt dan parameter, terima ID job dan status awal.
2. Cek status: lakukan polling pada endpoint GET menggunakan ID job, atau tunggu event webhook.
3. Ambil output (Retrieve): setelah status terminal (berhasil atau gagal), ambil URL gambar atau detail error.

Berikut adalah pola polling ilustratif dalam Python. Anggap jalur endpoint dan nama field sebagai placeholder; konfirmasikan bentuk endpoint job TokenLab saat ini dalam dokumentasi API sebelum menggunakannya dalam produksi.

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # verifikasi base URL saat ini di docs.tokenlab.sh
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit_image_job(prompt, model="nano-banana-2"):
    resp = requests.post(
        f"{API_BASE}/images/jobs",
        headers=HEADERS,
        json={"prompt": prompt, "model": model, "idempotency_key": generate_key()},
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

def poll_job(job_id, max_wait_seconds=120, interval=2, backoff=1.5):
    waited = 0
    while waited < max_wait_seconds:
        resp = requests.get(f"{API_BASE}/images/jobs/{job_id}", headers=HEADERS)
        resp.raise_for_status()
        data = resp.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        waited += interval
        interval = min(interval * backoff, 15)
    raise TimeoutError(f"Job {job_id} did not complete within {max_wait_seconds}s")

job_id = submit_image_job("a studio product shot on white background")
result = poll_job(job_id)
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
else:
    print("job failed:", result.get("error"))

idempotency_key dalam panggilan submit sangat penting: jika terjadi error jaringan setelah job dibuat tetapi sebelum klien Anda menerima ID job, melakukan retry pada panggilan submit dengan kunci yang sama akan mengembalikan job yang ada alih-alih membuat pembuatan duplikat. Konfirmasikan apakah dan bagaimana endpoint job TokenLab mendukung idempotency key di dokumentasi saat ini, karena ini adalah pola yang umum namun tidak universal di seluruh penyedia.

Polling vs. Webhook: Tradeoff

Kedua pendekatan tersebut valid; pilihan yang tepat bergantung pada pola lalu lintas dan infrastruktur Anda.

Polling lebih sederhana untuk diimplementasikan dan diuji secara lokal, tidak memerlukan endpoint publik, dan berfungsi dengan baik untuk beban kerja bervolume rendah atau batch di mana latensi beberapa detik tambahan tidak menjadi masalah. Kekurangannya adalah batas bawah latensi yang sama dengan interval polling Anda, dan volume permintaan yang tidak perlu jika Anda melakukan polling terlalu agresif pada job yang berjalan lama.

Webhook mendorong notifikasi ke server Anda saat job berubah status, yang menurunkan latensi dan mengurangi panggilan pengecekan status yang sia-sia. Biayanya bersifat operasional: Anda memerlukan endpoint HTTPS yang dapat dijangkau publik, verifikasi tanda tangan untuk mengonfirmasi bahwa payload benar-benar berasal dari penyedia, dan penanganan untuk pengiriman ganda atau tidak berurutan.

Dokumen referensi event webhook OpenAI menjelaskan bentuk umum pola ini untuk operasi asinkron: endpoint Anda menerima event dengan tipe dan pengenal objek, dan praktik yang disarankan adalah memperlakukan payload webhook sebagai notifikasi untuk mengambil status sumber daya saat ini melalui API, alih-alih memercayai body webhook sebagai sumber kebenaran akhir. Pola pull-after-push tersebut layak diadopsi terlepas dari penyedia gambar mana yang Anda integrasikan, karena melindungi Anda jika payload webhook terpotong, tertunda, atau dikirim lebih dari sekali.

Mengimplementasikan Webhook dengan Aman

Jika Anda memilih webhook untuk penyelesaian job gambar, praktik berikut mengurangi kemungkinan kegagalan senyap:

• Verifikasi tanda tangan pada setiap permintaan webhook yang masuk sebelum memprosesnya. Tolak apa pun yang tidak cocok, dan catat penolakan secara terpisah dari lalu lintas normal agar Anda dapat segera menemukan secret yang salah konfigurasi.
• Respons cepat, proses nanti. Akui webhook dengan status 200 segera setelah Anda memvalidasinya, lalu serahkan pekerjaan sebenarnya (mengambil gambar, menulis ke penyimpanan, memberi tahu pengguna Anda) ke job atau antrean latar belakang. Penyedia biasanya melakukan retry pengiriman webhook jika mereka tidak mendapatkan respons 2xx tepat waktu, yang dapat menyebabkan pemrosesan ganda jika handler Anda lambat dan sinkron.
• Deduplikasi berdasarkan ID job. Simpan ID job yang telah diproses (atau hash dari event) agar pengiriman yang di-retry tidak menghasilkan notifikasi ulang atau memproses ulang penulisan file.
• Ambil ulang sumber daya menggunakan ID job dari payload webhook alih-alih memercayai URL output yang disematkan sebagai yang final, konsisten dengan pola pull-after-push yang dijelaskan di atas.

Sketsa handler minimal:

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # gunakan penyimpanan nyata dalam produksi

@app.route("/webhooks/image-jobs", methods=["POST"])
def handle_webhook():
    if not verify_signature(request):
        abort(401)

    event = request.get_json()
    job_id = event.get("job_id") or event.get("data", {}).get("id")
    if job_id in processed_job_ids:
        return "", 200  # sudah ditangani, akui dan lewati

    enqueue_background_task("fetch_and_store_image", job_id)
    processed_job_ids.add(job_id)
    return "", 200

Verifikasi nama event webhook yang tepat, struktur payload, dan header tanda tangan yang digunakan untuk penyelesaian job gambar terhadap dokumentasi penyedia saat ini dan, secara terpisah, terhadap dukungan webhook TokenLab sendiri seperti yang dijelaskan di docs.tokenlab.sh, karena detail ini spesifik untuk penyedia dan dapat berubah.

Desain Retry: Tiga Kelas Kegagalan

Job gambar asinkron gagal dalam tiga cara berbeda, dan masing-masing memerlukan penanganannya sendiri:

1. Kegagalan pengiriman: POST untuk membuat job mengembalikan 4xx atau 5xx. Untuk 5xx dan error jaringan, lakukan retry dengan exponential backoff dan jitter, gunakan kembali idempotency key yang sama agar Anda tidak membuat job duplikat. Untuk error 4xx (prompt buruk, model tidak valid, kuota terlampaui), melakukan retry tanpa mengubah permintaan hanya akan gagal lagi; tampilkan error tersebut kepada pemanggil.
2. Job macet: job tetap dalam status non-terminal jauh melewati waktu pembuatan yang diharapkan. Tetapkan ambang batas tunggu maksimum per model (waktu pembuatan bervariasi menurut model dan resolusi) dan perlakukan job yang melampauinya sebagai gagal untuk tujuan aplikasi Anda, meskipun penyedia belum secara resmi menandainya sebagai gagal. Catat ini secara terpisah, karena tingkat job macet yang meningkat sering kali menandakan insiden di sisi penyedia.
3. Pengiriman webhook terlewat: endpoint Anda down, atau pengiriman gagal, dan tidak ada event yang pernah tiba. Inilah sebabnya mengapa fallback polling layak dipertahankan bahkan dalam desain yang mengutamakan webhook: penyapuan berkala yang memeriksa status job apa pun yang lebih lama dari beberapa menit tanpa status terminal akan menangkap job yang webhook-nya gagal tiba secara senyap.

Daftar Periksa Keputusan

Gunakan daftar periksa ini saat memutuskan cara menghubungkan penyelesaian job untuk fitur pembuatan gambar.

Skenario	Pendekatan yang disarankan	Mengapa
Volume rendah, alat internal, atau skrip batch	Polling	Paling sederhana untuk dibangun; tidak perlu endpoint publik
Fitur yang menghadap pengguna di mana latensi penting	Webhook, dengan penyapuan fallback polling	Latensi lebih rendah; fallback menangkap pengiriman yang terlewat
Volume job tinggi (ribuan/hari)	Webhook	Menghindari volume permintaan pengecekan status yang berlebihan
Tidak ada kemampuan untuk mengekspos endpoint HTTPS publik	Polling	Webhook memerlukan penerima yang dapat dijangkau
Perlu pencegahan duplikat yang ketat	Idempotency key saat submit, dedupe pada ID job saat diterima	Melindungi dari pengiriman yang di-retry dan pengiriman webhook ganda
Beberapa model gambar dalam satu pipeline	Normalisasi status job dan penanganan error di layer Anda sendiri	Penyedia dasar (lihat perbandingan model gambar) tidak berbagi taksonomi status yang identik

Batasan

Artikel ini menjelaskan pola umum untuk API job gambar asinkron dan tidak menegaskan jalur endpoint, nama field, nilai timeout, atau nama event webhook yang tepat untuk TokenLab atau untuk penyedia model dasar tertentu di luar apa yang dikutip di atas. Kosakata status job, header retry-after, dan skema tanda tangan webhook bervariasi antar penyedia dan dapat berubah seiring waktu; perlakukan kode dalam artikel ini sebagai ilustrasi, bukan kode produksi copy-paste, dan konfirmasikan bentuk permintaan dan respons saat ini di docs.tokenlab.sh sebelum melakukan rilis. Artikel ini tidak mencakup harga, batas tarif, atau jaminan throughput untuk model tertentu.

FAQ

Haruskah saya selalu menggunakan webhook alih-alih polling? Tidak. Webhook mengurangi latensi dan volume permintaan dengan biaya operasional yang lebih tinggi. Untuk kasus penggunaan volume rendah atau internal, polling sering kali menjadi pilihan yang lebih sederhana dan sama andalnya. Banyak sistem produksi menggunakan webhook sebagai jalur utama dengan penyapuan polling berkala sebagai fallback.

Bagaimana cara menghindari pembuatan gambar duplikat saat retry? Gunakan idempotency key pada permintaan pengiriman job sehingga POST yang di-retry setelah kegagalan jaringan mengembalikan job yang ada alih-alih membuat yang baru. Konfirmasikan apakah endpoint pembuatan job penyedia Anda mendukung ini sebelum mengandalkannya.

Apa yang terjadi jika endpoint webhook saya down saat job selesai? Perilaku bergantung pada penyedia; beberapa melakukan retry pengiriman untuk jangka waktu tertentu, yang lain tidak menjamin pengiriman ulang. Penyapuan polling berkala untuk job yang lebih lama dari beberapa menit tanpa status terminal adalah perlindungan praktis terlepas dari kebijakan retry penyedia.

Jika Anda sedang membangun fitur pembuatan gambar dan ingin membandingkan akses berbasis job di berbagai model dalam satu API, tinjau direktori model gambar dan panduan tugas pembuatan gambar asinkron, lalu Mulai dengan dokumentasi API TokenLab untuk mengonfirmasi detail endpoint dan webhook saat ini untuk build Anda.