For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal
Theme

Modo em segundo plano

Execute tarefas de longa duração de forma assíncrona em segundo plano.

Agentes como o Codex e a pesquisa aprofundada mostram que modelos de raciocínio podem levar vários minutos para resolver problemas complexos. O modo em segundo plano permite executar tarefas de longa duração de forma confiável com modelos como GPT-5.2 e GPT-5.2 Pro, sem precisar se preocupar com limites de tempo ou outros problemas de conexão.

O modo em segundo plano inicia essas tarefas de forma assíncrona. Os desenvolvedores podem consultar os objetos de resposta periodicamente para acompanhar o status das tarefas. Para começar a gerar uma resposta em segundo plano, faça uma requisição à API com background definido como true.

As requisições em segundo plano de projetos com zero retenção de dados (ZDR) são executadas com store=false. Os dados da resposta ficam armazenados temporariamente em disco por cerca de 10 minutos para permitir a execução assíncrona e as consultas periódicas.

Em projetos que usam o monitoramento modificado de abusos, inclusive em sua versão aprimorada, as requisições em primeiro plano seguem a política de retenção padrão quando você omite store ou o define como true. As respostas em segundo plano só ficam armazenadas após o período de consulta quando você informa store=true explicitamente. Se você omitir store ou o definir como false em uma requisição em segundo plano, a resposta será excluída após cerca de 10 minutos.

Gerar uma resposta em segundo plano
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    input="Write a very long novel about otters in space.",
    background=True,
)

print(resp.status)

Consultar periodicamente as respostas em segundo plano

Para verificar o status das requisições em segundo plano, use o endpoint GET da API Responses. Repita a consulta enquanto a requisição estiver no estado queued ou in_progress. Quando sair desses estados, ela terá atingido um estado final (terminal).

Recuperar uma resposta em execução em segundo plano
from openai import OpenAI
from time import sleep

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    input="Write a very long novel about otters in space.",
    background=True,
)

while resp.status in {"queued", "in_progress"}:
    print(f"Current status: {resp.status}")
    sleep(2)
    resp = client.responses.retrieve(resp.id)

print(f"Final status: {resp.status}\nOutput:\n{resp.output_text}")

Cancelar uma resposta em segundo plano

Você também pode cancelar uma resposta em andamento, como no exemplo a seguir.

Cancelar uma resposta em andamento
import os

from openai import OpenAI

response_id = os.environ["OPENAI_RESPONSE_ID"]
client = OpenAI()

resp = client.responses.cancel(response_id)

print(resp.status)

Cancelar a mesma resposta duas vezes é uma operação idempotente. As chamadas seguintes apenas retornam o objeto Response em seu estado final.

Transmitir uma resposta em segundo plano

Você pode criar um objeto Response em segundo plano e começar a receber seus eventos por streaming imediatamente. Isso pode ser útil se você prevê que o cliente interromperá a transmissão e quer poder retomá-la depois. Para isso, crie um objeto Response com background e stream definidos como true. Atualize o “cursor” com o valor de sequence_number recebido em cada evento da transmissão.

Atualmente, o primeiro token de uma resposta em segundo plano demora mais para chegar do que o de uma resposta síncrona. Estamos trabalhando para reduzir essa diferença de latência nas próximas semanas.

Gerar e transmitir uma resposta em segundo plano
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-6-astra",
  "input": "Write a very long novel about otters in space.",
  "background": true,
  "stream": true
}'

// To resume:
curl "https://api.openai.com/v1/responses/resp_123?stream=true&starting_after=42" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY"

Limites

  1. Requisições em segundo plano podem usar store=false, mas os dados da resposta ficam armazenados temporariamente para permitir a execução assíncrona e as consultas periódicas.
  2. Para cancelar uma resposta síncrona, encerre a conexão.
  3. Você só pode iniciar uma nova transmissão a partir de uma resposta em segundo plano se tiver criado essa resposta com stream=true.