Fila - Sunra.ai

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:

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.

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:

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:

{
  "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:

{
  "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:

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

​Endpoints da Fila

​Status da Solicitação

​Uso do Endpoint

​Resposta de Exemplo

​Status Possíveis

​Habilitando Logs

​Monitoramento em Tempo Real

​Webhooks

​Habilitando Webhooks

​Quando o Webhook é Disparado

​Formato da Solicitação

​Payload

​Comportamento de Retentativas

​Boas Práticas

​Cancelando Solicitações

​Recuperando Respostas

​Integração Simplificada com o Cliente Sunra

​Limites de Taxa