Callback Penyelesaian Tugas (Webhook)

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. Untuk tugas pembuatan video dan gambar, Anda juga dapat menggunakan language untuk memilih bahasa pesan kegagalan.

Mulai cepat

Saat mengirim tugas, tambahkan webhook di tingkat teratas body permintaan. Untuk menerjemahkan pesan kegagalan, tambahkan juga language:

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",
    "language": "id"
  }'

Setelah tugas selesai, kami akan mengirim permintaan POST ke URL Anda + /callback.

Endpoint tugas asinkron lainnya (video, audio, dll.) menggunakan webhook dengan cara yang sama. language saat ini berlaku untuk POST /v1/videos/generations dan POST /v1/images/generations; kedua field harus berada di tingkat teratas body permintaan.

Pilih bahasa pesan kesalahan

language adalah parameter string opsional yang hanya memengaruhi error.message dalam callback kegagalan. ID tugas, status, progres, biaya, dan URL hasil tidak berubah berdasarkan bahasa. Jika tidak diisi, pesan kesalahan asli dari penyedia upstream atau platform akan dikembalikan.

Bahasa	Nilai	Bahasa	Nilai
Inggris	`en`	Rusia	`ru`
Tionghoa Sederhana	`zh`	Prancis	`fr`
Jepang	`ja`	Jerman	`de`
Korea	`ko`	Indonesia	`id`
Portugis	`pt`	Spanyol	`es`

Nilai tidak peka huruf besar-kecil dan spasi di awal atau akhir akan dihapus secara otomatis. Misalnya, "ID" dan " id " sama-sama diperlakukan sebagai id.
Gunakan kode dua huruf dalam tabel. Tag wilayah seperti zh-CN, en-US, dan pt-BR tidak dikenali.
Nilai yang tidak didukung tidak menyebabkan pengiriman tugas gagal; callback tetap berisi pesan kesalahan asli.
Jika pesan asli sudah menggunakan bahasa target, pesan tersebut dikembalikan tanpa diterjemahkan ulang.
Jika penerjemahan gagal, pesan asli dikembalikan tanpa menunda atau membatalkan callback.

Saat melakukan polling, gunakan parameter kueri language pada endpoint status tugas untuk memilih bahasa pesan kesalahan yang sama. Webhook tidak memiliki string kueri, jadi language harus ditentukan saat mengirim tugas.

POST /mj/submit/* dan POST /v1/images/edits tidak mendukung webhook / language. Model gambar resmi xAI tidak mendukung language dan akan mengembalikan 400 parameter "language" is not supported jika parameter ini disertakan. Jangan kirim parameter ini ke model tersebut.

Aturan URL

webhook yang Anda berikan adalah URL dasar (base), dan kami otomatis menambahkan /callback di belakangnya:

`webhook` Anda	Ke mana kami benar-benar mem-POST
`https://your-server.com`	`https://your-server.com/callback`
`https://your-server.com/api`	`https://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 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": {
    "message": "Gambar input tidak dapat diakses. Pastikan URL dapat diakses secara publik",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

Untuk tugas video, hasilnya ada di result.videos, dan untuk audio di result.audios.

Contoh kegagalan di atas menggunakan "language": "id". Parameter bahasa hanya mengubah error.message; semua field lainnya tetap sama.

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:

Kembalikan 2xx secepat mungkin

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

Deduplikasi berdasarkan id

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

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:

Persyaratan	Keterangan
Dapat diakses publik	Tidak boleh berupa alamat internal / lokal (mis. `127.0.0.1`, `10.x`, `192.168.x` akan ditolak)
Protokol	`http` atau `https` (disarankan `https`)
Port	Gunakan port standar (`80` / `443`); port non-standar mungkin diblokir
Domain	Tidak boleh menunjuk ke domain layanan kami sendiri

URL yang tidak memenuhi persyaratan ini akan langsung dibuang (tidak dikirim, tidak dicoba ulang).

FAQ

Saya mengirim tugas dengan webhook tetapi tidak menerima pengiriman?

Periksa satu per satu:

Apakah tugas benar-benar selesai? Periksa detail tugas — apakah status sudah completed / failed (tidak dikirim saat diproses)?
Apakah URL Anda dapat diakses publik? Bisakah kami menjangkau /callback Anda?
Apakah port-nya standar (80 / 443)? Port non-standar mungkin diblokir oleh kebijakan keamanan.
Apakah /callback Anda mengembalikan 2xx tepat waktu? Mengembalikan 4xx akan langsung ditinggalkan.
Apakah Anda menggunakan https? Apakah sertifikatnya valid?

Mengapa url di dalam result berupa array?

Beberapa model menghasilkan banyak gambar sekaligus, jadi images[].url bisa berupa array — cukup perlakukan sebagai array.

Apakah tautan hasil memiliki masa berlaku?

Jika result menyertakan expires_at (timestamp Unix), itu menunjukkan waktu kedaluwarsa tautan — segera transfer/simpan.

Apakah status 'sedang diproses' dikirim?

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.

Ikhtisar

Model

Seri Teks

Seri Gambar

Seri Video

Seri Audio

Seri Moderasi

Manajemen Unggahan

Manajemen Tugas

Manajemen Akun

Callback Penyelesaian Tugas (Webhook)

Mulai cepat

Pilih bahasa pesan kesalahan

Aturan URL

Apa yang akan Anda terima

Percobaan ulang dan deduplikasi (penting)

Persyaratan untuk URL callback

FAQ

Contoh penerima minimal

​Mulai cepat

​Pilih bahasa pesan kesalahan

​Aturan URL

​Apa yang akan Anda terima

​Percobaan ulang dan deduplikasi (penting)

​Persyaratan untuk URL callback

​FAQ

​Contoh penerima minimal

Mulai cepat

Pilih bahasa pesan kesalahan

Aturan URL

Apa yang akan Anda terima

Percobaan ulang dan deduplikasi (penting)

Persyaratan untuk URL callback

FAQ

Contoh penerima minimal