API 参考

这里集中放接口参数类文章。API 变化较快，阅读时要同时关注文章的核对日期和服务商兼容范围。

文章	重点
OpenAI API 核心接口与参数指南	Responses、Chat Completions、Embeddings、多模态、资源接口和工程参数
Claude API（Anthropic Messages API）指南	Messages、content blocks、Tool Use、流式事件、Prompt Cache、Extended Thinking 和 OpenAI 迁移

学习清单

OpenAI API 核心接口与参数指南

• 能画出 OpenAI API 的接口地图，并说明 Responses、Chat Completions、Embeddings、Realtime、Files 和 Batch 的职责

  参考答案：Responses 和 Chat Completions 负责模型生成与工具交互；Embeddings 负责向量表示；Realtime 负责低延迟双向音频会话；Files 和 Vector Stores 负责文件与可检索资源；Batch 负责大量离线请求。它们不能互相替代，应按交互方式、数据形态和延迟要求选型。

• 新项目为什么通常优先考虑 Responses API？Chat Completions 什么时候仍然合理？

  参考答案：Responses 是新的统一模型交互抽象，使用 typed input/output Items，原生支持多种托管工具、连续状态和 Agent 能力，官方建议新项目优先考虑。Chat Completions 仍适合已有 messages -> choices 系统、需要广泛兼容或底层服务只提供该协议的场景，应以能力、迁移成本和回归结果决定。

• 解释 Responses 的 input/output Items 和 Chat Completions 的 messages/choices 的根本区别

  参考答案：Chat Completions 把输入和输出组织成消息及候选结果；Responses 把消息、推理、函数调用、函数结果和托管工具调用拆成有类型的 Items，更适合 Agent 的多种动作。解析时不能把所有 output Item 当普通文本消息。

• 从 Chat Completions 迁移到 Responses 时，工具调用需要改哪些地方？

  参考答案：请求从 /v1/chat/completions 改到 /v1/responses；函数定义改为 Responses 的 function tool 形状；响应从 message.tool_calls 改读 function_call Item；工具结果从 role: tool 改为 function_call_output，用同一个 call_id 关联，并同步更新流式和错误处理。

• previous_response_id 能不能减少历史输入 token 的计费？为什么？

  参考答案：不能简单这样理解。它帮助 API 关联上下文，但历史输入仍按 usage 和定价计入成本，上一响应的顶层 instructions 也不会自动继承。上下文关联、数据保留和计费是三个不同问题。

• 如何计算一次文本模型请求的成本？

  参考答案：读取 usage，拆出未缓存输入、缓存命中输入、可见输出和可能单列的 reasoning token，分别乘当前模型的输入、缓存输入和输出单价，再加图像、音频、托管工具或处理档位费用。不能只用 total_tokens * 一个单价，也不能重复计算已包含在 output 中的 reasoning token。

• 什么是 prompt token cache？怎样提高命中率？

  参考答案：它通常复用重复输入前缀的处理结果，不是完整答案缓存。应把稳定 instructions、工具 schema 和输出约束放前面，把用户问题、时间、request ID 和工具结果放后面，保持工具顺序和序列化稳定，用 cached_tokens / total_input_tokens 实测，并同时检查质量、数据隔离、延迟和成本。

• max_output_tokens、temperature、top_p 和 finish_reason 分别解决什么问题？

  参考答案：max_output_tokens 限制最多生成多少；temperature 和 top_p 控制采样随机性，通常不要同时大幅调整；finish_reason 说明自然结束、达到长度上限或需要工具调用等停止原因。只有合并查看这些字段，才能判断输出是否完整。

• 为什么 response_format 和 Responses 的 text.format 不能混用？

  参考答案：它们属于两个接口的不同请求 schema。Chat Completions 使用 response_format，Responses 使用 text.format。迁移还要检查 JSON Schema、strict 行为、拒答和不完整响应；schema 合法不代表业务内容正确。

• 什么时候使用 Audio API，什么时候使用 Realtime API？

  参考答案：转写、翻译和语音合成等一次性文件或请求处理适合 Audio API；需要低延迟双向音频、持续会话、打断和实时事件流时使用 Realtime API。Realtime 是长连接事件协议，不能当作普通 HTTP 音频接口处理。

• 如何保证 Batch 结果能够准确回写业务数据库？

  参考答案：提交 JSONL 时为每行生成唯一 custom_id，保存它与原记录的映射、batch ID、输入文件 ID 和版本。完成后读取 output/error 文件，按 custom ID 幂等更新；失败行单独记录和重试，不能按返回顺序猜测对应关系。

• OpenAI 兼容服务为什么不能只换 base_url？

  参考答案：兼容通常只覆盖部分 endpoint、参数、工具调用、流式事件和 usage。不同服务的模型能力、错误码、限流、价格、缓存和数据保留也不同。应维护能力矩阵，用同一组请求、流式、工具和回归样本验证后再切换。

Claude API（Anthropic Messages API）指南

• Anthropic Messages API 和 OpenAI Chat Completions 的核心差异是什么？

  参考答案：Messages 使用 /v1/messages、x-api-key 和 anthropic-version，系统指令通常在顶层 system，输入输出通过 content blocks 表达；Chat Completions 通常用 Bearer token、消息数组中的 system 和 choices 响应。工具 schema、工具结果、流式事件、usage 和错误语义也不同，不能只换模型名。

• system、messages 和 content block 分别负责什么？

  参考答案：system 是本次请求的全局约束，messages 保存 user/assistant 历史，content block 表达文本、图片、工具调用、工具结果或思考。简单文本可用字符串，需要多模态或工具时使用 block 数组；历史由应用维护，API 不等于永久记忆。

• Claude 工具调用为什么需要两轮甚至多轮请求？

  参考答案：第一轮只生成 tool_use 意图，应用负责校验名称和参数、授权并执行工具，再把上一轮 assistant content 和对应 tool_result 放进下一轮请求，Claude 才能继续回答或请求其他工具。循环必须限制轮数、超时、并发、预算和重复调用。

• tool_use、tool_result 和 OpenAI 的 tool_calls、role: tool 如何对应？

  参考答案：Claude 的 tool_use block 含 id、name 和 input，结果用 tool_result 并以 tool_use_id 关联；Chat Completions 使用 tool_calls 和 role: tool，Responses 又有 function call Item。迁移需同时修改角色、字段、ID 关联和事件解析。

• 为什么不能只读取 message.content[0].text？

  参考答案：content 可能包含多个 text、tool_use、thinking、redacted_thinking 或未来类型。固定读取第一个文本会漏掉工具调用或截断内容，应遍历 block 按 type 处理，检查 stop_reason，并把展示文本与运行时事件、审计数据分开。

• Claude 流式响应应该如何解析？

  参考答案：流式响应是 typed SSE 事件，常见有 message_start、content_block_start、content_block_delta、content_block_stop、message_delta 和 message_stop。文本 delta 可增量展示；工具输入 JSON 可能跨多个 delta，必须缓冲成完整 JSON 后再校验执行；最终状态还要读取 stop reason、usage、error、取消和连接结束信息。

• Prompt Caching 适合缓存什么，不能解决什么？

  参考答案：适合复用稳定 system 指令、工具定义、公共背景和重复长文档的输入处理，动态问题和检索证据放在缓存前缀之后。它不是语义缓存或答案缓存，不能自动解决过期、ACL 和租户隔离；应监控缓存 token、成本、TTFT、版本和陈旧命中。

• Extended Thinking 会带来哪些工程影响？

  参考答案：会使用额外推理预算，响应可能包含 thinking 或 redacted thinking block，影响成本、TTFT、总延迟、展示处理和部分参数组合。应按问题复杂度启用、限制预算，不把思考内容未经审查展示或写入普通日志，并继续用检索、工具和业务规则验证事实。

• 如何控制 Claude 请求的上下文和成本？

  参考答案：估算 system、历史、工具 schema、图片/文档和 RAG 证据总输入，按权限和版本删除无效内容，摘要历史，去重压缩证据，最后按 token 上限截断。正式响应读取 input/output、缓存和 thinking usage，按当前价格分项计算。

• 从 OpenAI 迁移到 Claude 时最容易漏掉哪些地方？

  参考答案：常见遗漏包括认证 header、endpoint、顶层 system、content block、max_tokens、input_schema、tool_use/tool_result 循环、SSE 解析、usage 和 stop reason。还要重新验证多模态、Prompt Cache、thinking、错误码、限流、数据保留和质量回归，不能只换 SDK 或 base_url。

• 如何设计一个安全的 Claude 工具调用服务？

  参考答案：工具层要做租户授权、JSON Schema 与业务校验、读写分级、审批和幂等、超时和最大轮数、外部数据隔离、审计和取消传播；工具结果按 tool_use_id 回传，RAG 先做 ACL 过滤，缓存和日志也不能越过权限边界。模型意图不应直接获得数据库或外部系统写权限。