openai-python 3.32.0 与 openai-node 7.35.0 更新解读：prompt 建声、Live 音频夹具与 Live Decisions

2026-10-16，两包官方 SDK 又一次同日发版：openai-python v3.32.0（20:17 UTC）与 openai-node v7.35.0（20:16 UTC）（时间出自两包 GitHub Releases，本站 2026-10-17 抓取核对）。上一批（10-14 的 browser/computer toolsets，标注 1/4）之后，这一批把语音与 Live 会话的能力面往前推了一大步：语音可以用一段文字描述直接创建，Live 会话可以播放预制音频夹具，Decisions 问题评估接进了 Live 的转写触发器，Decisions API 自己也拿到了 prompt caching。本文按惯例只写两包 CHANGELOG 与 v3.32.0 / v7.35.0 tag 源码里能指出的东西。

prompt 建声：一段文字描述生成语音，但只在 Live 可用

这是本批的头条。voices.create 原来只有一条路径——上传音频样本加同意录音；v3.32.0 / v7.35.0 起它变成双形态，新增 type: "prompt" 变体。v3.32.0 tag 的 voices.py 文档串原文：

For prompt-based creation, send type: "prompt" with a name and prompt as JSON or multipart form data.

参数面（python 与 node 两侧类型定义一致）：

• name（必填）：新语音的名字
• prompt（必填）：目标语音的文字描述，不能全是空白字符
• type（必填，字面量 prompt）
• model（可选）：语音创建模型，默认 auto，字面量另一值为 2026-10-08
• script_hint（可选）：创建时让语音念的台词；不给就由 prompt 自动生成，台词修剪空白后不能为空、过短会被拒收

voice = client.voices.create(
    name="brand-narrator",
    type="prompt",
    prompt="A calm mid-range adult voice, unhurried pace, "
           "soft studio tone with clean consonants",
)

返回的 Voice 对象有两处扩展：type 从单值 audio_sample 扩为 audio_sample | prompt，并新增可选 prompt 字段——按文档串，只有存了原始 prompt 的 prompt 建声才带这个字段，audio_sample 语音和没存 prompt 的旧语音都没有。

边界同样写在文档串里，而且写了三遍（voices.py、speech_create_params.py、Realtime 的音频输出配置）：Voices created from text prompts are supported only in Live, not in Realtime or the speech endpoint. 另外，响应不含预览音频（The response does not include preview audio）。

Live 音频夹具：一次一段、至多 30 秒的输出插播

Live 会话新增客户端事件 session.output_audio.fixture.play，把一段完整的预制音频从会话输出通道播出去。类型文档串把约束写得非常具体：

Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active.

规则拆开是：音频必须是 base64 编码的裸 PCM16、单声道、小端、24 kHz，不带 WAV 等容器头，也不管会话音频格式是什么；至多 30 秒；服务端先校验整个载荷，通过之后才打断模型语音并静音输入；同一时刻只允许一个夹具在播。两个配套服务端事件——fixture.playing 确认受理、fixture.played 报告服务端混音器排空——官方明确它们不是精确的传输媒体边界。播放期间到达的输入被丢弃，且不重放。

该事件既可以从主 WebSocket 发，也可以从 server sideband 发。

Live Decisions：转写触发器、decisions 委派与共享 Decision 项

Decisions（问题评估）这一批接进了 Live 会话，共四块：

触发器（triggers）：session 配置新增 triggers 数组，每个元素是一组绑定到转写事件类型的问题。event_type 只有两个字面量：session.input_transcript.delta 与 session.output_transcript.delta，且每个转写事件类型至多一个触发器。问题三种形态，按 type 判别：

官方同时写明：triggers 独立于 delegation 运行；更新会话时省略 triggers 保持现状、传列表整体替换、传空列表停用。

decisions 委派：delegation 联合在"你的应用"与 responses 之外新增 type: "decisions"，配置是 model + questions（同一套三型问题）。文档串相应从"use responses to let the API manage a Responses backend"改为"use responses or decisions to delegate to the corresponding API"。

Decision 项事件：decision.item.create / decision.item.created / decision.item.delete / decision.item.deleted 四个事件，用于给"未来的评估"追加或移除输入项——文档串原话是 Append an input item for future decisions without starting an evaluation or changing Live voice context。条目是 user 角色消息，content 可以是字符串或 input_text / input_image 部件列表（图片走内联 data URL，detail 支持 low / high / auto / original，默认 auto）。

启动历史限额措辞：session 的 input（启动前注入的纯文本历史）文档串从"至多 128 条消息与合计 8,192 渲染 token"改为"至多 128 条消息与一个可配置的渲染 token 上限（默认 8,192）"——上限从写死变成可配置，这与 node #2949 的 chore 条目 clarify the Live startup history token limit 相互印证。

Decisions API 拿到 prompt caching

独立的 Decisions API（client.decisions.create）本批新增 prompt_cache_key 与 prompt_cache_options 两个参数（python #4087，标题自带 [2/2] 标注；node #2956 无分段标注）。PromptCacheOptions 的文档串与 Responses 侧规则一致：仅 gpt-5.6 及以后的模型支持；默认 implicit 模式自动建一个隐式断点、至多再写最近三个显式断点，explicit 模式不建隐式断点、至多写四个显式断点（没有显式断点就不走缓存）；ttl 默认 30m、也是当前唯一支持值；缓存匹配考虑会话最近 80 个断点。

断点落在内容块上：input_text / input_image 块新增可选 prompt_cache_breakpoint（mode 恒为 explicit），文档串写明它标记可复用前缀的精确结尾、TTL 继承请求的 prompt_cache_options.ttl、边界不做 token 块取整。

错误诊断与 Realtime 错误消息

response.error 对象（Responses、beta Responses 与 videos 三处同批）新增两个可空字段：

• param：The request parameter associated with the error, or null if none was recorded
• type：The original error type, or null if it was not recorded

Realtime 侧，response status 里的 error 对象补上了可空的 message（A human-readable error message）。新增的 SDK 测试对三条路由（responses / beta / videos）逐一断言了 type、param、code、message 的回读。

项目 API key：scope 与过期解耦更新

项目 API key 的 update 操作本批解锁了 scope 修改（python api_keys.py 与 node #2943 同步）。要点全部来自类型文档串：

• scopes 与 expires_in_seconds 现在都是可选，但至少提供一个；省略的字段保持不变；两个字段都不接受 null；两处修改一起保存
• scopes 用与控制台相同的 scope 标识符整体替换 key 的权限限制；空数组含义是 All permissions（仍受属主实际有效权限约束）——不是收回全部权限；只读用 ["api.all.read"]，细粒度如 ["api.files.read"]
• 改 scope 不改变属主（用户或 service account）的角色，也不授予管理权限
• scope 变更与控制台编辑走同一套鉴权缓存传播（不承诺立即全端点生效）

其余：python 补齐 residency、弃用注解与 WS 重构

• regional processing residency：python 的项目 residency 枚举新增 JP_STORAGE_PROCESSING、IN_STORAGE_PROCESSING、AU_STORAGE_PROCESSING（#4081）——node v7.34.0（#2942，10-14）已有该特性，python 侧至此补齐。
• ChatModel 弃用注解：两包同批把 gpt-5.4-nano 与 gpt-5.1 标上 Announced shutdown date: 2027-04-01，并把 gpt-4.1 / gpt-4o 系列并入 2027-01-14 行（python 注解含未带日期别名，node 侧只列带日期快照）。官方弃用页已给出替代建议：gpt-5.4-nano 迁 gpt-6-luna、gpt-5.1 与 gpt-5.3-codex 迁 gpt-6-sol。逐条解读见同批的《OpenAI 2026 年 10 月弃用潮：GPT-4o 与 GPT-4.1 家族 2027-01-14 关停、TTS 四件套转投 gpt-realtime-2.1-mini》。
• WebSocket 重构：python 新增共享模块 _websocket_connection.py（#4084，share WebSocket connection handling）；node 侧对应两条 refactor（#2947 share existing WebSocket send and open handling、#2953 share WebSocket connection lifecycle and generated bindings）。纯内部重构，两包 CHANGELOG 均未声明行为变化。

对谁有用

• 做 Live 语音智能体的团队：夹具给了确定性的输出插播能力（提示音、确认音、短广告位），30 秒上限与单夹具约束适合做成播放队列；Decisions 触发器让"每句话都在被打分"的合规与质检场景不必再自建转写轮询。
• 要在语音里用定制音色的产品：prompt 建声把音色定制的门槛从"录样本 + 录同意书"降到一段文字描述，但注意它只在 Live 可用——TTS 与 Realtime 场景仍走 audio_sample。
• 管 API key 治理的平台团队：scopes 与过期解耦后，轮换密钥不再被迫重设过期时间，缩权也不再需要删了重建。
• 用 Decisions API 做批量评估的团队：固定前缀（评审手册等）配 prompt_cache_key + 显式断点可以压重复输入成本，规则与 Responses 缓存一致。

下一步

• 上一批 SDK 解读见《OpenAI SDK 新增 Browser/Computer 工具集（1/4）：BrowserToolset 把驱动方法变成 Responses 函数工具》。
• Live API 的通道与通话控制基础见《Live API 现身 OpenAI SDK：gpt-live-1、WebRTC/WebSocket 双通道与 SIP 通话控制解读》。
• prompt caching 的完整打法（断点、key、诊断）见《openai-python 3.9 / 3.10 与 openai-node 7.11 / 7.12 更新解读：prompt cache 诊断、API key 过期与 GPT Image 2.5》与《OpenAI 官方 Agent 优化 Cookbook 解读：客服智能体的四轮降本方法论》。
• 本批弃用注解背后的整波弃用公告，见《OpenAI 2026 年 10 月弃用潮：GPT-4o 与 GPT-4.1 家族 2027-01-14 关停、TTS 四件套转投 gpt-realtime-2.1-mini》。