Antrian

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 Akhir	Metode	Deskripsi
api.sunra.ai/v1/queue/{model-id}	POST	Menambahkan permintaan ke antrian
api.sunra.ai/v1/queue/requests/{request_id}/status	GET	Mengambil status permintaan
api.sunra.ai/v1/queue/requests/{request_id}/status/stream	GET	Mengalirkan status hingga selesai
api.sunra.ai/v1/queue/requests/{request_id}	GET	Mengambil respons dari permintaan
api.sunra.ai/v1/queue/requests/{request_id}/cancel	PUT	Membatalkan 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.

Webhooks

Jika Anda lebih suka diberitahu daripada melakukan polling, sertakan parameter kueri webhook saat mengirim permintaan. Sunra akan melakukan POST hasil akhir ke URL tersebut setelah permintaan mencapai status terminal, sehingga Anda tidak perlu menjaga koneksi tetap terbuka atau menjadwalkan polling.

Mengaktifkan Webhooks

Tambahkan parameter kueri webhook yang dikodekan URL ke endpoint pengiriman:

curl -X POST \
  "https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image?webhook=https%3A%2F%2Fexample.com%2Fsunra-webhook" \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Sebuah kota tepi laut yang terinspirasi Studio Ghibli dengan rumah-rumah berwarna-warni, jemuran berkibar, dan kucing-kucing tidur di ambang jendela."}'

Kodekan URL webhook (mis. https%3A%2F%2F...) dan pastikan Sunra dapat menjangkaunya; HTTPS sangat dianjurkan. Respons pengiriman tidak berubah — Anda tetap menerima request_id dan URL status/cancel/response yang sama.

Kapan Webhook Dipicu

Sunra memanggil webhook Anda hanya pada peristiwa terminal:

succeeded — permintaan selesai dan output disertakan dalam payload.
failed — permintaan mengalami kesalahan dan detail kesalahan disertakan dalam payload.

Status menengah (IN_QUEUE, IN_PROGRESS) tidak memicu webhook. Jika Anda juga membutuhkan pembaruan progres, kombinasikan webhook dengan endpoint streaming atau polling yang dijelaskan di atas.

Format Permintaan

Sunra mengirim permintaan POST ke URL webhook Anda dengan:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Sunra-AI-Webhook/1.0`

Endpoint Anda harus merespons dengan kode status 2xx dalam waktu 5 detik. Konfirmasi cepat dan alihkan pekerjaan berat ke job latar belakang — respons yang lambat dianggap gagal dan memicu percobaan ulang.

Payload

Peristiwa sukses:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Sebuah kota tepi laut yang terinspirasi Studio Ghibli..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Peristiwa gagal mengganti output dengan error. Isi tepat error bervariasi tergantung jenis kegagalan — contoh di bawah menunjukkan salah satu bentuk umum:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Sebuah kota tepi laut yang terinspirasi Studio Ghibli..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "Pesan kesalahan yang dapat dibaca manusia"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Field	Deskripsi
`id`	`request_id` yang dikembalikan saat pengiriman. Gunakan untuk melakukan deduplikasi pada percobaan ulang.
`object`	Selalu `"prediction"`.
`model`	Pemilik dan nama model (mis. `black-forest-labs/flux-1.1-pro`).
`model_endpoint`	Slug endpoint (mis. `text-to-image`).
`status`	`"succeeded"` atau `"failed"`.
`input`	Body permintaan asli yang Anda kirim.
`output`	Hadir pada `succeeded`. Body respons yang sama dengan yang dikembalikan endpoint hasil.
`error`	Hadir pada `failed`. Objek yang menjelaskan kegagalan; strukturnya bergantung pada jenis kegagalan.
`created_at`	Timestamp ISO 8601 saat permintaan dibuat.
`completed_at`	Timestamp ISO 8601 saat permintaan mencapai status terminal.

Perilaku Percobaan Ulang

Pengiriman webhook bersifat at-least-once. Jika endpoint Anda timeout (5 dtk) atau mengembalikan status non-2xx, Sunra mencoba ulang dengan backoff eksponensial — hingga 3 kali percobaan ulang dengan penundaan mulai dari 10 detik dan dibatasi pada 30 detik. Setelah percobaan ulang terakhir, kegagalan dicatat dan tidak ada upaya lebih lanjut. Karena percobaan ulang dapat mengirimkan peristiwa yang sama lebih dari sekali, handler Anda harus idempoten — gunakan field id sebagai kunci deduplikasi.

Praktik Terbaik

Gunakan HTTPS dan verifikasi bahwa lalu lintas mencapai endpoint yang Anda harapkan.
Tanggapi 2xx segera dan proses payload secara asinkron.
Perlakukan pengiriman sebagai at-least-once dan dedup berdasarkan id.
Gabungkan webhook dengan endpoint polling atau streaming jika Anda memerlukan pembaruan progres sebelum peristiwa terminal.

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 Akhir	Batas Laju	Batas Burst
Kirim ke Antrian	10 permintaan/detik	100 permintaan/menit
Semua Titik Akhir Lainnya	100 permintaan/detik	1.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.

Ikhtisar

Multimodal

LLM

Pustaka Klien

Titik Akhir Antrian

Status Permintaan

Penggunaan Titik Akhir

Contoh Respons

Status yang Mungkin

Mengaktifkan Log

Pemantauan Waktu Nyata

Webhooks

Mengaktifkan Webhooks

Kapan Webhook Dipicu

Format Permintaan

Payload

Perilaku Percobaan Ulang

Praktik Terbaik

Membatalkan Permintaan

Mengambil Respons

Integrasi yang Disederhanakan dengan Klien Sunra

Batas Laju

​Titik Akhir Antrian

​Status Permintaan

​Penggunaan Titik Akhir

​Contoh Respons

​Status yang Mungkin

​Mengaktifkan Log

​Pemantauan Waktu Nyata

​Webhooks

​Mengaktifkan Webhooks

​Kapan Webhook Dipicu

​Format Permintaan

​Payload

​Perilaku Percobaan Ulang

​Praktik Terbaik

​Membatalkan Permintaan

​Mengambil Respons

​Integrasi yang Disederhanakan dengan Klien Sunra

​Batas Laju

Titik Akhir Antrian

Status Permintaan

Penggunaan Titik Akhir

Contoh Respons

Status yang Mungkin

Mengaktifkan Log

Pemantauan Waktu Nyata

Webhooks

Mengaktifkan Webhooks

Kapan Webhook Dipicu

Format Permintaan

Payload

Perilaku Percobaan Ulang

Praktik Terbaik

Membatalkan Permintaan

Mengambil Respons

Integrasi yang Disederhanakan dengan Klien Sunra

Batas Laju