这里只记录 response api 区别于 chat completions 的一些特性。

text.verbosity 参数

Responses API 里新的文本配置可以控制啰嗦程度。
可选 low、medium、high，低值更简洁，高值更详细。

{  
"text": {  
"verbosity": "low"  
}  
}

text.format 格式控制参数
默认普通文本 在这里可以开JSON schema

{  
"text": {  
"format": {  
"type": "text"  
}  
}  
}

开JSON SCHEMA

{
  "text": {
    "format": {
      "type": "json_schema",
      "name": "summary_result",
      "schema": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "summary": {"type": "string"},
          "tags": {
            "type": "array",
            "items": {"type": "string"}
          }
        },
        "required": ["title", "summary", "tags"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

老版本还有 json_object：旧版 JSON mode，只保证合法 JSON

instructions

高优先级指令，可以理解为开发者指令。

{  
"instructions": "你是一个严谨但说人话的 AI 应用开发老师。"  
}

官方说明：`store` 表示是否存储生成的模型 response，以便之后通过 API 取回。

笔记：

store是否保存本次 response。`json{ "store": true}


用途：

之后 retrieve调试记录对话构建 conversation


如果你不想服务端保存，可以考虑设为 false，具体看业务和平台能力。

---## truncation控制上下文太长时怎么截断。`json{ "truncation": "auto"}


笔记：

truncation控制输入超过上下文窗口时如何处理。常见理解：`textdisabled：不自动截断，太长就报错auto：自动截断部分上下文


做严肃 RAG / 文档问答时，要小心自动截断，因为可能把关键资料截没。

---# 9. 缓存 / 成本 / 性能参数## prompt_cache_key用于提升 prompt cache 命中率。`json{ "prompt_cache_key": "user_123_project_ai_notes"}


官方文档说 `prompt_cache_key` 用于让 OpenAI 缓存相似请求，以优化 cache hit rate，并替代旧的 `user` 字段。

笔记：

prompt_cache_key用于提示缓存。适合：`text很多请求共享同一大段前缀例如固定 system prompt固定知识库说明固定工具描述


好处：

提升缓存命中降低延迟可能降低成本

---## prompt_cache_retention缓存保留策略。`json{ "prompt_cache_retention": "24h"}


官方文档说可选 `in-memory` 或 `24h`；`24h` 可以启用 extended prompt caching，让缓存前缀活跃更久，最长 24 小时。

笔记：

prompt_cache_retention控制 prompt cache 保留策略。可选：`textin-memory24h


新手阶段知道有这个即可。

---## service_tier控制请求服务层级。`json{ "service_tier": "default"}


官方文档说 `service_tier` 可以指定处理类型；`auto` 会用项目设置，`default` 是标准价格和性能，`flex`、`priority` 等对应不同处理层级。

笔记：

service_tier控制请求使用哪个服务层级。常见：`textautodefaultflexpriority


入门阶段一般不用管，默认即可。

---# 10. 安全 / 元数据参数## metadata给请求附加业务元数据。`json{ "metadata": { "user_id": "u_123", "feature": "ai_notes", "env": "dev" }}


笔记：

metadata给请求附加业务元数据。用途：`text日志调试统计后台筛选追踪是哪一个功能发起的请求


不要放敏感信息，比如明文邮箱、手机号、密码、API key。

---## safety_identifier用于安全风控的稳定用户标识。`json{ "safety_identifier": "hashed_user_id_abc"}


官方文档说 `safety_identifier` 是稳定标识，用于帮助检测应用用户是否违反使用政策；建议哈希用户名或邮箱，避免发送可识别信息，最大长度 64。

笔记：

safety_identifier用于安全风控的稳定用户标识。建议：`text传 hash 后的 user_id / email不要传明文个人信息


用途：

帮助平台识别异常使用滥用检测安全审计

---# 11. 最小请求模板你可以放进笔记：markdown## 最小 Responses API 请求bashcurl https://api.openai.com/v1/responses \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.2", "input": "解释一下 API 是什么" }'

---# 12. 稍微完整一点的请求模板markdown## 常用 Responses API 请求模板json{ "model": "gpt-5.2", "instructions": "你是一个严谨但说人话的 AI 应用开发老师。", "input": "解释一下 RAG 是什么", "temperature": 0.7, "max_output_tokens": 800, "stream": false, "text": { "verbosity": "medium", "format": { "type": "text" } }, "store": true, "metadata": { "feature": "learning_notes" }}

---# 13. Chat Completions 对应参数如果你用旧的 /chat/completions，大致这样：markdown## Chat Completions 常见参数json{ "model": "gpt-5.2", "messages": [ { "role": "developer", "content": "你是一个编程老师。" }, { "role": "user", "content": "解释一下 API 是什么" } ], "temperature": 0.7, "max_completion_tokens": 800, "stream": false, "tools": [], "tool_choice": "auto"}


核心区别：

Responses API:input + instructionsChat Completions:messages

---# 14. 新手优先掌握哪些参数？你现在别全背。先按这个顺序学：markdown## 参数学习优先级### 第一优先级：必须会textmodelinput / messagesAuthorizationContent-Type


### 第二优先级：马上会用

instructionstemperaturemax_output_tokensstream


### 第三优先级：做 AI 应用必须学

text.formatjson_schematoolstool_choiceprevious_response_idstore


### 第四优先级：进阶优化

reasoning.effortprompt_cache_keyservice_tiermetadatasafety_identifiertruncation

---# 15. 一句话总笔记markdown一次 LLM API 请求，本质上是：textPOST BaseURL + Endpoint带上 Authorization指定 model提交 input/messages用可选参数控制输出、格式、流式、工具、上下文、成本和安全


最核心参数：

model：用哪个模型input/messages：给模型什么instructions：模型应该怎么做temperature：随机性max_output_tokens：最长输出stream：是否流式text.format：输出格式tools：可调用工具tool_choice：是否必须/允许调用工具

::contentReference[oaicite:16]{index=16}


---