> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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`:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel
```

## Mengambil Respons

Setelah permintaan Anda `COMPLETED`, ambil respons menggunakan:

```bash theme={null}
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.