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

# 대기열

AI 애플리케이션에서 일반적으로 몇 초 이상 걸리는 요청의 경우 대기열 시스템을 개발했습니다. 이 시스템은 트래픽 급증을 관리하고, 필요한 경우 요청을 취소하고, 대기열에서 요청 상태를 모니터링할 수 있는 세분화된 제어를 제공합니다. 또한 장기 실행 HTTP 요청을 처리할 필요가 없습니다.

## 대기열 엔드포인트

다음 엔드포인트를 통해 모든 대기열 기능에 액세스할 수 있습니다.

| 엔드포인트                                                 | 메서드  | 설명              |
| ----------------------------------------------------- | ---- | --------------- |
| api.sunra.ai/v1/queue/\{모델 ID}                        | POST | 대기열에 요청 추가      |
| api.sunra.ai/v1/queue/requests/\{요청 ID}/status        | GET  | 요청 상태 검색        |
| api.sunra.ai/v1/queue/requests/\{요청 ID}/status/stream | GET  | 완료될 때까지 상태 스트리밍 |
| api.sunra.ai/v1/queue/requests/\{요청 ID}               | GET  | 요청 응답 가져오기      |
| api.sunra.ai/v1/queue/requests/\{요청 ID}/cancel        | PUT  | 요청 취소           |

예를 들어 curl을 사용하여 요청을 제출하고 대기열에 추가하려면 다음을 수행합니다.

```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": "화려한 집, 펄럭이는 빨래, 창틀에서 잠자는 고양이가 있는 스튜디오 지브리풍 해변 마을."}'
```

다음은 `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"
}
```

페이로드에는 `request_id`가 포함되어 있으며 상태 확인, 취소 또는 응답 검색을 위한 URL을 제공하여 추가 엔드포인트 개발 없이 워크플로우를 간소화합니다.

## 요청 상태

요청 진행 상황을 모니터링하려면 고유한 요청 ID와 함께 제공된 엔드포인트를 사용합니다. 이를 통해 상태, 대기열 위치를 추적하거나 준비가 되면 응답을 검색할 수 있습니다.

### 엔드포인트 사용법

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

## 샘플 응답

요청이 대기열에 있으면 다음과 같은 응답을 받게 됩니다.

```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"
}
```

## 가능한 상태

요청은 다음 세 가지 상태 중 하나일 수 있습니다.

* **IN\_QUEUE**: 요청이 처리 대기 중임을 나타냅니다.
  * `queue_position`: 대기열에서의 위치를 보여줍니다.
  * `response_url`: 처리가 완료되면 응답을 검색하기 위한 URL입니다.

* **IN\_PROGRESS**: 요청이 현재 처리 중입니다.
  * `logs`: 처리 단계를 보여주는 자세한 로그(활성화된 경우).
  * `response_url`: 최종 응답을 사용할 수 있는 위치입니다.

* **COMPLETED**: 처리가 완료되었습니다.
  * `logs`: 전체 프로세스를 자세히 설명하는 로그.
  * `response_url`: 완료된 응답에 대한 직접 링크.

## 로그 활성화

로그는 요청 처리 과정을 파악하는 데 도움이 됩니다. 기본적으로 비활성화되어 있지만 쿼리 매개변수를 사용하여 활성화할 수 있습니다.

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
```

각 로그 항목에는 다음이 포함됩니다.

* `message`: 이벤트 설명.
* `level`: 심각도(예: INFO, ERROR).
* `source`: 로그 출처.
* `timestamp`: 로그 생성 시간.

## 실시간 모니터링

지속적인 업데이트를 위해 스트리밍 엔드포인트를 사용합니다.

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

이렇게 하면 요청이 완료될 때까지 `text/event-stream` 형식으로 실시간 상태 업데이트를 제공합니다.

## Webhooks

폴링 대신 알림을 받는 것을 선호한다면, 요청을 제출할 때 `webhook` 쿼리 매개변수를 전달하세요. 요청이 종료 상태에 도달하면 Sunra가 최종 결과를 해당 URL로 `POST`하므로 연결을 유지하거나 폴링을 예약할 필요가 없습니다.

### Webhooks 활성화

제출 엔드포인트에 URL 인코딩된 `webhook` 쿼리 매개변수를 추가하세요:

```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": "스튜디오 지브리 스타일에서 영감을 받은 해변 마을. 다채로운 집들, 바람에 펄럭이는 빨래, 창턱에서 자고 있는 고양이들."}'
```

Webhook URL을 URL 인코딩하고(예: `https%3A%2F%2F...`) Sunra가 해당 주소에 접근할 수 있는지 확인하세요. HTTPS 사용을 강력히 권장합니다. 제출 응답은 변경되지 않습니다 — 여전히 `request_id`와 동일한 status/cancel/response URL을 받습니다.

### Webhook 발생 시점

Sunra는 **종료 이벤트에서만** webhook을 호출합니다:

* `succeeded` — 요청이 완료되었으며 출력이 페이로드에 포함됩니다.
* `failed` — 요청이 오류가 발생했으며 오류 세부 정보가 페이로드에 포함됩니다.

중간 상태(`IN_QUEUE`, `IN_PROGRESS`)는 webhook을 **트리거하지 않습니다**. 진행 상태 업데이트도 필요하다면 위에 설명된 스트리밍 또는 폴링 엔드포인트와 webhook을 결합하세요.

### 요청 형식

Sunra는 다음 헤더와 함께 webhook URL로 `POST` 요청을 보냅니다:

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

엔드포인트는 5초 이내에 `2xx` 상태 코드로 응답해야 합니다. 빠르게 확인하고 무거운 작업은 백그라운드 작업으로 위임하세요 — 느린 응답은 실패로 간주되어 재시도를 트리거합니다.

### 페이로드

성공 이벤트:

```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": "스튜디오 지브리 스타일에서 영감을 받은 해변 마을..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
```

실패 이벤트는 `output`을 `error`로 대체합니다. `error`의 정확한 내용은 실패 유형에 따라 다릅니다 — 아래 예는 그중 하나의 일반적인 형태입니다:

```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": "스튜디오 지브리 스타일에서 영감을 받은 해변 마을..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "사람이 읽을 수 있는 오류 메시지"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
```

| 필드               | 설명                                                |
| ---------------- | ------------------------------------------------- |
| `id`             | 제출 시 반환된 `request_id`. 재시도를 중복 제거하는 데 사용하세요.      |
| `object`         | 항상 `"prediction"`.                                |
| `model`          | 모델 소유자 및 이름(예: `black-forest-labs/flux-1.1-pro`). |
| `model_endpoint` | 엔드포인트 슬러그(예: `text-to-image`).                    |
| `status`         | `"succeeded"` 또는 `"failed"`.                      |
| `input`          | 제출한 원본 요청 본문.                                     |
| `output`         | `succeeded`일 때 존재. 결과 엔드포인트가 반환하는 응답 본문과 동일.      |
| `error`          | `failed`일 때 존재. 실패를 설명하는 객체이며 구조는 실패 유형에 따라 다름.   |
| `created_at`     | 요청이 생성된 시점의 ISO 8601 타임스탬프.                       |
| `completed_at`   | 요청이 종료 상태에 도달한 시점의 ISO 8601 타임스탬프.                |

### 재시도 동작

Webhook 전달은 적어도-한-번 보장됩니다. 엔드포인트가 시간 초과(5초)되거나 `2xx`가 아닌 상태를 반환하면, Sunra는 지수 백오프로 재시도합니다 — **최대 3회** 재시도, 10초부터 시작하여 30초로 제한된 지연. 마지막 재시도 이후 실패는 로그에 기록되며 더 이상 시도되지 않습니다.

재시도가 동일한 이벤트를 두 번 이상 전달할 수 있으므로 핸들러는 멱등해야 합니다 — 중복 제거 키로 `id` 필드를 사용하세요.

### 모범 사례

* HTTPS를 사용하고 트래픽이 예상하는 엔드포인트에 도달하는지 확인하세요.
* 즉시 `2xx`로 응답하고 페이로드는 비동기적으로 처리하세요.
* 전달을 적어도-한-번으로 처리하고 `id`로 중복 제거하세요.
* 종료 이벤트 전에 진행 상태 업데이트가 필요한 경우 webhook을 폴링 또는 스트리밍 엔드포인트와 결합하세요.

## 요청 취소

요청이 아직 대기 중인 경우 다음을 사용하여 취소할 수 있습니다.

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

## 응답 검색

요청이 `COMPLETED`되면 다음을 사용하여 응답을 검색합니다.

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

이 엔드포인트는 검토를 위한 로그도 제공합니다.

## Sunra 클라이언트를 사용한 간소화된 통합

Sunra 클라이언트는 상태 추적을 자동화하여 Sunra 기능으로 앱 개발을 간소화합니다.

## 속도 제한

공정한 사용과 시스템 안정성을 보장하기 위해 API 엔드포인트에는 다음과 같은 속도 제한이 적용됩니다.

| 엔드포인트 유형        | 속도 제한     | 버스트 제한      |
| :-------------- | :-------- | :---------- |
| **대기열에 제출**     | 10개 요청/초  | 100개 요청/분   |
| **기타 모든 엔드포인트** | 100개 요청/초 | 1,800개 요청/분 |

이러한 제한을 초과하면 `403 Forbidden` 응답을 받게 됩니다. 이러한 경우를 처리하기 위해 지수 백오프가 있는 재시도 메커니즘을 구현하는 것이 좋습니다.