For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

백그라운드 모드

오래 걸리는 작업을 백그라운드에서 비동기로 실행하세요.

Codex와 심층 리서치 같은 에이전트에서 볼 수 있듯이, 추론 모델이 복잡한 문제를 해결하는 데는 몇 분이 걸릴 수 있습니다. 백그라운드 모드를 사용하면 시간 초과나 기타 연결 문제를 걱정할 필요 없이 GPT-5.2나 GPT-5.2 Pro 같은 모델에서 오래 걸리는 작업을 안정적으로 실행할 수 있습니다.

백그라운드 모드는 작업을 비동기로 시작합니다. 개발자는 응답 객체를 주기적으로 조회(폴링)해 작업 상태를 확인할 수 있습니다. 백그라운드에서 응답 생성을 시작하려면 background를 true로 설정해 API 요청을 보내세요.

데이터 비보관(ZDR)이 적용된 프로젝트의 백그라운드 요청은 store=false로 실행됩니다. 비동기 실행과 폴링을 지원하기 위해 응답 데이터는 약 10분간 디스크에 임시로 저장됩니다.

수정된 악용 모니터링 또는 그 강화 버전을 사용하는 프로젝트에서는 포그라운드 요청에서 store를 생략하거나 true로 설정하면 표준 데이터 보존 정책이 적용됩니다. 백그라운드 응답은 store=true를 명시한 경우에만 폴링 기간이 끝난 뒤에도 보관됩니다. 백그라운드 요청에서 store를 생략하거나 false로 설정하면 약 10분 후에 응답이 삭제됩니다.

백그라운드에서 응답 생성하기
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)

백그라운드 응답 폴링하기

백그라운드 요청의 상태를 확인하려면 Responses API의 GET 엔드포인트를 사용하세요. 요청 상태가 queued 또는 in_progress인 동안에는 폴링을 계속하세요. 요청이 이 두 상태를 벗어나면 최종 상태에 도달한 것입니다.

백그라운드에서 생성 중인 응답 조회하기
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}")

백그라운드 응답 취소하기

생성 중인 응답은 다음과 같이 취소할 수 있습니다.

생성 중인 응답 취소하기
import os

from openai import OpenAI

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

resp = client.responses.cancel(response_id)

print(resp.status)

취소 작업은 멱등성을 보장합니다. 같은 응답에 대해 취소를 다시 호출하면 최종 Response 객체만 반환됩니다.

백그라운드 응답 스트리밍하기

백그라운드 응답을 생성하고 곧바로 이벤트 스트리밍을 시작할 수 있습니다. 클라이언트의 스트림 연결이 끊길 가능성이 있고 나중에 스트리밍을 재개하려는 경우에 유용합니다. 응답을 생성할 때 background와 stream을 모두 true로 설정하세요. 스트리밍 이벤트를 받을 때마다 해당 이벤트의 sequence_number에 해당하는 “커서”를 기록해 두세요.

현재 백그라운드 응답은 동기 응답보다 첫 토큰을 받기까지 더 오래 걸립니다. 앞으로 몇 주 안에 이 지연 시간 차이를 줄이기 위해 개선 작업을 진행하고 있습니다.

백그라운드 응답 생성 및 스트리밍하기
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"

제한 사항

  1. 백그라운드 요청에서 store=false를 사용할 수 있지만, 비동기 실행과 폴링을 위해 응답 데이터는 임시로 저장됩니다.
  2. 동기 응답을 취소하려면 연결을 종료하세요.
  3. 백그라운드 응답에서 새 스트림을 시작하려면 응답을 생성할 때 stream=true를 설정해야 합니다.