Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

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

未关闭 适合新手
  • 哪里不对？
#4,156 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
78/100
Issue 类型
缺陷
描述清晰度
描述清楚
活跃度
活跃
技术栈
python
领域
backend-api-design

调研方向

阅读 src/openai/types/responses/response_create_params.py 和 src/openai/types/responses/response.py，查看请求和响应的 TTL 类型，然后查找 InputTokensDetails 及其测试。更新类型和 docstring，使其符合文档中记载的 30m 和 12h 值，并添加类型化的缓存写入 token 详情。完成标准是：类型检查接受所报告的请求和响应字段，并且测试覆盖两种 TTL 和 token 详情字段。

由索引模型根据 Issue 内容生成。

描述

Confirm this is an issue with the Python library and not an underlying OpenAI API
  • This is an issue with the Python library
Describe the bug

The prompt caching guide documents prompt_cache_options.ttl as "30m" or "12h" for the Responses API (12-hour caching, changelog 2026-10-20), and the API accepts "12h". The SDK types do not:

  1. Request: PromptCacheOptions.ttl in src/openai/types/responses/response_create_params.py is Literal["30m"], so mypy and pyright reject a request that succeeds at runtime. The docstring also still says 30m "is currently the only supported value".
  2. Response: Response.prompt_cache_options.ttl in src/openai/types/responses/response.py is also Literal["30m"], but the API returns "12h".
  3. Usage: the API returns usage.input_tokens_details.cache_write_tokens_details (ttl_30m_tokens, ttl_12h_tokens), but InputTokensDetails has no such field, so it is only reachable as an untyped dict.

Draft PR #4144 adds "12h" to prompt_cache_breakpoint.ttl, but as of its current head it leaves the request-level PromptCacheOptions.ttl as Literal["30m"] and does not add cache_write_tokens_details.

Expected

  • PromptCacheOptions.ttl: Literal["30m", "12h"] (request and response)
  • a typed cache_write_tokens_details with ttl_30m_tokens / ttl_12h_tokens
To Reproduce
  1. Run the snippet below. The request succeeds and the response echoes ttl='12h'.
  2. Type-check it with pyright: 
    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 reports error: No overload variant of "create" of "Responses" matches argument types "str", "bool", "dict[str, str]", "list[dict[str, str]]" [call-overload] on the same call.
  3. Change "12h" to "30m": the first error goes away. The cache_write_tokens_details error remains ("InputTokensDetails" has no attribute "cache_write_tokens_details"; maybe "cache_write_tokens"? [attr-defined]).
Code snippets
from openai import OpenAI

client = OpenAI()
r = client.responses.create(
    model="gpt-6-luna",
    store=False,
    prompt_cache_options={"ttl": "12h"},
    input=[
        {"role": "developer", "content": "<prefix of 1,024+ tokens>"},
        {"role": "user", "content": "hi"},
    ],
)
print(r.prompt_cache_options)
# PromptCacheOptions(mode='implicit', ttl='12h', comparison_response_id=None)
assert r.usage is not None
print(r.usage.input_tokens_details.cache_write_tokens_details)
# {'ttl_12h_tokens': 3465, 'ttl_30m_tokens': 0}  <- plain dict
OS

macOS 15.7.9

Python version

Python v3.12.11

Library version

openai v3.36.1

主要语言
Python
星标
31.9k
派生
8k
平均合并
16 小时 38 分钟
30 天内合并 PR
170

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

openai/openai-python 的其他 Issue

查看 openai/openai-python 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。