openai-python 3.9 / 3.10 与 openai-node 7.11 / 7.12 更新解读：prompt cache 诊断、API key 过期与 GPT Image 2.5

2026-09-08 前后两天，OpenAI 的两个官方 SDK 密集发了四个版本（Node 侧还有一个补丁），09-09 晚间又追加了一对 key 过期治理版本（v3.11.0 / v7.13.0），09-10 晚间再追加两对——Live API（v3.12.0 / v7.14.0）与 Agents API（v3.13.0 / v7.15.0），是这波里仅有的两个全新资源面。前面几个版本里最有价值的是 prompt cache 诊断——缓存没命中时终于能拿到"为什么没命中"的结构化原因；其余还包括 Service Account API key 的过期字段及其后续的 policy 治理升级、GPT Image 2.5 的模型类型，以及一批 429/503 响应的文档化。本文事实逐条对照当日可重抓的 GitHub release notes 与 SDK 源码（引用清单见文末）；OpenAI 官方文档域对本站 403（最近一次可访问为 2026-09-01，2026-09-11 复核仍不可访问），涉及官方文档侧的状态一律不做超出本次核验的断言。

1. 版本概览

注意两包的版本号并不一一对应：key 过期字段在 Python 侧落在 v3.10.0、在 Node 侧落在 v7.11.0；key 过期治理升级在 Python 侧落在 v3.11.0、在 Node 侧落在 v7.13.0。而 09-10 晚间的两对是对齐发布：Live API 同在 python v3.12.0 / node v7.14.0（相差 1 分钟），Agents API 同在 python v3.13.0 / node v7.15.0（同一分钟）。Node 侧 09-09 还有 v7.12.1 补丁（2026-09-09 01:15 UTC，把 v7.12.0 的 GPT Image 2.5 支持补发上 npm）与若干 CI 修复，本文不展开。

2. prompt cache 诊断：终于能问"为什么没命中"

2.1 机制

v3.9.0 起，responses.create 的 prompt_cache_options 里新增 comparison_response_id（字符串，上一条请求的 response ID）。SDK 原文：Supplying this field requests prompt cache diagnostics when the feature is enabled——填了它，本次请求就会附带与那条历史请求的缓存对比诊断。诊断结果出现在响应对象的 prompt_cache_diagnostics 字段，是一个带判别值的联合类型：

• cache_hit：可复用前缀命中；
• cache_miss：未命中，附三个信息——reason（九种枚举）、cache_missed_tokens（首次分叉后受影响的输入 token 估计数）、可选的 comparison_reusable_tokens（对比请求中可复用前缀的原始 token 数）；
• comparison_response_not_found：给的 response ID 找不到；
• unavailable：诊断不可用。

九种 miss reason 值得整表收藏，基本覆盖了日常"缓存怎么又没命中"的全部场景：

配套的类型文档也把 prompt caching 的几个关键数字写死了：prompt_cache_options 仅支持 gpt-5.6 及以后模型；mode 默认 implicit（自动写 1 个隐式 breakpoint，另可写最近 3 个显式 breakpoint），设为 explicit 则不写隐式、最多写 4 个显式；缓存匹配考虑会话中最近 80 个 breakpoints；ttl 目前仅 30m 一档。客户端事件枚举里同步出现了 prompt_cache_key_changed 事件，与 miss reason 同名。

2.2 代码

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-5.6-terra",
    input="总结这段部署纪要的三个关键结论",
    prompt_cache_key="deploy-notes-2026-09",          # 原有能力：稳定缓存键
    prompt_cache_options={
        "comparison_response_id": "resp_abc123",      # v3.9.0 新增：上一轮 response ID
    },
)

diag = resp.prompt_cache_diagnostics                  # Optional[PromptCacheDiagnostics]
if diag is not None and diag.type == "cache_miss":
    print(diag.reason, diag.cache_missed_tokens)

这段代码是 SDK 源码核对版（对照 v3.9.0 的参数类型定义逐字段核对），未在真实 key 下实跑。

3. Service Account API key 过期字段

v3.10.0（Python 侧）给 admin 面板下的 Service Account API key 增加了过期语义：

• 请求侧：api_keys.create 新增可选 expires_in_seconds（秒数）；
• 响应侧：返回对象新增 expires_in_seconds（"Number of seconds until the API key expires"）与 expires_at（Unix 时间戳，永不过期为 null）。

key = client.admin.organization.projects.service_accounts.api_keys.create(
    service_account_id="sa_xxx",      # 占位示例
    project_id="prj_xxx",             # 占位示例
    name="ci-runner-key",
    expires_in_seconds=60 * 60 * 24 * 90,   # 90 天
)
print(key.expires_at, key.expires_in_seconds)

对 CI / 自动化场景是实打实的好消息：以前 service account key 默认长期有效，泄露后的爆炸半径靠轮换纪律兜底；现在可以把过期时间写进创建调用里。注意这批字段只出现在 Service Account 的 key 上——用户 API key 是否支持过期，SDK 类型里没有对应变化，不要外推。

数小时后，这组字段在 v3.11.0 / v7.13.0（两包均 2026-09-09 15:30 UTC 前后发布）里完成了一次质变：expires_in_seconds 加上 1..31536000 秒（365 天）的硬边界；语义从"可选字段"升级为"policy 治理"——组织或项目级过期策略可以强制 key 过期、可以设最大生命周期（此时必须传值且不得超限），且与 create_service_account_only: true 互斥。这部分展开见本站《OpenAI API key 过期策略详解：expires_in_seconds、组织级 policy 与自动化密钥治理》。

4. GPT Image 2.5 类型落地

v3.10.0（Python）与 v7.12.0（Node）把 GPT Image 2.5 双模型（gpt-image-2.5-sunburst / gpt-image-2.5-flare，各含 -2026-09-08 快照）写进了模型枚举，并调整了图像选项：quality 新增 xhigh / max，透明背景在 2.5 上不再带 preview 标注，任意分辨率规则随参数文档更新。这部分展开见本站《GPT Image 2.5 解读：sunburst / flare 双模型、xhigh-max 质量档与任意分辨率》，本文不重复。

5. 09-10 晚间追加：Live API 与 Agents API

三天批次的最后一天（09-10）晚间，两包各发两版，落了两个全新的 API 资源面，各自有专文拆解：

• Live API（python v3.12.0 / node v7.14.0，17:28 / 17:29 UTC）：client.live 命名空间，POST /live/sessions 提交 WebRTC SDP offer 建 live 会话、connect() 走 WebSocket 直连；sessions 子资源带 accept / reject / hangup / refer 四个 SIP 通话控制端点（accept 的 SDK 原文是 Accept an incoming SIP call）与 fork、download_recording；sideband 可附着到既有会话。会话配置的 model 字段出现新字面量 gpt-live-1——它没有进入 ChatModel 枚举，也不是官宣模型。详见《Live API 现身 OpenAI SDK：gpt-live-1、WebRTC/WebSocket 双通道与 SIP 通话控制解读》。
• Agents API（python v3.13.0 / node v7.15.0，19:37 UTC 同分钟）：beta 命名空间 client.beta.agents，但 HTTP 端点是顶层 /agents 与 /vaults。四层资源面：可复用 Agent 的 CRUD（service_tier 五档枚举）、Managed Agents session（状态机 idle / in_progress / requires_action / failed）、执行环境（templates / files / skills / plugins）、凭据 vaults。详见《Agents API 现身 OpenAI SDK（beta）：/agents CRUD、environments、sessions 与 vaults 全景》。

两个资源面截至 2026-09-11 均无可用性与定价公告（官方文档域对本站 403），生产系统以观望为主。

6. 其余修正与文档化改动

• 函数参数补全事件字段修正（openapi-545）：v3.9.0 修正了 function argument completion 相关事件的字段定义。release notes 只到这一句；受影响的下游是按事件字段解析流式 function call 进度的代码，升级后建议回归一遍事件解析。
• 接受 incomplete web search call 状态：web search call 的状态枚举扩展，可以表达"未完成"的中间态。如果你的代码对状态做穷举 switch，记得兜住新值。
• refuse overflowing server retry delays：当服务器返回的 retry-after 值大得离谱时，SDK 不再按它等待（避免整夜挂起重试），改为报错。
• 429 / 503 响应文档化：SDK-235 把限流（429，含 TooManyRequests / InferenceRateLimited 形态）与过载（503，InferenceServiceUnavailable）响应写进了 API 规范描述——错误处理分支从此有据可依。
• Node 侧修复（v7.11.0）：assistants 终态 message 快照保留、audio 录制进程信号等，属于 SDK 自身质量修复，与 API 语义无关。

7. 升级建议

• 用 prompt caching 的生产服务：升 Python ≥ v3.9.0 / Node ≥ v7.11.0，给主链路加上 comparison_response_id 诊断。命中率突然下滑时，九种 reason 直接告诉你是哪个配置漂了——这比对着面板猜快得多。
• 有 Service Account key 的团队：升 Python ≥ v3.11.0 / Node ≥ v7.13.0（覆盖基础字段 + policy 治理语义），新 key 一律带 expires_in_seconds，存量 key 按轮换计划重发并盘点 expires_at 为 null 的存量 key。确认 organization / projects admin 权限的调用方代码同步升级。
• 图像生成管线：想试 2.5 再升 Python ≥ v3.10.0 / Node ≥ v7.12.0，不急则维持现状（gpt-image-2 未弃用）。
• 所有升级：先过一遍 CI 里的错误处理分支——这批把 429/503 的形态写进了规范，正是收紧重试与退避策略的时机。

prompt caching 的完整机制与成本账，见本站《Responses API 高级实战：structured outputs / 流式 SSE / Batch / prompt caching》；时间线视角的模型与 API 变动，见《OpenAI 模型更新日志（2026 持续更新）》。

8. 下一步

• 《Responses API 压缩进度事件解读：response.compaction.compacting、compaction_trigger 与长会话上下文压缩》：09-16 node v7.17.0 的压缩进度事件深度拆解。
• 《openai-python 3.14.x 与 openai-node 7.16 / 7.17 更新解读：流式错误规范化、WebSocket 背压与 SSE 兜底》：本系列 09-14 至 09-16 的后续批次。
• 《Live API 现身 OpenAI SDK：gpt-live-1、WebRTC/WebSocket 双通道与 SIP 通话控制解读》：09-10 落地的全新实时会话接口面。
• 《GPT Image 2.5 解读：sunburst / flare 双模型、xhigh-max 质量档与任意分辨率》：本批图像侧更新的完整拆解。
• 《OpenAI API key 过期策略详解：expires_in_seconds、组织级 policy 与自动化密钥治理》：key 过期治理升级（v3.11.0 / v7.13.0）的完整拆解与运维清单。
• 《gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读》：本批之前一周（09-03）SDK 类型层的另一批重大变化。
• 《Responses API 高级实战：structured outputs / 流式 SSE / Batch / prompt caching》：prompt caching 机制与计费影响。
• 《OpenAI 模型更新日志（2026 持续更新）》：所有发布的时间线。
• 《OpenAI API 错误处理与重试：401/429/5xx 实战模式》：429/503 的重试与退避策略落地。