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

​
대기열 엔드포인트

다음 엔드포인트를 통해 모든 대기열 기능에 액세스할 수 있습니다.
엔드포인트메서드설명
api.sunra.ai/v1/queue/{모델 ID}POST대기열에 요청 추가
api.sunra.ai/v1/queue/requests/{요청 ID}/statusGET요청 상태 검색
api.sunra.ai/v1/queue/requests/{요청 ID}/status/streamGET완료될 때까지 상태 스트리밍
api.sunra.ai/v1/queue/requests/{요청 ID}GET요청 응답 가져오기
api.sunra.ai/v1/queue/requests/{요청 ID}/cancelPUT요청 취소
예를 들어 curl을 사용하여 요청을 제출하고 대기열에 추가하려면 다음을 수행합니다. 
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 형식으로 실시간 상태 업데이트를 제공합니다.

​
요청 취소

요청이 아직 대기 중인 경우 다음을 사용하여 취소할 수 있습니다. 
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 응답을 받게 됩니다. 이러한 경우를 처리하기 위해 지수 백오프가 있는 재시도 메커니즘을 구현하는 것이 좋습니다.