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 -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를 포함하는 샘플 응답입니다.
{
"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와 함께 제공된 엔드포인트를 사용합니다. 이를 통해 상태, 대기열 위치를 추적하거나 준비가 되면 응답을 검색할 수 있습니다.
엔드포인트 사용법
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status
샘플 응답
요청이 대기열에 있으면 다음과 같은 응답을 받게 됩니다.
{
"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: 완료된 응답에 대한 직접 링크.
로그 활성화
로그는 요청 처리 과정을 파악하는 데 도움이 됩니다. 기본적으로 비활성화되어 있지만 쿼리 매개변수를 사용하여 활성화할 수 있습니다.
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
message: 이벤트 설명.level: 심각도(예: INFO, ERROR).source: 로그 출처.timestamp: 로그 생성 시간.
실시간 모니터링
지속적인 업데이트를 위해 스트리밍 엔드포인트를 사용합니다.
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 쿼리 매개변수를 추가하세요:
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": "스튜디오 지브리 스타일에서 영감을 받은 해변 마을. 다채로운 집들, 바람에 펄럭이는 빨래, 창턱에서 자고 있는 고양이들."}'
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 |
2xx 상태 코드로 응답해야 합니다. 빠르게 확인하고 무거운 작업은 백그라운드 작업으로 위임하세요 — 느린 응답은 실패로 간주되어 재시도를 트리거합니다.
페이로드
성공 이벤트:
{
"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의 정확한 내용은 실패 유형에 따라 다릅니다 — 아래 예는 그중 하나의 일반적인 형태입니다:
{
"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을 폴링 또는 스트리밍 엔드포인트와 결합하세요.
요청 취소
요청이 아직 대기 중인 경우 다음을 사용하여 취소할 수 있습니다.
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel
응답 검색
요청이 COMPLETED되면 다음을 사용하여 응답을 검색합니다.
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Sunra 클라이언트를 사용한 간소화된 통합
Sunra 클라이언트는 상태 추적을 자동화하여 Sunra 기능으로 앱 개발을 간소화합니다.
속도 제한
공정한 사용과 시스템 안정성을 보장하기 위해 API 엔드포인트에는 다음과 같은 속도 제한이 적용됩니다.
| 엔드포인트 유형 | 속도 제한 | 버스트 제한 |
|---|
| 대기열에 제출 | 10개 요청/초 | 100개 요청/분 |
| 기타 모든 엔드포인트 | 100개 요청/초 | 1,800개 요청/분 |
403 Forbidden 응답을 받게 됩니다. 이러한 경우를 처리하기 위해 지수 백오프가 있는 재시도 메커니즘을 구현하는 것이 좋습니다.
