如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

后台模式

异步执行耗时较长的 Responses API 请求和多轮工作流。

使用后台模式可以异步执行耗时较长的 Responses API 请求,包括多步骤智能体运行中的请求。一次智能体运行涵盖由应用管理的整个工作流。应用先发送初始请求,再根据结果决定下一步,例如运行工具并在后续请求中发送工具输出。如果多个请求彼此独立,而且一开始就可以一起提交,请使用 Batch API。

选择完成时限

根据您需要多快收到初始响应来设置 background_options.completion_window。选择 2h 或 8h 时,API 的目标是在接受请求后的相应时限内完成响应。

完成时限 适用场景 模型 Token 折扣
soonest(默认) 有人正在等待结果时,按需生成报告。 无
2h 在下午的分流会议前分析上午收到的支持工单。 比标准费率低 30%
8h 夜间审查一批文档,供次日早晨使用。 比标准费率低 40%

如需在夜间审查文档,先发送一个 8h 请求。如果初始响应要求应用查找文档,请运行工具,并在后续请求中发送工具结果。沿用相同的完成时限、续接 ID、模型和项目,使后续请求有资格获得更高的队列优先级。

目标完成时限从 API 接受初始请求时开始计算,仅适用于初始响应。每个符合条件的请求(包括后续请求)均可享受模型 Token 费率折扣。在此示例中,两个请求均享受 40% 的折扣。

发起后台请求

将 background 设为 true,并保存 API 返回的响应 ID。通过 webhook 获取请求完成通知,再按 ID 获取响应。本示例使用默认完成时限(soonest)。

在后台生成响应
from openai import OpenAI

client = OpenAI()

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

print(resp.status)

即使将 store 设为 false 或使用零数据保留,后台模式仍会临时存储响应数据。API 使用这些数据来执行请求,并提供结果供后续获取。对于所有完成时限(soonest、2h 和 8h),API 都会对临时存储的请求内容进行静态加密。有关临时存储的详情,请参阅数据控制。

通过 webhook 接收结果

  1. 为发送后台请求的项目创建 webhook 端点。订阅 response.completed,并按需订阅与失败、未完成或已取消的响应对应的事件。
  2. 对收到的事件验证签名。将耗时较长的工作交给后台工作进程,接受事件后立即返回 2xx 响应。
  3. 对于 response.completed 事件,使用 event.data.id 获取响应。其他终态事件按应用的工作流处理。

Webhook 指南提供了一个验证签名并获取已完成响应的服务端示例。如果无法接收 webhook,请使用响应 ID 轮询响应。

API 接受 2h 或 8h 请求后,如果遇到可重试的容量错误,会自动重试。当响应处于 queued 或 in_progress 状态时,请等待 webhook,或使用同一个响应 ID 轮询。

使用享受折扣的完成时限

从 GPT-6.2 Astra 和 GPT-6.2 Sol 开始,新模型在发布时不提供 Flex 处理(service_tier: flex)。对于耗时较长的 Responses API 请求,请在支持此功能的模型上使用标准服务层级,并选择享受折扣的完成时限。

享受折扣的完成时限目前在 GPT-6.2 Astra、GPT-6.2 Sol、GPT-6.1 Terra 和 GPT-6 Luna 上开放公测。

完成时限为 2h 或 8h 的请求与 Batch API 作业共用批处理与后台请求的速率限制。API 会在请求提交时统计输入 Token 数量。使用默认完成时限 soonest 的请求适用常规请求数和 Token 数限制。

如果应用可以等待初始响应,请使用 2 小时或 8 小时的完成时限。将 background 设为 true,并将 background_options.completion_window 设为 2h 或 8h。省略 stream 或将其设为 false。请参阅完成时限定价。

享受完成时限折扣的请求必须按标准服务层级处理。将 service_tier 设为 default 即可选择标准服务层级。使用 auto 时,只有 API 选择标准服务层级,请求才符合折扣条件。

即使提示词完全相同,未使用折扣时限的标准请求也无法复用由 2h 或 8h 后台请求创建的提示词缓存条目。

如需通过一次请求在夜间审查文档,请发送 8h 请求至 POST /v1/responses,使用 gpt-6.1-terra,并在 input 中传入文档内容。如果只需要一个响应,请省略 background_options.continuation_id。

如需使用默认完成时限,请省略 background_options.completion_window 或将其设为 soonest。

通过后续请求运行工作流

在夜间文档审查流程中,两次请求应使用同一个 API 项目。

  1. 要求 gpt-6.1-terra 按 ID 查找文档,并检查文档是否缺少所需审批。请在创建响应的请求中提出这一要求。将 background 设为 true,将 service_tier 设为 default,并将 background_options.completion_window 设为 8h。将 background_options.continuation_id 设为应用为本次运行指定的唯一 ID。在请求中提供一个可按 ID 获取文档的函数工具。保存 API 返回的响应 ID。
  2. 收到 response.completed webhook 时,请对重复投递的事件进行去重,去重依据是 webhook-id 请求头。确认 event.data.id 与保存的响应 ID 一致后,再继续处理。获取响应,并按其中的 function_call 输出项执行文档查找。如果应用可能需要在响应过期后继续运行,请在仍可获取响应时保存原始输入和完整的响应 output。
  3. 创建后续响应,沿用相同的模型、服务层级、后台设置、完成时限和续接 ID。如果上一条响应仍可获取,请将 previous_response_id 设为 event.data.id,以延续对话历史。在 input 中发送一个 function_call_output 项,使用原函数调用的 call_id,并将获取到的文档作为该项的 output。

复用 continuation_id,使后续请求有资格获得更高的队列优先级。实际开始时间取决于调度。如果上一条响应已过期,请省略 previous_response_id,并在 input 中传入对话历史。按原顺序重新传入原始输入和已保存的响应 output 中的每一项,包括其中的所有加密推理项和原函数调用。然后追加新的 function_call_output 项。

轮询后台响应

除了使用 webhook,您也可以使用响应 ID 调用响应获取端点,以查看请求状态。状态为 queued 或 in_progress 时,请继续轮询。进入终态后,停止轮询。

获取正在后台生成的响应
from openai import OpenAI
from time import sleep

client = OpenAI()

resp = client.responses.create(
    model="gpt-6.2-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 对象。要取消同步响应,请关闭连接。

流式接收后台响应

要流式接收后台响应,请使用默认完成时限(soonest),并在创建响应时指定 stream: true。对于 2h 和 8h 请求,请省略 stream 或将其设为 false。

如果连接断开,请将最后收到的事件的 sequence_number 作为 starting_after 传入,以恢复事件流。只有在创建响应时启用了流式传输,之后才能流式接收该响应。

后台响应的首个 Token 等待时间可能比同步响应更长。

在后台生成响应并流式接收事件
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-6.2-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"