Untuk permintaan yang memakan waktu lebih dari beberapa detik, yang biasa terjadi pada aplikasi AI, kami telah mengembangkan sistem antrian. Sistem ini menawarkan kontrol terperinci untuk mengelola lonjakan lalu lintas, membatalkan permintaan jika diperlukan, dan memantau status permintaan Anda dalam antrian. Ini juga menghilangkan kebutuhan untuk menangani permintaan HTTP yang berjalan lama.

​
Titik Akhir Antrian

Anda dapat mengakses semua fitur antrian melalui titik akhir berikut:
Titik AkhirMetodeDeskripsi
api.sunra.ai/v1/queue/{model-id}POSTMenambahkan permintaan ke antrian
api.sunra.ai/v1/queue/requests/{request_id}/statusGETMengambil status permintaan
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGETMengalirkan status hingga selesai
api.sunra.ai/v1/queue/requests/{request_id}GETMengambil respons dari permintaan
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUTMembatalkan permintaan
Misalnya, untuk mengirim permintaan menggunakan curl dan menambahkannya ke antrian: 
curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Kota tepi laut yang terinspirasi dari Studio Ghibli dengan rumah-rumah berwarna-warni, cucian berkibar, dan kucing tidur di ambang jendela."}'
Berikut adalah contoh respons yang menyertakan request_id: 
{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}
Payload menyertakan request_id dan menyediakan URL untuk memeriksa status, membatalkan, atau mengambil respons, menyederhanakan alur kerja Anda tanpa pengembangan titik akhir tambahan.

​
Status Permintaan

Untuk memantau kemajuan permintaan Anda, gunakan titik akhir yang disediakan dengan ID permintaan unik Anda. Ini memungkinkan Anda untuk melacak status, posisi antrian, atau mengambil respons setelah siap.

​
Penggunaan Titik Akhir

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​
Contoh Respons

Saat permintaan Anda berada di antrian, Anda akan menerima respons seperti ini: 
{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

​
Status yang Mungkin

Permintaan Anda dapat berada di salah satu dari tiga status:
  • IN_QUEUE: Menunjukkan permintaan sedang menunggu untuk diproses.
    • queue_position: Menampilkan posisi Anda dalam antrian.
    • response_url: URL untuk mengambil respons setelah pemrosesan selesai.
  • IN_PROGRESS: Permintaan sedang diproses.
    • logs: Log terperinci (jika diaktifkan) yang menunjukkan langkah-langkah pemrosesan.
    • response_url: Di mana respons akhir akan tersedia.
  • COMPLETED: Pemrosesan telah selesai.
    • logs: Log yang merinci seluruh proses.
    • response_url: Tautan langsung ke respons Anda yang telah selesai.

​
Mengaktifkan Log

Log memberikan wawasan tentang pemrosesan permintaan. Log dinonaktifkan secara default tetapi dapat diaktifkan dengan parameter kueri: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
Setiap entri log meliputi:
  • message: Deskripsi acara.
  • level: Tingkat keparahan (misalnya, INFO, ERROR).
  • source: Asal log.
  • timestamp: Waktu log dibuat.

​
Pemantauan Waktu Nyata

Untuk pembaruan berkelanjutan, gunakan titik akhir streaming: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
Ini memberikan pembaruan status waktu nyata dalam format text/event-stream hingga permintaan selesai.

​
Membatalkan Permintaan

Jika permintaan Anda masih dalam antrian, Anda dapat membatalkannya dengan: 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
Mengambil Respons

Setelah permintaan Anda COMPLETED, ambil respons menggunakan: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Titik akhir ini juga menyediakan log untuk ditinjau.

​
Integrasi yang Disederhanakan dengan Klien Sunra

Klien Sunra mengotomatiskan pelacakan status, menyederhanakan pengembangan aplikasi dengan fungsi Sunra.

​
Batas Laju

Untuk memastikan penggunaan yang adil dan stabilitas sistem, titik akhir API kami tunduk pada batas laju berikut:
Jenis Titik AkhirBatas LajuBatas Burst
Kirim ke Antrian10 permintaan/detik100 permintaan/menit
Semua Titik Akhir Lainnya100 permintaan/detik1.800 permintaan/menit
Jika Anda melebihi batas ini, Anda akan menerima respons 403 Forbidden. Kami merekomendasikan untuk menerapkan mekanisme coba lagi dengan backoff eksponensial untuk menangani kasus-kasus ini.