Idempotensi
Error jaringan bisa membuat Anda tidak tahu apakah sebuah request sudah sampai ke API. Mengulang request adalah langkah yang tepat, tetapi untuk pekerjaan yang mahal — job video, pembuatan yang panjang — Anda tentu tidak ingin pekerjaan itu berjalan dua kali. Kirim header Idempotency-Key dan percobaan ulang dengan key yang sama akan dikenali sebagai request yang sama.
curl https://api.inferray.com/v1/videos \
-H "Authorization: Bearer $INFERRAY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d3c2e1a-onboarding-video-42" \
-d '{"model": "veo-3.1-fast-generate-preview", "prompt": "A paper boat on a pond", "seconds": 8}'
Key adalah string apa pun hingga 256 karakter. UUID acak per request logis berfungsi dengan baik; buat sekali saja, sebelum percobaan pertama, dan gunakan kembali untuk setiap percobaan ulang.
Apa yang terjadi saat request diulang
| Yang Anda kirim | Yang Anda terima |
|---|---|
| Key yang sama dan body yang sama, untuk video atau respons tersimpan | Job atau respons yang dibuat oleh request pertama. Tidak ada yang dijalankan atau ditagih lagi. |
| Key yang sama dan body yang sama, untuk request lainnya | 409 yang menyatakan bahwa request sudah pernah dikirim. Request tidak dijalankan lagi. |
| Key yang sama dengan body atau model yang berbeda | 409. Sebuah key terikat pada request pertama yang menggunakannya. |
| Key baru | Request baru. |
Key disimpan selama satu hari untuk request biasa, tujuh hari untuk job video, dan tiga puluh hari untuk respons tersimpan.
Kapan menggunakannya
- Selalu untuk pembuatan video, yang lambat dan ditagih per detik.
- Untuk request apa pun yang diulang otomatis oleh kode Anda setelah timeout atau error koneksi.
- Di job queue yang mungkin mengirimkan task yang sama lebih dari sekali.
Tanpa header ini, setiap request diperlakukan sebagai request baru, dan biasanya memang itulah yang diinginkan untuk penggunaan interaktif.