FlowModels

Requisições longas em segundo plano: Responses com background, consulta e cancelamento

Publicado em 11. novembro 2026

Algumas requisições demoram bastante, por exemplo quando um modelo raciocina a fundo ou escreve um texto longo. Em vez de manter a conexão aberta o tempo todo, inicie a requisição como tarefa em segundo plano pelo endpoint /responses. Você recebe um ID na hora e busca o resultado quando estiver pronto, por consulta, por stream ou por webhook.

O endpoint /responses

POST /v1/responses é a alternativa ao Chat Completions no formato da API Responses da OpenAI. Em vez de messages, você envia input, como texto simples ou como lista de mensagens. O texto da resposta fica em output[].content[] com type: "output_text", e as bibliotecas da OpenAI oferecem diretamente output_text para isso.

Sem outras indicações, o endpoint responde de forma síncrona, como o Chat Completions. Com stream: true, os eventos chegam em stream. Com background: true, a tarefa roda em segundo plano.

Iniciar uma tarefa em segundo plano

curl https://api.flowmodels.one/v1/responses \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: proposta-2026-117-rascunho" \
  -d '{"model": "groq/openai/gpt-oss-120b", "background": true, "input": "Escreva um texto detalhado de proposta para um site com loja online."}'

A API responde imediatamente com HTTP 202 e um objeto com status: "queued":

{"id": "resp_018f1234-5678-7abc-9def-0123456789ab", "object": "response", "status": "queued", "store": true, "output": [], "output_text": ""}

Tarefas em segundo plano são sempre armazenadas. A API recusa background: true junto com store: false.

Consultar o status

Com GET /v1/responses/{id}, você consulta o andamento. status passa por estes valores:

  • queued: aguardando processamento
  • in_progress: em execução
  • completed: pronta, com o resultado em output
  • failed: falhou, com detalhes em error
  • cancelled: cancelada
  • incomplete: encerrada antes do fim, por exemplo porque o limite de saída foi atingido

Consulte em intervalos razoáveis, por exemplo a cada poucos segundos. Cada consulta conta para o seu limite de requisições.

Acompanhar o andamento em stream e retomar

Se você combinar background: true com stream: true, recebe os eventos imediatamente em stream, e a tarefa continua rodando do nosso lado. Cada evento traz um sequence_number contínuo. Guarde o último que você recebeu.

Se a conexão cair, a tarefa simplesmente continua. Você retoma o stream do último ponto:

curl -N "https://api.flowmodels.one/v1/responses/resp_018f1234-5678-7abc-9def-0123456789ab?stream=true&starting_after=41" \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Accept: text/event-stream"

Você recebe então apenas os eventos depois do número 41. Essa consulta não inicia uma nova chamada de modelo e não tem custo extra. starting_after é um número inteiro a partir de 0 e só funciona junto com stream=true.

Resultado por webhook em vez de consulta

Em vez de consultar periodicamente, seu servidor pode ser notificado. Para isso, crie um webhook com os eventos response.completed, response.failed, response.cancelled e response.incomplete, veja Configurar webhooks do FlowModels. Envie o UUID dele no início, como webhook_endpoint_id. A entrega contém apenas o ID e o status, e o resultado é obtido em seguida com GET /responses/{id}. Como proteger a entrega está em Verificar a assinatura de webhook.

Cancelar

POST /v1/responses/{id}/cancel cancela uma tarefa em andamento e retorna o estado atual dela. Se a tarefa já tiver terminado, falhado ou sido cancelada, a chamada dá certo mesmo assim e não altera nada. Portanto, você pode enviá-la várias vezes sem risco. Os custos já gerados continuam valendo.

Por quanto tempo o resultado fica disponível

Respostas armazenadas e seus eventos ficam disponíveis por 24 horas depois da conclusão. Depois disso, e no caso de respostas não armazenadas ou de outra equipe, você recebe 404 response_not_found. Portanto, busque seu resultado logo e armazene do seu lado.

Bom saber

  • Com metadata, você pode enviar até 16 pares de valores próprios, como seu número de pedido. Eles voltam com a resposta armazenada. No Chat Completions, esse campo não é permitido.
  • O Brain funciona aqui do mesmo jeito que no Chat Completions, com external_identifier e conversation, veja Usar o Brain: salvar e continuar conversas por usuário final.
  • A resposta armazenada não é a mesma coisa que o histórico de conversas no Brain. Depois de 24 horas, só desaparece a resposta disponível para consulta, não a conversa.
  • Na biblioteca para Python, campos próprios como external_identifier ou webhook_endpoint_id são enviados por extra_body, veja Usar a biblioteca da OpenAI para Python e Node.js com o FlowModels.

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP