如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

背景模式

在背景以非同步方式執行耗時任務。

從 Codex 和深度研究等智慧體可以看出,推理模型解決複雜問題時可能需要幾分鐘。背景模式讓你能使用 GPT-5.2 和 GPT-5.2 Pro 等模型可靠地執行耗時任務,無須擔心逾時或其他連線問題。

背景模式會以非同步方式啟動這些任務,開發人員可以輪詢回應物件,持續查看任務狀態。若要在背景開始產生回應,請在送出 API 請求時將 background 設為 true:

零資料保留(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 的 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 物件。

串流背景回應

你可以建立背景 Response,並立即開始透過串流接收該回應的事件。如果你預期用戶端可能會中斷串流,並希望稍後能接續接收事件,就可以使用這個方式。建立 Response 時,請將 background 和 stream 都設為 true。請記錄每個串流事件中的 sequence_number,以便用作追蹤串流進度的「游標」。

目前,接收背景回應的第一個 Token 所需的時間比同步回應更長。我們正努力在未來幾週內縮小這項延遲差距。

產生背景回應並串流其事件
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,才能從該回應啟動新的串流。