`prompt_cache_options.ttl` is typed `Literal[“30m”]` but the API accepts and returns `”12h”`; `cache_write_tokens_details` is untyped

快速结论：这类报错通常发生在调用 Responses API 并设置 prompt_cache_options.ttl、同时用 mypy/pyright 做静态检查时：运行时请求和返回都支持 "12h"，但旧版 SDK 的类型只写了 "30m"，并且 cache_write_tokens_details 没有类型定义。优先升级 openai 到已包含修复的版本。

适用环境：Issue 已确认的环境为 macOS 15.7.9、Python 3.12.11、openai 3.36.1；类型检查器涉及 pyright 与 mypy 2.4.0。原始 Issue 未提供 CUDA、PyTorch、显卡信息。

最快修复方案：升级到 openai v3.45.0（修复由 #4240 合入并在该版本发布）。该版本已让请求和响应的 ttl 类型包含 "12h"，并为两种缓存寿命的写入用量提供带类型的字段。

注意事项：Issue 中只明确了“该修复在 v3.45.0 发布”，未逐一验证更早的补丁版本是否包含修复；若升级后仍报错，先确认实际安装版本与 import 路径。另外，手工修改生成的类型文件可能在下次重新生成时被覆盖，Issue 评论建议改动源 OpenAPI/schema 后重新生成，而不是直接手改。

问题场景

用户在 OpenAI Python SDK 中调用 client.responses.create(...)，传入 prompt_cache_options={"ttl": "12h"}，并在请求前用 mypy 或 pyright 做类型检查；运行时请求成功，响应中 prompt_cache_options.ttl 回显为 '12h'，但静态检查报参数类型不匹配。同时，代码访问 r.usage.input_tokens_details.cache_write_tokens_details 时，该字段在 SDK 类型中不存在，只能以普通 dict 形式拿到。

报错原文

repro.py:7:26 - error: Argument of type "dict[str, str]" cannot be assigned to parameter "prompt_cache_options" of type "PromptCacheOptions | Omit" in function "create"
    Type "dict[str, str]" is not assignable to type "PromptCacheOptions | Omit"
      "dict[str, str]" is not assignable to "PromptCacheOptions"
      "dict[str, str]" is not assignable to "Omit" (reportArgumentType)
repro.py:15:36 - error: Cannot access attribute "cache_write_tokens_details" for class "InputTokensDetails"
  Attribute "cache_write_tokens_details" is unknown (reportAttributeAccessIssue)

mypy 2.4.0:
error: No overload variant of "create" of "Responses" matches argument types "str", "bool", "dict[str, str]", "list[dict[str, str]]"  [call-overload]

mypy（改用 "30m" 后仍存在）:
"InputTokensDetails" has no attribute "cache_write_tokens_details"; maybe "cache_write_tokens"?  [attr-defined]

原因分析

这是 SDK 生成类型/ schema 与 API 实际行为不一致，而不是运行时请求失败。Issue 指出：请求侧 src/openai/types/responses/response_create_params.py 中 PromptCacheOptions.ttl 被定义为 Literal["30m"]，文档字符串还写着 30m 是唯一支持值；响应侧 src/openai/types/responses/response.py 同样只有 Literal["30m"]，但 API 会返回 "12h"。此外，InputTokensDetails 没有 cache_write_tokens_details 字段，因此 ttl_30m_tokens 与 ttl_12h_tokens 只能以未类型化的 dict 访问。

环境排查

确认 Python 版本：Issue 中为 3.12.11。
确认当前安装的 openai 版本：Issue 中出问题的版本为 3.36.1，修复版本为 v3.45.0。
确认静态检查工具及版本：Issue 使用 pyright 与 mypy 2.4.0。
确认报错位置：请求构造处是否使用 prompt_cache_options={"ttl": "12h"}；响应访问处是否读取 usage.input_tokens_details.cache_write_tokens_details。
原始 Issue 未提供 CUDA、PyTorch、显卡或节点配置，无需据此排查。

解决步骤

将 openai SDK 升级到 v3.45.0 或更高版本；该版本由 #4240 修复，并已明确包含本次类型修复。
升级后重新运行类型检查（pyright / mypy），确认 prompt_cache_options={"ttl": "12h"} 不再触发参数类型错误。
确认响应类型中 prompt_cache_options.ttl 可接受 "12h"，并且 usage.input_tokens_details.cache_write_tokens_details 具有 ttl_30m_tokens、ttl_12h_tokens 字段，可正常以属性方式访问。
如果你在仓库内自行维护 SDK 类型，可优先按 Issue 评论建议修改源 OpenAPI/schema 后重新生成类型文件，而不是直接手改生成代码，避免再次生成时被回退；可优先尝试补充回归测试，验证 "12h" 可类型检查且响应解析出 ttl_12h_tokens。

验证方法

升级后重新执行原复现脚本，并用 pyright / mypy 做类型检查：请求中的 ttl="12h" 不再报参数类型错误；响应打印出的 prompt_cache_options 中 ttl='12h' 正常；r.usage.input_tokens_details.cache_write_tokens_details 不再是未类型化的普通 dict，而能通过带类型的 ttl_30m_tokens、ttl_12h_tokens 字段访问。运行时行为原本即可成功，所以关键验证点是静态类型检查不再报错。