> ## 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. # Fila 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: | Endpoint | Método | Descrição | | ----------------------------------------------------------- | ------ | ------------------------------------ | | api.sunra.ai/v1/queue/\{model-id} | POST | Adiciona uma solicitação à fila | | api.sunra.ai/v1/queue/requests/\{request\_id}/status | GET | Recupera o status de uma solicitação | | api.sunra.ai/v1/queue/requests/\{request\_id}/status/stream | GET | Transmite o status até a conclusão | | api.sunra.ai/v1/queue/requests/\{request\_id} | GET | Busca a resposta de uma solicitação | | api.sunra.ai/v1/queue/requests/\{request\_id}/cancel | PUT | Cancela uma solicitação | Por exemplo, para enviar uma solicitação usando curl e adicioná-la à fila: ```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": "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`: ```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" } ``` 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 ```bash theme={null} 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: ```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 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: ```bash theme={null} 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: ```bash theme={null} 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. ## Webhooks Se você prefere ser notificado em vez de fazer polling, passe um parâmetro de consulta `webhook` ao enviar uma solicitação. O Sunra fará um `POST` com o resultado final para essa URL assim que a solicitação atingir um estado terminal, então você não precisa manter uma conexão aberta nem agendar polling. ### Habilitando Webhooks Adicione um parâmetro de consulta `webhook` codificado em URL ao endpoint de envio: ```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": "Uma cidade litorânea inspirada no Studio Ghibli com casas coloridas, roupas penduradas no varal e gatos dormindo nas janelas."}' ``` Codifique a URL do webhook (por exemplo, `https%3A%2F%2F...`) e garanta que o Sunra consiga acessá-la; HTTPS é fortemente recomendado. A resposta de envio não muda — você ainda recebe um `request_id` e as mesmas URLs de status/cancelamento/resposta. ### Quando o Webhook é Disparado O Sunra chama seu webhook **apenas em eventos terminais**: * `succeeded` — a solicitação foi concluída e a saída está incluída no payload. * `failed` — a solicitação falhou e os detalhes do erro estão incluídos no payload. Estados intermediários (`IN_QUEUE`, `IN_PROGRESS`) **não** disparam um webhook. Se você também precisar de atualizações de progresso, combine o webhook com os endpoints de streaming ou polling descritos acima. ### Formato da Solicitação O Sunra envia uma solicitação `POST` para a URL do seu webhook com: | Header | Value | | -------------- | ---------------------- | | `Content-Type` | `application/json` | | `User-Agent` | `Sunra-AI-Webhook/1.0` | Seu endpoint deve responder com um código de status `2xx` em até 5 segundos. Confirme rápido e mova qualquer trabalho pesado para um job em segundo plano — respostas lentas são tratadas como falhas e disparam novas tentativas. ### Payload Um evento de sucesso: ```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": "Uma cidade litorânea inspirada no Studio Ghibli..." }, "output": { "images": [ { "url": "https://..." } ] }, "created_at": "2026-04-28T12:00:00.000Z", "completed_at": "2026-04-28T12:00:08.123Z" } ``` Um evento de falha substitui `output` por `error`. O conteúdo exato de `error` varia de acordo com o tipo de falha — o exemplo abaixo mostra uma forma comum: ```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": "Uma cidade litorânea inspirada no Studio Ghibli..." }, "error": { "code": "EXAMPLE_ERROR_CODE", "message": "Mensagem de erro legível" }, "created_at": "2026-04-28T12:00:00.000Z", "completed_at": "2026-04-28T12:00:08.123Z" } ``` | Campo | Descrição | | ---------------- | --------------------------------------------------------------------------------------------- | | `id` | O `request_id` retornado no envio. Use-o para deduplicar tentativas. | | `object` | Sempre `"prediction"`. | | `model` | O proprietário e o nome do modelo (por exemplo, `black-forest-labs/flux-1.1-pro`). | | `model_endpoint` | O slug do endpoint (por exemplo, `text-to-image`). | | `status` | `"succeeded"` ou `"failed"`. | | `input` | O corpo da solicitação original que você enviou. | | `output` | Presente em `succeeded`. O mesmo corpo de resposta retornado pelo endpoint de resultado. | | `error` | Presente em `failed`. Um objeto que descreve a falha; sua estrutura depende do tipo de falha. | | `created_at` | Timestamp ISO 8601 de quando a solicitação foi criada. | | `completed_at` | Timestamp ISO 8601 de quando a solicitação atingiu o estado terminal. | ### Comportamento de Retentativas A entrega de webhook é pelo-menos-uma-vez. Se seu endpoint exceder o timeout (5 s) ou retornar um status diferente de `2xx`, o Sunra tenta novamente com backoff exponencial — até **3 retentativas** com atrasos começando em 10 segundos e limitados a 30 segundos. Após a última tentativa, a falha é registrada e não há mais tentativas. Como as retentativas podem entregar o mesmo evento mais de uma vez, seu handler deve ser idempotente — use o campo `id` como chave de deduplicação. ### Boas Práticas * Use HTTPS e verifique se o tráfego está chegando ao endpoint esperado. * Responda `2xx` imediatamente e processe o payload de forma assíncrona. * Trate a entrega como pelo-menos-uma-vez e deduplique por `id`. * Combine webhooks com os endpoints de polling ou streaming se você precisar de atualizações de progresso antes do evento terminal. ## Cancelando Solicitações Se sua solicitação ainda estiver na fila, você pode cancelá-la com: ```bash theme={null} 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: ```bash theme={null} 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 Endpoint | Limite de Taxa | Limite de Rajada | | :---------------------------- | :----------------------- | :------------------------ | | **Enviar para a Fila** | 10 solicitações/segundo | 100 solicitações/minuto | | **Todos os outros Endpoints** | 100 solicitações/segundo | 1.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.