Langsung ke konten utama
Saat mengirim tugas generasi asinkron seperti video / gambar / audio, Anda dapat menyertakan URL callback. Setelah tugas selesai (berhasil atau gagal), kami akan secara aktif mem-POST hasilnya ke URL Anda, sehingga Anda tidak perlu terus-menerus melakukan polling.

​
Mulai cepat

Saat mengirim tugas, tambahkan field webhook ke body permintaan: 
curl -X POST https://domain-akses-anda/v1/images/generations \
  -H "Authorization: Bearer API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com"
  }'
Setelah tugas selesai, kami akan mengirim permintaan POST ke URL Anda + /callback.
Endpoint tugas asinkron lainnya (video, audio, dll.) bekerja dengan cara yang sama — cukup tambahkan field webhook ke body permintaan.

​
Aturan URL

webhook yang Anda berikan adalah URL dasar (base), dan kami otomatis menambahkan /callback di belakangnya:
webhook AndaKe mana kami benar-benar mem-POST
https://your-server.comhttps://your-server.com/callback
https://your-server.com/apihttps://your-server.com/api/callback
https://your-server.com/api/https://your-server.com/api/callback
Jadi server Anda perlu menyediakan endpoint yang menerima POST .../callback.

​
Apa yang akan Anda terima

Konten yang dikirim persis sama dengan yang dikembalikan oleh endpoint “Dapatkan Status Tugas” — Anda dapat memprosesnya dengan logika parsing yang sama. 
{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}
Untuk tugas video, hasilnya ada di result.videos, dan untuk audio di result.audios.
Kami hanya mengirim ketika tugas mencapai status final (completed / failed); kami tidak mengirim saat sedang diproses.

​
Percobaan ulang dan deduplikasi (penting)

  • Percobaan ulang: Jika server Anda tidak mengembalikan 2xx dalam sekitar 10 detik, atau mengembalikan 5xx, kami akan otomatis mencoba lagi, hingga 3 kali, dengan interval sekitar 10 dtk, 30 dtk, dan 60 dtk. Jika ketiganya gagal, kami menyerah (dalam sekitar 2 menit).
  • Tidak dicoba ulang: Jika endpoint Anda mengembalikan 4xx (dianggap URL / permintaan bermasalah), kami langsung menyerah tanpa mencoba lagi.
  • Deduplikasi: Biasanya satu tugas hanya dikirim sekali. Namun dalam kasus ekstrem (mis. restart di sisi kami setelah pengiriman tetapi sebelum konfirmasi) Anda mungkin menerima pengiriman ganda. Pastikan untuk melakukan deduplikasi secara idempoten berdasarkan id (task_id) untuk menghindari pemrosesan ganda.
Rekomendasi untuk endpoint penerima Anda:
1

Kembalikan 2xx secepat mungkin

Terima dan masukkan ke antrean dulu, lalu proses secara asinkron — jangan biarkan kami menunggu Anda selesai memproses.
2

Deduplikasi berdasarkan id

Gunakan id (task_id) sebagai kunci idempotensi untuk menghindari pemrosesan ganda.
3

Konfigurasi dan verifikasi tanda tangan

Di produksi, verifikasi asal permintaan callback dan tolak permintaan palsu.

​
Persyaratan untuk URL callback

Demi keamanan, URL callback harus memenuhi:
PersyaratanKeterangan
Dapat diakses publikTidak boleh berupa alamat internal / lokal (mis. 127.0.0.1, 10.x, 192.168.x akan ditolak)
Protokolhttp atau https (disarankan https)
PortGunakan port standar (80 / 443); port non-standar mungkin diblokir
DomainTidak boleh menunjuk ke domain layanan kami sendiri
URL yang tidak memenuhi persyaratan ini akan langsung dibuang (tidak dikirim, tidak dicoba ulang).

​
FAQ

Periksa satu per satu:
  1. Apakah tugas benar-benar selesai? Periksa detail tugas — apakah status sudah completed / failed (tidak dikirim saat diproses)?
  2. Apakah URL Anda dapat diakses publik? Bisakah kami menjangkau /callback Anda?
  3. Apakah port-nya standar (80 / 443)? Port non-standar mungkin diblokir oleh kebijakan keamanan.
  4. Apakah /callback Anda mengembalikan 2xx tepat waktu? Mengembalikan 4xx akan langsung ditinggalkan.
  5. Apakah Anda menggunakan https? Apakah sertifikatnya valid?
Beberapa model menghasilkan banyak gambar sekaligus, jadi images[].url bisa berupa array — cukup perlakukan sebagai array.
Jika result menyertakan expires_at (timestamp Unix), itu menunjukkan waktu kedaluwarsa tautan — segera transfer/simpan.
Tidak. Kami hanya mengirim sekali, saat tugas akhirnya berhasil atau gagal.

​
Contoh penerima minimal

Python
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("Callback tugas diterima:", data["id"], data["status"])
        # TODO: deduplikasi berdasarkan id, verifikasi tanda tangan, lalu proses
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()
Kembalikan 200 secepat mungkin, dan jalankan logika pemrosesan Anda secara asinkron di latar belakang.