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 processamentoin_progress: em execuçãocompleted: pronta, com o resultado emoutputfailed: falhou, com detalhes emerrorcancelled: canceladaincomplete: 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_identifiereconversation, 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_identifierouwebhook_endpoint_idsão enviados porextra_body, veja Usar a biblioteca da OpenAI para Python e Node.js com o FlowModels.