Para solicitações que demoram mais do que alguns segundos, típicas em aplicações de IA, desenvolvemos um sistema de filas. Este sistema oferece controle refinado para gerenciar picos de tráfego, cancelar solicitações se necessário e monitorar o status de sua solicitação na fila. Ele também elimina a necessidade de lidar com solicitações HTTP de longa duração.

​
Endpoints da Fila

Você pode acessar todos os recursos da fila através dos seguintes endpoints:
EndpointMétodoDescrição
api.sunra.ai/v1/queue/{model-id}POSTAdiciona uma solicitação à fila
api.sunra.ai/v1/queue/requests/{request_id}/statusGETRecupera o status de uma solicitação
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGETTransmite o status até a conclusão
api.sunra.ai/v1/queue/requests/{request_id}GETBusca a resposta de uma solicitação
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUTCancela uma solicitação
Por exemplo, para enviar uma solicitação usando curl e adicioná-la à fila: 
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": "Uma cidade litorânea inspirada no Studio Ghibli com casas coloridas, roupas balançando no varal e gatos dormindo nos parapeitos das janelas."}'
Aqui está uma resposta de exemplo incluindo o 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"
}
O payload inclui o request_id e fornece URLs para verificar o status, cancelar ou recuperar a resposta, simplificando seu fluxo de trabalho sem desenvolvimento adicional de endpoint.

​
Status da Solicitação

Para monitorar o progresso de sua solicitação, use o endpoint fornecido com seu ID de solicitação exclusivo. Isso permite que você acompanhe o status, a posição na fila ou recupere a resposta assim que estiver pronta.

​
Uso do Endpoint

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​
Resposta de Exemplo

Quando sua solicitação estiver na fila, você receberá uma resposta como esta: 
{
  "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 Possíveis

Sua solicitação pode estar em um dos três estados:
  • IN_QUEUE: Indica que a solicitação está aguardando para ser processada.
    • queue_position: Mostra sua posição na fila.
    • response_url: URL para recuperar a resposta assim que o processamento for concluído.
  • IN_PROGRESS: A solicitação está sendo processada no momento.
    • logs: Logs detalhados (se habilitados) mostrando as etapas de processamento.
    • response_url: Onde a resposta final estará disponível.
  • COMPLETED: O processamento foi concluído.
    • logs: Logs detalhando todo o processo.
    • response_url: Link direto para sua resposta concluída.

​
Habilitando Logs

Os logs fornecem informações sobre o processamento da solicitação. Eles são desabilitados por padrão, mas podem ser habilitados com um parâmetro de consulta: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
Cada entrada de log inclui:
  • message: Descrição do evento.
  • level: Gravidade (por exemplo, INFO, ERROR).
  • source: Origem do log.
  • timestamp: Hora em que o log foi gerado.

​
Monitoramento em Tempo Real

Para atualizações contínuas, use o endpoint de streaming: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
Isso fornece atualizações de status em tempo real no formato text/event-stream até que a solicitação seja concluída.

​
Cancelando Solicitações

Se sua solicitação ainda estiver na fila, você pode cancelá-la com: 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
Recuperando Respostas

Assim que sua solicitação for COMPLETED, recupere a resposta usando: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Este endpoint também fornece logs para revisão.

​
Integração Simplificada com o Cliente Sunra

O cliente Sunra automatiza o rastreamento de status, simplificando o desenvolvimento de aplicativos com as funções Sunra.

​
Limites de Taxa

Para garantir o uso justo e a estabilidade do sistema, nossos endpoints de API estão sujeitos aos seguintes limites de taxa:
Tipo de EndpointLimite de TaxaLimite de Rajada
Enviar para a Fila10 solicitações/segundo100 solicitações/minuto
Todos os outros Endpoints100 solicitações/segundo1.800 solicitações/minuto
Se você exceder esses limites, receberá uma resposta 403 Forbidden. Recomendamos implementar um mecanismo de repetição com recuo exponencial para lidar com esses casos.