openai-python 3.40/3.41 与 openai-node 7.45.1 更新解读：缓存断点 TTL 语义、响应级工具用量与 Realtime item 引用

openai-python v3.40.0 与 v3.41.0、openai-node v7.45.1 在 2026-10-27 与 10-28 两天内接连发布：python 侧把 prompt cache 断点的 TTL 继承语义定稿，并落地四个新面（响应级托管工具用量、Realtime item 引用、sessions metadata 过滤、WS 重连队列保留二进制帧）；node 侧同步 TTL 措辞并放宽 vertex provider 的 google-auth-library 兼容范围。本文全部参数名与枚举值取自两仓 tag 源码（2026-10-31 核对），不凭 release notes 标题推断。

1. 版本与上架状态

openai-python v3.40.0 与 openai-node v7.45.1 同分钟发布（两仓 CI 同步），PyPI 上能直接装到的是 v3.41.0。node 侧本批只有 v7.45.1 一个点版本，v7.45.0（10-26）的 feature 面（scheduled automations、gpt-6.1-terra 等）已见于《OpenAI 模型更新日志（2026 持续更新）》的 2026-10-26 条目，本文不重复。

2. 缓存断点 TTL：字段在 10-26，语义在 10-27

这条故事分两段，单看任何一个版本的 release notes 都容易读偏：

第一段（字段）：断点级 ttl 字段首见于 python v3.38.0（2026-10-26）——PromptCacheBreakpoint 里出现 ttl: Literal["30m", "12h"]，紧邻前一版 v3.37.0 的同一文件没有这个字段。

第二段（语义）：v3.40.0 的 #4188 标题是「add prompt cache breakpoint TTL options」，但对类型层的实际改动只有文档措辞：把「断点继承请求 TTL」改成**「When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl」**——只有断点自己没写 ttl 时才继承请求级设置。node 侧 v7.45.1 的 #3057 在 responses、beta responses、chat completions、conversations 四处资源文件同步了同一措辞。

v3.41.0 tag 上的断点参数定义（src/openai/types/responses/response_input_text_param.py，逐字摘录）：

class PromptCacheBreakpoint(TypedDict, total=False):
    """Marks the exact end of a reusable prompt prefix.

    When `ttl` is omitted, the breakpoint inherits the request's
    `prompt_cache_options.ttl`; the boundary is not rounded to a token block.
    """

    mode: Required[Literal["explicit"]]
    """The breakpoint mode. Always `explicit`."""

    ttl: Literal["30m", "12h"]
    """The minimum lifetime of this cache breakpoint. Defaults to the request TTL."""

同时注意请求级没有扩围：PromptCacheOptions.ttl 在 v3.41.0 仍是 Literal["30m"]，官方文档串原文「The ttl defaults to 30m, which is currently the only supported value」。也就是说，12h 目前只存在于断点级覆盖：请求级保持 30m，给个别关键断点单点写 ttl: "12h"，是当前类型层允许的用法。

3. Response.tool_usage：托管工具用量单独记账

v3.41.0 的 #4201 在 Responses 响应对象（含 beta 变体）上新增 tool_usage: Optional[ToolUsage]。官方文档串把定位写得很清楚：「Usage reported by hosted tools, separate from base model usage」——与 base model 的 usage 并列、互不包含；不可用时整个字段省略，出现时没用量记录的工具族计零。

两个工具族的结构（按 tag 类型文件整理）：

{
  "tool_usage": {
    "image_gen": {
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "cached_tokens": null,
      "input_tokens_details": { "image_tokens": 0, "text_tokens": 0 },
      "output_tokens_details": { "image_tokens": 0, "text_tokens": 0 },
      "cached_tokens_details": { "cached_image_tokens": 0, "cached_text_tokens": 0 }
    },
    "web_search": { "num_requests": 0 }
  }
}

三条官方语义边界值得原文照录：image_gen 是「sums available token counts across image generation calls」，用量记录缺失或不完整的调用可能被跳过，输出明细与缓存计数可省略——省略的缓存计数意味着缓存使用情况未知；web_search.num_requests 只数计费搜索——折扣搜索与「打开页面」之类的动作不计入；官方最后一句：最终费用以账单记录为准（Use billing records to reconcile final charges）。

对做成本观测的人来说，这让你能从单个响应对象直接读到托管工具的用量聚合，而不必按工具调用逐条累加——但「聚合可能缺项」这条边界决定了它适合做观测，不适合直接做计费口径。

4. Realtime：用 item_reference 引用既有会话项

#4189 给 Realtime 的 response.create 输入加了类型化引用。新类型 ResponseItemReferenceParam 只有两个字段：type: Literal["item_reference"] 与 id: Required[str]（「The ID of an existing item in the same Realtime session」）。类型文件的限制句值得原文照录：「Item references are only accepted in the response input array, not as new conversation items」。

WithReferences 变体的 input 字段类型是 Iterable[Union[ConversationItemParam, ResponseItemReferenceParam]]——普通会话项与引用项可以混排（按 tag 类型文件整理的示例）：

event = {
    "type": "response.create",
    "response": {
        "input": [
            {"type": "item_reference", "id": "item_123"},
        ]
    },
}
connection.send(event)  # send() 联合已接受 WithReferences 变体（sync/async 同步扩展）

配套地，sync 与 async 两条 WebSocket 连接的 send() 方法联合类型都扩展为同时接受 ResponseCreateEventWithReferencesParam——不改这处的话，带引用的事件在类型检查层过不去。

5. agents sessions 列表：按 metadata 精确过滤

#4200 给 client.beta.agents.sessions.list 加了 metadata 过滤参数（SessionListParams.metadata: Dict[str, str]）。官方文档串的约束逐条是：以 metadata[key]=value 形式做精确字符串匹配；所有给出的键值对都必须命中；至多 16 对；键 1-64 字符、值至多 512 字符；新会话与 metadata 更新进入过滤结果可能有延迟。

page = client.beta.agents.sessions.list(
    metadata={"team": "platform"},
    limit=50,
)  # SyncCursorPage[AgentSession]；另有 agent_id 过滤与 after 游标

注意这是「过滤」不是「搜索」：精确匹配、全对命中、无模糊查询；把 metadata 当全文索引用会得不到预期结果。最终一致性那句原文也决定了它不适合做「刚创建就立刻要查到」的强一致场景。

6. WebSocket 重连队列：二进制帧不再被解码

#4191 重写了重连发送队列的帧类型处理。改动前，重连期间的出站帧统一按字符串排队——二进制帧先被强制 UTF-8 解码；改动后 SendQueue 直接保留 str | bytes 原类型，二进制帧原样入队、重连后原样发送。

连接最终仍关闭时抛出的 WebSocketConnectionClosedError 有三个值得知道的行为：

• 新增 unsent_frames 属性：按原始顺序保留文本与二进制帧；
• 既有 unsent_messages 保留为文本兼容视图：UTF-8 可解码的二进制转成文本，解不开的「opaque binary」只存在于 unsent_frames；
• 异常的常规属性快照做了脱敏——恢复数据对象 __repr__ 输出 <redacted WebSocket recovery data>，防止二进制内容被日志系统顺手打印。

做实时语音或二进制协议桥接的应用，此前如果自己兜底「重连前把 bytes 转 str」，本批之后可以直接交给 SDK 的队列。

7. 弃用注解：translations 端点、模型注释与图像文档

#4199「document upcoming model shutdowns」把一批既有关停事实写进了 SDK 层，其中一条是新的端点级弃用：

/v1/audio/translations 端点标弃用。audio.translations.create 方法（含各重载）在 python v3.41.0 带上 typing_extensions.deprecated 标注（SDK 自带测试同步改为预期 DeprecationWarning）。文档串原文：「This endpoint supports only whisper-1. The endpoint and model are deprecated and scheduled to shut down on February 26, 2027. Migrate to /v1/realtime/translations, which requires a separate integration.」——端点仅支持 whisper-1、2027-02-26 与转写四件套同日关停、迁移目标是 Realtime 侧的 translations 端点且官方明说需要单独集成。

ChatModel 2027-04-01 弃用行扩为四值：在原有两值（gpt-5.4-nano、gpt-5.1）基础上加入日期快照 gpt-5.4-nano-2026-03-17 与 gpt-5.1-2025-11-13；gpt-5.3-codex 仍不在这行注解里——官方弃用页 2026-10-31 当日核对仍把它列在 2027-04-01 行（替代 gpt-6-sol），SDK 注解与弃用页清单不一致是现状。

图像模型文档串刷新（#4198）：gpt-image-1 从「GPT image 模型」输入约束清单中移除（与其 2026-10-23 关停一致），chatgpt-image-latest 改为单独一句「follows the same input constraints as GPT image models」；quality 参数「仅支持 low」的措辞同步改为只提 gpt-image-1.5。

node 侧唯一的另一个改动是 #3046：vertex provider 的 google-auth-library peer 依赖范围从 >=9.15.1 <11 放宽到 >=9.15.1 <12（v7.45.0 与 v7.45.1 的 package.json 对照核实）——Google 侧 auth 库升 v11 的项目不再被 peer 依赖卡住。

8. 升级建议与常见坑

• 从 v3.39.x 升 v3.41.0 是纯增量：本批四个 feature 均为新增面，对既有签名的改动只有联合类型扩宽这类增量（如 #4189 的 send() 接受新变体）；v3.40.0 对类型层也只有文档措辞。
• 别照 release notes 标题写文章：「add prompt cache breakpoint TTL options」的实际 diff 是措辞刷新——本文第 2 节的两段式时间线（10-26 字段、10-27 语义）以 tag 源码对照为准。
• tool_usage 缺项是常态：聚合可能跳过用量记录不完整的调用、缓存计数可省略——拿它做观测可以，做计费口径必须按官方那句「以账单记录为准」。
• translations 迁移有集成成本：官方原话 requires a separate integration——不是改个端点字符串就行，排期时按新集成评估。
• node 用户：只需要 TTL 措辞与 google-auth-library v11 兼容的话，v7.45.1 即可；本批其余新面（tool_usage、item_reference、sessions metadata 过滤、WS 二进制帧队列）截至 v7.45.1 未出现在 node release notes。

9. 下一步

• 上一批 SDK 面（prompt 建声、Live 音频夹具、Decisions 与 prompt caching）见《openai-python 3.32.0 与 openai-node 7.35.0 更新解读：prompt 建声、Live 音频夹具与 Live Decisions》。
• 缓存预热（prewarm）与显式断点的入门语义见《openai-python 3.15 / 3.16 与 openai-node 7.18 / 7.19 更新解读：缓存预热、Webhook 管理与 connector_id 弃用》。
• 本批 sessions 过滤所在的 agents 会话体系背景见《OpenAI SDK 出现托管 Agent 环境资源：prewarmed 预热创建、闲置挂起与过期事件》。
• vertex provider 与 google-auth-library 的接入细节见《OpenAI 模型登陆 Google Cloud：Vertex AI 上的 Responses API 与 SDK vertex() 接入》。