第一次调用大模型 API，通常不难。
把一段 Prompt 发给模型，等它返回文字，一个最小 Demo 就跑起来了。
可一旦想把这个 Demo 做成真正有人使用的产品，问题会接连出现。
想做连续聊天，应用要维护会话上下文。有的接口需要回传历史消息，有的可以通过会话标识或上一条响应关联上下文。无论采用哪种方式，应用都要决定下一次调用使用哪些信息。
想让回复像打字一样逐步出现，要持续接收增量内容；想让模型查询订单、修改文件或执行命令，要接入工具并处理调用结果；任务执行时间一长，还要面对权限、状态、失败重试和中断恢复。
走到这里，大模型 API 已经不只是“输入一段文字，返回一段文字”。程序与模型交换的东西，从字符串扩展到角色消息、图片、结构化结果、工具调用和持续发生的事件。
这篇文章沿着 API 的演进，整理一张 AI 应用开发地图：接口暴露了什么能力，应用怎样组合和交付这些能力，以及为什么真正把它们变成可靠产品的，仍然是模型之外的 Runtime。
先从最基础的一层开始：模型和程序究竟交换什么。
大模型 API 的演进：从字符串到执行结果
如果只看接口可以表达的对象，这段变化大致可以归纳为三次扩展：自由文本 Prompt、带角色的 Messages，以及承载工具调用、任务结果和持续状态的 Items 与 Events。
Prompt：输入什么字符串，模型就从哪里续写
早期 Completion 接口把模型当成远程续写器。角色、示例、上下文和输出要求都塞进一段 Prompt，模型返回后续文本。
这种方式直接，但程序很难稳定地区分指令和用户内容，多轮对话也只能由开发者自行拼接。Chat Completions 后来用带角色的消息组织系统要求、用户输入和历史回复，OpenAI 又在这套接口中加入函数调用。
Messages：让系统、用户和助手各有位置
Chat Completions 和 Anthropic Messages 都把对话组织成消息列表。每条消息有角色和内容，应用可以明确表示系统要求、用户输入和模型回复。
Anthropic 的 Messages API 通常以 user 和 assistant 回合组织对话，从会话开始生效的系统提示通常使用请求顶层的 system 参数。消息内容还可以拆成 content blocks，文字、图片和 tool_use 不必挤在同一个字符串中。
Messages 解决了信息如何组织，没有替应用保存完整记忆。下一次调用需要哪些历史消息和工具结果，仍要由应用选择并传回。页面上的连续聊天，是应用管理状态后的产品体验。
Items 与 Events：一次返回不再只是助手说了一句话
当模型开始使用工具、处理多模态输入和持续输出事件时，Message 仍然有用，但不再是唯一单位。
OpenAI Responses API 的输出由带类型的 Items 组成；输入既可以是一段字符串，也可以是一组输入 Items。输出中可以出现消息、推理项和函数调用等对象；流式调用又会产生 response.output_text.delta、工具参数增量和完成状态等事件。
这不是把 messages 改名成 input。从对象模型看，Responses 不只返回助手消息，也可以返回推理项和工具调用。对 OpenAI 的新项目，官方建议优先采用 Responses，并把它称为新的 API primitive。
Prompt、Messages、Items 和 Events 不是互相排斥的四代接口，也不是所有厂商都严格经历的替代顺序。Message 内部可以有类型化内容块，Responses 仍然包含消息，Realtime 也会持续产生类型化事件。“从字符串到消息，再到 Items 和 Events”，是理解接口设计的一条观察线索。
把四种形态对比来看，程序实际收发的是下面这些东西：
为什么很多厂商会兼容 OpenAI 的接口格式
OpenAI 的 Chat Completions 已经进入大量 SDK、框架和应用代码。其他模型服务兼容这套请求与响应格式，开发者通常只需替换 API Key、模型名和 base URL，就能先完成基础调用，不必重写原有接入代码。
但“兼容”只说明某套请求、响应和 SDK 调用方式可以复用，不说明能力和语义完全一致。
Anthropic 也提供 OpenAI SDK 兼容入口，主要用于快速测试和比较模型能力。其官方文档同时说明，这不是多数场景下的长期生产方案；PDF、引用、完整 Thinking 和 Prompt Caching 等能力应使用原生 Claude API。兼容层中的部分字段还会被忽略。
DeepSeek、GLM 等服务也在官方文档中提供 OpenAI 和／或 Anthropic 格式的兼容入口。具体支持哪些字段和工具会变化，选型时仍要查看目标模型的支持表。
Open Responses 是一个受 OpenAI Responses API 启发的开源规范。它定义共享的请求与响应模型、Items、流式语义和工具调用模式，希望让不同客户端和服务提供商用较一致的结构交换信息，同时允许厂商扩展特有的工具和 Item 类型。
图：大模型 API 从交互单元到兼容规范的双线演进
AI 应用开发地图
把今天的大模型 API 拆开看，就是三件事：程序和模型交换什么，应用能调用哪些能力，结果怎样送到用户手里。下面还有应用 Runtime，负责状态、权限、执行、恢复和评估。
图：大模型 API 与 AI 应用开发总地图
用退款助手案例看会更具体。
用户提交订单号、商品照片和退款诉求；应用把它们组织成消息和图片内容块，调用图片理解、结构化输出和订单查询，再把处理状态与最终结果交给用户。
整个过程可能发生多次模型与工具往返。
图：箭头是处理顺序，不代表只调用一次 API。
前面的 Prompt、Messages、Items 和 Events，回答的是程序与模型“交换什么”。接下来再看应用可以组合哪些能力。
能力组合：应用可以通过 API 调用什么
结构化输出：让结果进入软件系统
自然语言适合给人看，软件系统更需要稳定字段。在支持结构化输出的模型和接口中，开发者可以提供 JSON Schema，让模型按约定返回姓名、日期、分类、路由决定或前端组件需要的数据。
特别注意的是：结构化输出解决的是结果形状，不是事实正确性。一个 JSON 可以完全符合 Schema，却写错订单、金额或日期。程序能读取，不代表业务可以相信。
工具调用：让模型提出行动请求
工具调用把自然语言判断接到外部系统。以查询订单为例：
- 应用向模型声明工具名称、说明和输入 Schema；
- 模型返回工具调用请求；
- 应用校验参数和用户权限；
- 应用执行查询；
- 应用把工具结果交回模型；
- 模型继续回答，或者提出下一次调用。
对自定义业务工具，模型提出调用请求，执行与业务后果仍由应用控制。搜索、代码执行等托管工具也可能由模型服务商执行，但应用仍要决定是否启用、允许访问哪些数据，以及结果能否触发自己的业务操作。
文件、检索和多模态：扩展模型能看到的材料
文件、向量检索、图片和音频输入，让模型不再只处理用户刚输入的一段文字。文档问答可以先检索相关片段，退款助手可以读取商品照片，语音助手可以直接处理声音。
材料进入模型之后，数据责任没有消失。文档怎样切分、检索结果是否相关、用户能看哪些文件、图片是否包含隐私、答案是否有材料支持，都要由应用处理。
运行与交付：请求怎样运行，用户怎样收到结果
同一种模型能力，换一种运行和交付方式，会形成不同的产品体验。
这部分不用想得太抽象。我们每天使用 AI 产品时，其实一直在接触这些方式：
| 你看到的产品画面 | 背后的运行与交付方式 |
|---|---|
| 聊天窗口按增量显示回答，像有人正在打字 | 流式返回 |
| 上传一张票据，稍等后收到完整识别结果 | 完整返回 |
| 语音助手边听边说，应用支持中途打断 | 持续实时连接 |
| 提交一批彼此独立的材料处理请求，稍后统一查看结果 | Batch |
完整返回还是流式返回
信息抽取和后台分类可以等待完整结果。聊天、写作和代码生成通常更适合流式返回，让用户更早看到内容。
现在常见的大模型聊天产品使用的“打字机效果”，就是流式返回最直观的样子。模型还没有生成完整答案，界面已经开始接收并显示文本增量。
流式也会带来新状态：用户可能中断，网络可能断开，界面上可能留下半段内容，工具调用事件还会穿插其中。接口能流式返回，不代表产品已经处理好了这些状态。
普通请求还是持续连接
实时语音需要持续双向连接。音频不断进入，音频、文本、工具和会话事件不断返回，应用还可以在模型说话时处理用户打断。
它对应的不是“发一段录音，等一段回答”，而是更像打电话：双方保持连接，可以轮流说话，也可以中途插话。
OpenAI Realtime API 提供 WebRTC、WebSocket 和 SIP 等连接方式；Google Gemini Live API 也面向低延迟的实时交互。接口名字不同，选型时应核对是否具备产品需要的持续连接、双向音频或文本流，以及打断处理。
在线返回还是 Batch
以 OpenAI Batch 和 Anthropic Message Batches 为例，大量彼此独立、不要求即时返回的模型请求，可以组成异步批次，例如批量分类、评估或生成摘要。
Batch 不是任意后台任务或单个长任务机制。应用仍要保存批次标识，跟踪状态，关联每条结果，并处理失败、过期或取消的请求。
它更像把一摞材料交给后台统一处理，而不是坐在聊天窗口前等模型逐字回复。
Runtime 把模型调用变成应用
API 提供消息、工具、文件和事件，把这些能力接起来还不是可靠应用。
这里的应用 Runtime，是把一次次模型调用组织成持续任务的应用代码与基础设施，不是某种编程语言运行时。
它决定了一个 AI 产品只是“回答”，还是能够真正“干活”。
腾讯 WorkBuddy 官方将其定位为能够自主规划并交付多模态复杂任务结果的办公 Agent。以 OpenAI Codex 为例，Coding Agent 可以读取和修改代码文件、运行命令与测试，再把变更和测试结果交给用户审查。
可以把它理解为：模型生成对任务的理解和下一步行动建议；应用 Runtime 提供文件、工具、执行环境、任务状态与权限边界，并负责实际执行和控制副作用。两者组合起来，才会形成桌面执行助手、Coding Agent 这类能持续完成任务的产品。
Runtime 至少要处理：
- 选择哪些上下文进入当前请求；
- 保存会话和任务状态；
- 注册工具并验证参数；
- 管理用户身份、数据和操作权限；
- 处理超时、重试和重复调用；
- 在高风险操作前请求人工确认；
- 按隐私和数据保留策略，记录必要的调用数据、成本和异常；
- 用固定任务评估应用是否完成目标。
放回退款助手，Runtime 要确认用户是否拥有订单、商品是否符合退款规则、同一请求是否已经处理、失败后是否重试，以及什么时候转给人工。模型即使正确理解用户，也不能替业务系统决定这些事情。
AI 应用开发如何选择接口
接口选型可以分四步。
第一，是否优先考虑跨厂商迁移。如果需要，就使用目标厂商共同支持的兼容子集；如果更依赖某家厂商的特有能力，就先核对其原生接口。
第二，模型要返回什么。OpenAI 新项目优先考虑 Responses，包括普通文本生成；已有 Chat Completions 项目不必为了接口形式立即迁移。Anthropic 原生应用通常从 Messages API 开始，其他厂商则查看其原生工具、Agent 或多模态接口。
第三，用户怎样等待。根据产品交互选择完整返回、流式、持续实时连接或离线 Batch。
第四，应用要承担什么后果。只要涉及状态、权限、工具执行、副作用和恢复，就要明确 Runtime 的设计，不能指望换一套接口自动解决。
| 场景 | 接口方向 | 主要原因 |
|---|---|---|
| 简单生成与普通对话 | OpenAI 新项目优先 Responses；Anthropic 原生应用通常从 Messages 开始 | 已有 Chat Completions 项目可以继续维护，不必只为接口形式迁移 |
| 多工具、多模态、Agent 任务 | OpenAI 优先 Responses；其他厂商查原生接口 | 可能需要工具调用、类型化输出或流式事件，对象模型因厂商而异 |
| 跨厂商基础调用 | 各家共同支持的兼容子集 | 降低迁移成本，但要逐项核对能力 |
| 实时语音 | 厂商的实时会话接口，如 OpenAI Realtime、Gemini Live | 核对持续连接、双向流、打断和音频能力 |
| 大量独立离线请求 | Batch | 不要求即时返回 |
| 依赖厂商特有能力 | 优先核对原生 API | 兼容层未必覆盖所需功能，需查看厂商限制 |
新接口不是旧接口的无条件替代品。
OpenAI 仍然支持 Chat Completions，但官方建议新项目优先使用 Responses。Anthropic 的原生对话接口是 Messages；Realtime 和 Batch 则解决不同的运行方式。
先看场景，再看厂商提供哪条入口。
用六个练习理解 AI 应用开发的基本原理
- 原生 API 调用：打印完整请求与响应，手动带上历史消息完成第二轮；如果说不清多轮状态存在哪里，还没有看懂协议。
- 结构化输出：用 JSON Schema 固定字段，再测试拒答、截断、缺失信息和错误金额等情况；格式符合 Schema 不算完成，业务字段仍要校验。
- 流式聊天：处理停止生成、网络中断和半段响应；只实现“打字机效果”不算完成。
- 工具调用：先接只读工具，再接有副作用的工具，为后者增加确认、幂等和审计；模型能生成参数不等于应用可以直接执行。
- 带引用的文档问答：加入权限过滤、引用展示和固定问题评估；能回答但找不到依据不算完成。
- Realtime 或 Batch：选一个方向，分别处理持续连接与打断，或者批次状态与结果关联；只成功提交请求不算完成。
完成这六个练习后，再进入 Agent SDK 或工作流框架，就能看出它封装了哪些消息、工具、循环和状态，也能判断哪些责任仍然留给应用。
总结：API 是入口，不是完整应用
从 API 开始学习，不需要先掌握某个庞大框架，也不需要先训练模型。它足够靠近模型，又仍然属于应用开发。
但接口调用成功，只说明模型服务返回了结果。产品问题、数据治理、权限、安全、评估、可观测性和成本控制仍然要由应用解决。
面对新的模型、接口或框架，可以继续问四个问题：
- 程序怎样把上下文交给模型？
- 模型怎样把文本、数据和行动请求交还程序？
- 一次请求怎样变成可中断、可恢复、可追踪的任务？
- 哪些责任始终留在模型之外？
沿着这四个问题，大模型 API 就不再是一份参数表。
接口的演进解释了 AI 应用怎样变复杂，应用地图则告诉开发者该在哪里做选择。
参考资料
- OpenAI，从 Completions 转向 Chat Completions：https://openai.com/index/gpt-4-api-general-availability/
- OpenAI，迁移到 Responses API：https://developers.openai.com/api/docs/guides/migrate-to-responses
- OpenAI，构建 Agent 的新工具：https://openai.com/index/new-tools-for-building-agents/
- OpenAI，Realtime API：https://platform.openai.com/docs/guides/realtime
- OpenAI，Batch API：https://developers.openai.com/api/docs/guides/batch
- Google，Gemini Live API：https://ai.google.dev/gemini-api/docs/live-api
- Anthropic，Messages API：https://docs.anthropic.com/en/api/messages
- Anthropic，OpenAI SDK compatibility：https://platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk
- Anthropic，Message Batches：https://platform.claude.com/docs/en/api/messages/batches/create
- Open Responses：https://www.openresponses.org/
- DeepSeek，API 文档：https://api-docs.deepseek.com/
- 智谱 GLM，OpenAI API 兼容：https://docs.bigmodel.cn/cn/guide/develop/openai/introduction
- 腾讯 WorkBuddy，产品页：https://www.codebuddy.cn/work/
- OpenAI，Codex 产品介绍：https://openai.com/index/introducing-codex/
