Responses API completion_window: descontos com 2h e 8h

Configure solicitações em segundo plano na Responses API com desconto e campos aninhados corretamente. Compare soonest, 2h e 8h, recupere resultados e preserve a prioridade de agendamento e o histórico nas solicitações seguintes.

Conteúdo
Responses API completion_window: descontos com 2h e 8h

Se as revisões por API da sua equipe podem esperar algumas horas, use uma janela de conclusão da Responses API para reduzir as cobranças elegíveis por tokens. Defina background_options.completion_window como 2h ou 8h, com background: true e service_tier: "default". Siga as configurações documentadas das janelas de conclusão: não envie completion_window no nível superior nem ative streaming nessas janelas com desconto.

Escolha soonest, 2h ou 8h

Escolha a janela conforme o momento em que precisa da primeira resposta, não pelo tempo que imagina que o modelo levará para raciocinar. Em 2026-11-19, o guia do modo em segundo plano da OpenAI define estas opções e descontos.

JanelaDesconto nos tokens do modelo em relação ao StandardQuando usar
soonestNenhum; é a opção padrãoAlguém precisa do resultado naquele momento.
2h30%A revisão pode terminar antes de uma reunião posterior ou da próxima etapa de processamento.
8h40%Uma revisão noturna ou análise de documentos pode esperar até a manhã seguinte.

Definir apenas background: true não ativa um desconto. Sem uma configuração de janela de conclusão, a solicitação usa soonest. Para 2h e 8h, o prazo-alvo começa quando a API aceita a solicitação inicial e vale para aquela resposta. Não é um prazo para concluir todo o fluxo, incluindo as chamadas de ferramentas e solicitações seguintes.

Para calcular um exemplo limitado aos tokens, considere uma solicitação à Astra com 100,000 tokens de entrada sem cache e 10,000 tokens de saída faturáveis. Considere que não há gravações em cache, ferramentas pagas, cobranças de armazenamento ou acréscimos por processamento regional.

Em 2026-11-19, a tabela de preços Standard da OpenAI informa $8 por 1M tokens de entrada e $40 por 1M tokens de saída para a Astra com contexto curto. A ficha do modelo Astra aplica ajustes de contexto longo acima de 272K tokens de entrada. Os 100,000 tokens de entrada deste exemplo ficam abaixo desse limite.

O custo estimado dos tokens do modelo no Standard é:

(100,000 / 1,000,000 × $8) + (10,000 / 1,000,000 × $40) = $1.20

Com as mesmas quantidades de tokens, 2h resulta em $1.20 × 0.70 = $0.84, e 8h resulta em $1.20 × 0.60 = $0.72. São exemplos calculados, não cobranças medidas em solicitações reais.

O desconto se aplica às tarifas de tokens do modelo em cada solicitação elegível, incluindo as seguintes. Não aplique esse percentual a outras cobranças da fatura. Para trabalhos com cache, calcule gravações e leituras separadamente com o guia de custos do cache de prompts.

Confira o modelo e escolha a forma de acesso

Use diretamente a Responses API da OpenAI quando precisar dos controles documentados das janelas de conclusão. Em 2026-11-19, a lista de modelos elegíveis inclui GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Terra e GPT-6 Luna na versão beta pública. Os IDs dos modelos GPT-6.2 são gpt-6.2-astra e gpt-6.2-sol.

Para escolher o modelo e migrar, consulte o guia da API de GPT-6.2 Astra e Sol. Escolha a forma de acesso separadamente do modelo:

OpçãoO que exigeQuando escolher
OpenAI Responses APIUm projeto e uma chave de API, acesso a partir de um país ou território compatível e faturamento de API configurado ou créditos de API disponíveis. O uso é cobrado separadamente da assinatura do ChatGPT.Você precisa dos controles 2h ou 8h, principalmente quando as solicitações seguintes dependem dos resultados anteriores.
OpenAI Batch APIAs mesmas condições de acesso e faturamento da API, além do envio de solicitações independentes por arquivo.Todas as entradas são conhecidas de antemão. Use o fluxo da Batch API em vez de coordenar etapas dependentes.
BetterTokenSua própria conta e chave de API, um cliente compatível e as opções de pagamento disponíveis no console. O uso segue a unidade de cobrança de cada modelo.Você está comparando opções de acesso a modelos com pagamento por uso. Confira os preços da BetterToken e verifique separadamente o suporte às janelas de conclusão antes de enviar esse fluxo por um gateway.

Não presuma que uma assinatura do ChatGPT ou do Codex disponibilize essas opções de solicitação. O caminho documentado aqui é uma solicitação à Responses API, com faturamento de API separado do ChatGPT. A autenticação por chave de API do Codex usa o faturamento da API em vez dos créditos incluídos no plano. Isso, por si só, não confirma a existência de um controle de janela de conclusão no Codex.

Envie background_options com a estrutura correta

Coloque completion_window e continuation_id dentro de background_options. Mantenha background, service_tier e stream no nível superior, conforme o esquema de solicitações da Responses. O processamento Standard é obrigatório; service_tier: "default" seleciona esse modo.

O exemplo de Bash abaixo exige curl, jq e uuidgen. Execute os blocos na mesma sessão de shell e no mesmo diretório de trabalho. Quando read aguardar uma entrada, cole sua chave de API da OpenAI e pressione Enter. A chave não aparece na tela nem entra no histórico de comandos.

Este exemplo gera um ID de continuação porque depois enviará uma segunda solicitação. Ele pede que a API armazene as respostas e grava arquivos JSON locais. Revise seus requisitos de tratamento de dados antes de substituir o conteúdo por documentos sensíveis.

set +x
set -euo pipefail

read -rs OPENAI_API_KEY && export OPENAI_API_KEY
CONTINUATION_ID=$(uuidgen)

jq -n --arg continuation_id "$CONTINUATION_ID" '{
  model: "gpt-6.2-astra",
  input: "Review this migration plan for risks: add a nullable column, backfill it in batches, switch reads, then enforce NOT NULL.",
  background: true,
  service_tier: "default",
  stream: false,
  store: true,
  background_options: {
    completion_window: "8h",
    continuation_id: $continuation_id
  }
}' > background-request.json

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @background-request.json \
  --output background-response.json

jq -er '.id' background-response.json > background-response-id.txt
jq '{id, status, service_tier}' background-response.json

A primeira confirmação de sucesso é receber um id de resposta, salvo em background-response-id.txt. Um status queued ou in_progress significa que o resultado ainda não está pronto. Guarde esse ID em vez de enviar o mesmo trabalho novamente.

Consulte o status pelo ID salvo ou use um webhook

Recupere a resposta existente com GET /v1/responses/{response_id}. O loop abaixo continua apenas enquanto o status for queued ou in_progress. Ele termina com sucesso em completed e mostra informações sobre os outros estados finais. O intervalo de 30 segundos é uma escolha do exemplo, não uma exigência da API.

RESPONSE_ID=$(cat background-response-id.txt)

while :; do
  curl --fail-with-body --silent --show-error \
    "https://api.openai.com/v1/responses/$RESPONSE_ID" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    --output background-response.json

  STATUS=$(jq -r '.status' background-response.json)
  case "$STATUS" in
    queued|in_progress) sleep 30 ;;
    completed) break ;;
    *)
      jq '{id, status, error, incomplete_details}' background-response.json
      exit 1
      ;;
  esac
done

cp background-response.json "$RESPONSE_ID.json"
jq '{id, status, service_tier, usage}' background-response.json
jq -r '.output[]? | select(.type == "message") |
  .content[]? | select(.type == "output_text") | .text' \
  background-response.json

Neste exemplo somente de texto, o sucesso exige o status completed e a exibição do texto da revisão extraído da mensagem de resposta. A extração verifica os tipos dos itens, sem presumir que o primeiro item de saída contenha texto. Se uma consulta HTTP falhar, preserve o arquivo com o ID e execute novamente o bloco de consulta, não o de envio.

Em produção, siga as instruções para receber webhooks em vez de manter uma shell aberta. Assine o evento response.completed, verifique a assinatura recebida e recupere a resposta identificada por event.data.id. Use webhook-id para evitar o processamento de entregas duplicadas antes de iniciar o próximo trabalho. Preveja também como tratar os resultados malsucedidos.

Continue o fluxo sem perder histórico ou prioridade

Reutilize a janela de conclusão, o ID de continuação, o modelo e o projeto de API para que as solicitações relacionadas sejam elegíveis a maior prioridade na fila. Mantenha o processamento Standard e a execução em segundo plano na solicitação seguinte. O fluxo com solicitações seguintes da OpenAI condiciona a prioridade ao agendamento; não promete início imediato.

Os identificadores têm funções diferentes. background_options.continuation_id é um identificador escolhido pela aplicação para agendar solicitações; ele não fornece o histórico da conversa. previous_response_id aponta para a resposta anterior e permite continuar a conversa enquanto essa resposta estiver disponível.

Depois que a primeira solicitação terminar, este bloco preserva o modelo, a janela, o ID de continuação e as configurações de processamento. Ele adiciona o ID da resposta anterior e uma nova instrução. Use uma chave do mesmo projeto de API durante todo o fluxo.

RESPONSE_ID=$(cat background-response-id.txt)

jq --arg previous_response_id "$RESPONSE_ID" \
  '.previous_response_id = $previous_response_id |
   .input = "Turn the two highest-risk findings into acceptance tests."' \
  background-request.json > background-followup.json

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @background-followup.json \
  --output background-response.json

jq -er '.id' background-response.json > background-response-id.txt

Execute novamente o bloco de consulta para recuperar essa nova resposta. A solicitação seguinte é cobrada separadamente; as tarifas elegíveis de tokens do modelo recebem o desconto escolhido. Manter as configurações de continuação dá elegibilidade à prioridade, não a um desconto adicional. O histórico encadeado continua contando como tokens de entrada faturados.

Em fluxos com chamadas de função, envie um item de entrada function_call_output com o call_id original e o resultado da ferramenta em output. O guia de chamadas de função descreve essa troca. Não substitua o mecanismo de histórico da conversa por um ID de continuação; ele não consegue reconstruir uma resposta expirada.

Verifique os limites da fila e a cobrança antes de ampliar o uso

Planeje o tráfego em segundo plano com desconto junto com os trabalhos da Batch. Solicitações com 2h ou 8h compartilham o Batch/Background Rate Limit, e os tokens de entrada são contabilizados no envio. Verifique essa capacidade compartilhada antes de aumentar o volume de trabalhos agendados. Ter saldo financeiro disponível é uma questão separada.

Se o envio falhar, compare o parâmetro indicado no erro com o esquema da solicitação antes de tentar novamente um trabalho pequeno. Conforme o erro, confira a estrutura dos campos, a elegibilidade do modelo, o processamento Standard e a exigência de não usar streaming. Um ID retornado confirma a aceitação; recupere a resposta para verificar se a geração realmente termina.

Se as cobranças parecerem não incluir o desconto, procure uma janela explícita 2h ou 8h na solicitação salva, não apenas background: true. Confira o service_tier da resposta, que informa o modo de processamento usado de fato. Guarde o JSON enviado e o usage retornado, depois confira o primeiro trabalho com os preços atuais da API antes de aplicar a configuração à fila inteira.

Quer otimizar seu fluxo de trabalho com LLMs?

Conecte modelos por uma única API, gerencie chaves e controle os gastos com IA.

Começar grátis