把聊天补全的请求与响应摊在一页上

接入聊天补全接口时，最容易混淆的不是地址，而是同一个字段在不同位置的含义。这页笔记把请求与响应并排来看，再对照流式输出、工具调用和原生协议。目标是保留一套清楚的调用骨架，而不是假设所有模型行为相同。

§ 入口：服务地址与接口路径

左侧，连接配置：服务地址决定请求发往哪里，接口路径决定使用哪种协议。OpenAI 聊天补全通常使用 POST /v1/chat/completions，并通过 Authorization: Bearer 携带密钥。配置 SDK 时，要确认 base_url 是否已经包含 /v1，避免重复拼接。

右侧，模型选择：model 是请求体中的模型标识，不是服务地址。Vana API 的统一入口是 https://api.vanaapi.com；切换服务时调整连接配置，切换模型时调整 model，具体标识以平台提供的值为准。

左侧，请求：messages 是按顺序排列的消息数组。每条消息用 role 表示身份，用 content 承载内容。常见角色包括 system、user、assistant 和 tool；developer 角色及其支持范围需要按模型核对。普通聊天通常需要客户端带上相关历史。

右侧，响应：非流式结果通常从 choices[0].message 读取本轮助手消息，而不是从顶层读取 content。返回对象还可能包含 id、model、usage 等信息。接口返回一轮结果，不等于服务端自动保存了下一轮所需的完整会话。

左侧，简单输入：纯文本场景下，content 可以是字符串。支持多模态的接口也可能接收内容块数组，将文本与图片等输入放在同一条消息内；具体结构和可用模态必须核对。

右侧，稳健读取：不要把所有响应都当成非空字符串。助手消息可能主要包含工具调用，此时 content 可能为空或为 null。解析器应区分文本、工具调用和其他受支持字段，避免直接拼接造成异常。

左侧，非流式：省略 stream 或设为 false，通常等待完整 JSON 响应。适合后台任务、结果校验和不需要逐字显示的界面。finish_reason 用于判断生成如何结束，不能只检查有没有文本。

右侧，流式：设置 stream: true 后，通常接收服务器发送事件。文本从 choices 中的 delta 逐步到达，而不是反复返回完整 message。应解析事件边界、累计片段并处理结束信号；一个网络数据块不一定对应一个完整事件。用量是否随流返回，也要核对支持情况。

左侧，发出请求：tools 声明工具名称、用途和参数结构。模型返回 tool_calls，表示它请求调用工具，并不表示工具已经执行。函数参数通常是 JSON 字符串，需要解析、校验并进行权限检查。

右侧，继续对话：应用执行工具后，把助手的工具调用消息与对应的 tool 结果一起加入历史，再次请求模型。工具结果通过 tool_call_id 对应调用。工具声明、调用请求、执行结果是三个不同阶段。

左侧，通用部分：消息数组、模型字段和基本响应结构可以复用。例如评估 GPT-6.1 Sol 与 Gemini 3.1 Pro 时，可以先保留同一套聊天补全调用逻辑，再分别验证输出。

右侧，需要核对的部分：上下文长度、输出上限参数、采样选项、结构化输出和工具能力不一定一致。OpenAI 兼容不意味着每个参数都具有完全相同的语义；出现错误时，应记录状态码、错误体和请求标识，而不是直接重复提交。

左侧，统一接入：Vana API 支持 OpenAI 兼容格式，也提供 Anthropic Messages 和 Gemini 原生协议，可配合 OpenAI SDK，以及 Claude Code、Codex、Gemini CLI 使用；具体采用哪种协议取决于客户端配置。

右侧，边界保持清楚：Anthropic Messages、Gemini 原生请求与聊天补全并非同一份 JSON。路径、字段和流事件不能直接互换。统一服务入口减少连接配置，但不会消除协议差异。

实际落地时，先验证一条普通请求，再补流式、工具调用和错误处理。Vana API 按实际 token 用量计费，无月费；可以创建账户，用一段短对话检查接入链路，再迁移正式流量。