10. 调用接口

返回概览 · 完整版目录 · 下载完整 PDF

业务应用和开发工具通过网关的模型调用接口使用模型。网关在入口完成鉴权、授权、配额与流量规则判断，把请求转换为上游供应商的接口格式，并把响应和错误按调用方使用的协议返回。本章面向接入网关的开发人员和技术负责人，功能属于基础功能许可。

10.1 Base URL 与鉴权

Base URL 由网关的公开访问地址加固定前缀组成。成员在模型广场的模型详情「首次调用 API」区域可直接复制当前环境的地址（第 8.3 节）。下表中 <网关地址> 指该访问地址：

规则：

• 同一请求同时携带两种凭据且取值不同时，网关返回 400，不会择一使用；
• 凭据可以是成员创建的 API 密钥，也可以是启用「业务系统调用」后的身份源令牌（第 9.5 节）；
• 请求中的模型名（OpenAI、Anthropic 为请求体的 model 字段，Gemini 为路径中的模型名）填写模型广场或模型列表接口返回的模型名。模型必须属于这把 Key 绑定的模型服务，否则返回 404，错误码 LLM_MODEL_NOT_AVAILABLE；
• 可选请求头 x-zenova-conversation-id 用于指定会话归属；不携带时由网关自动识别会话，识别顺序与取值要求见第 10.9 节；
• 请求体上限为 32 MiB，语音转写文件上传为 25 MiB。

10.2 接口清单

OpenAI 兼容接口（路径相对于 OpenAI Base URL）：

Anthropic 原生接口：POST /v1/messages（支持流式），GET /v1/models。

Gemini 原生接口：POST /v1beta/models/{model}:generateContent、POST /v1beta/models/{model}:streamGenerateContent，同时接受 /v1/models/... 路径；GET /v1beta/models 列出模型。不支持 countTokens 等其他方法，调用返回 404。

模型必须具备对应用途（第 4.6 节）。模型或其供应商不支持所调用的接口时返回 400，错误码 MODEL_ENDPOINT_UNSUPPORTED；批量判断接口在所选上游不支持判断时返回 400，提示“该模型不支持此接口”。

10.3 协议自动转换

对话类接口支持四种协议：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini generateContent。调用方可以用其中任一协议调用任一对话模型，不必与供应商的「模型请求格式」一致：

• 入站协议与上游格式相同时，网关原样转发请求与响应；
• 不同时，网关把请求转换为上游格式，再把响应（包括流式事件）转换回入站协议；
• 转换中有字段无法在上游格式中表达而被丢弃时，响应头 x-zenova-conversion-dropped 列出被丢弃的部件，多个标识以逗号分隔，例如 anthropic.tool.web_search,responses.store。原样转发的请求不带该响应头。

嵌入、重排序、图像、语音和批量判断接口只提供 OpenAI 兼容格式，不做协议转换。

因此，Claude Code 可通过 Anthropic 接口、Gemini CLI 可通过 Gemini 接口、Codex 可通过 Responses 接口使用网关上的任意对话模型。各工具的环境变量见第 8.3 节「获取 API 密钥并发起首次调用」。

10.4 流式输出、重试与心跳

开启流式：OpenAI 与 Anthropic 接口在请求体中设置 "stream": true；Gemini 使用 :streamGenerateContent 方法。

重试与切换：

• 网关只在上游返回首个内容之前重试或切换目标，内容一旦开始输出就不再重试，避免重复内容；
• 同一目标的重试次数与可重试错误类型取供应商的「统一重试策略」（默认最多重试 2 次，第 4.4 节）；
• 只有在流量规则中配置了故障转移时，网关才会切换到备用档位的其他模型（第 15 章，需要动态路由许可）。

心跳：流式请求在 10 秒内仍未得到上游首个内容时，网关先返回 200 响应头并开始发送心跳，此后的失败以流内错误帧交付；流式输出过程中，网关每 15 秒插入一条心跳。Anthropic 协议使用 event: ping 事件，其他协议使用 SSE 注释行 : keepalive，标准客户端会忽略注释行。中间代理或负载均衡的空闲超时应大于 15 秒。

流内错误：流式输出开始后发生失败时，网关发送一条与所选协议错误体同形的流内错误帧，再正常结束流。已输出的内容与用量照常计费。护栏在流式输出中途拦截时，流以协议的终结帧结束，并在终结帧中带 safetyIntervention 字段（kind 为 stream_cut）。

10.5 嵌入与重排序

嵌入：POST /embeddings，请求体包含 model 和 input。按输入 Token 计费。

{ "model": "your-gateway-model", "input": "把这段文字变成向量。" }

重排序：POST /rerank，请求体包含 model、query 和 documents。按搜索次数计费：上游返回搜索次数时采用该值，否则按“1 次查询加每 100 个文档 1 次”计算；价格按每千次搜索设置。

{ "model": "your-gateway-model", "query": "退款进度", "documents": ["订单已发货。", "退款将在三个工作日内到账。"] }

10.6 图像与语音

语音转写只读取音频文件头计算时长，不解码整段音频；无法识别格式时返回 400，提示“无法识别音频格式”。

实时转写使用 WebSocket：

1. 连接 GET /audio/transcriptions/realtime?model=<模型名>，可选 language（ISO-639-1 语种代码，如 zh，缺省自动识别）。
2. 子协议为 zenova.transcription.v1。凭据放在 Authorization 头；浏览器无法设置该头时，把凭据作为第二个子协议携带，服务端不会回显。
3. 以二进制帧发送 16 kHz、单声道、16 位小端 PCM 音频。网关按停顿切段，每段作为一次转写请求独立鉴权、计费，并以 {"type":"transcript","text":"…","final":true} 文本帧返回。
4. 客户端可发送 {"type":"input_audio_buffer.commit"} 立即切段，发送 {"type":"session.finish"} 结束会话；服务端推完全部段后发送 {"type":"finished"} 并关闭连接。出错时发送 {"type":"error","code":"…","message":"…"} 并关闭。

10.7 批量判断

批量判断对一段内容同时回答多道是非、选择或评分题，适用于分类、审核等场景。调用前需在模型的能力配置中声明「判断」用途。

POST /decisions 请求体包含 model、input（被判断的内容）和 questions。每道题包含 name、instructions 和 type：

• predicate：是非题，答案为概率；
• choice：选择题，choices 至少 2 项，每项包含 value 和 description；
• score：评分题，levels 至少 1 级，每级包含 label 和 description。

{
  "model": "your-gateway-model",
  "input": "这笔订单被扣了两次款。",
  "questions": [
    { "name": "is_complaint", "instructions": "这是不是一条投诉？", "type": "predicate" },
    { "name": "department", "instructions": "应该交给哪个部门？", "type": "choice",
      "choices": [ { "value": "billing", "description": "付款、发票和退款。" },
                   { "value": "other", "description": "以上都不是。" } ] }
  ]
}

POST /systemone 是同一用途的另一种请求格式：用 state 放被判断的内容，questions 为按题名索引的对象。

限制：

• 一次请求最多 256 题，题名不能重复；
• 超过所选上游的单批上限时，网关按上限拆分并发送，再按题名合并答案，每一批单独记一条用量；
• 图片只能以 data: 地址放入内容，不接收图片的上游返回 400；
• 缺题、多题或答案不在选项内时，网关拒绝并指出具体题目；
• 不同上游给出的判断分数不能直接比较。

计费按 Token，同时计输入和输出。

10.8 错误格式与错误码

错误按调用方使用的协议返回：

reason 是稳定的错误码，HTTP 状态和是否可重试都由它决定，业务系统应按 reason 处理错误，不要解析 message 文本。常见错误码：

响应头：

• x-request-id：网关侧请求标识，与 OpenAI、Anthropic 错误体中的 request_id 相同，Anthropic 协议还同时返回 request-id。向管理员反馈问题时附上该值；
• x-should-retry：true 或 false，表示重试是否可能改变结果；
• Retry-After（秒）与 retry-after-ms（毫秒）：仅在错误可重试且网关知道等待时长时返回。可重试的 429 若没有其他等待时长，返回 Retry-After: 1；网关数据面尚未就绪而返回 503 时，也带 Retry-After。

错误体中的 message 是随版本可能调整的说明文字，多数为英文；管理控制台和能力中心按 reason 显示中文说明。完整的错误码清单、各协议的错误体与流式终结帧形态，见随产品发布的文档站中的错误参考页。

10.9 会话识别

网关把同一场对话的多次调用归入同一个会话，供会话列表与会话详情（第 20.3 节）、会话诊断（第 20.4 节）、按会话计数的限额（第 15.4.3 节）和会话切换保护（第 15.7.4 节）使用。会话与请求标识 x-request-id 无关：请求标识每次调用各不相同，不影响会话归属。

网关按以下顺序识别会话，命中一项即停止：

1. 请求头 x-zenova-conversation-id：调用方显式指定的会话编号。
2. 客户端自带的会话编号：Claude Code、Codex、OpenCode 等客户端在请求中携带的会话编号，无需额外配置。
3. Responses 续接与会话：使用 OpenAI Responses 接口并携带 previous_response_id 时，续接请求归入上一轮所在的会话，并沿用上一轮的识别方式；未携带 previous_response_id 但请求体带有 conversation 时，按该值识别。
4. 首条用户消息：以上信息均未提供时，网关按对话中的首条用户消息识别同一对话的多轮请求。

能够自行控制请求的调用方（例如自建的 Agent 平台或业务系统）可以携带请求头 x-zenova-conversation-id，精确指定会话归属。取值要求如下：

• 使用 UUID，或使用由字母、数字、-、_ 组成且不少于 22 个字符的编号。
• 最长 128 个字符；取值不符合上述格式或超过长度上限时，请求返回 400。
• 同一对话的全部请求携带相同取值，不同对话使用不同取值。

使用时注意以下限制：

• 按首条用户消息识别的会话只用于会话归并与展示，不参与按会话计数，也不启用会话切换保护。需要这两项功能时，应携带 x-zenova-conversation-id，或使用自带会话编号的客户端。
• 按首条用户消息识别要求对话历史保持完整。调用方截断、摘要或改写早期消息（包括首条用户消息）后，后续请求可能被识别为新的会话；同一调用方、同一终端用户发起的首条用户消息完全相同的两场对话，可能被归入同一会话。对会话归属有精确要求时，应显式携带请求头。
• 使用 Responses 续接时，previous_response_id 必须原样回传网关下发的响应编号（形如 resp_zr2.…）。回传其他取值，或回传其他凭据获得的响应编号，请求返回 400，错误码 invalid_previous_response_id。
• Responses 续接依赖上一轮所在供应商保存的响应。上一轮所在的供应商或供应商账号当前不可用（错误码 provider_account_continuation_unavailable），或上一轮响应经协议转换生成、上游供应商未保存该响应（错误码 response_continuation_unrestorable）时，无法凭 previous_response_id 续接。此时请求的 input 若已携带完整上下文（包含此前的助手回复、工具调用或工具结果），网关去掉 previous_response_id 后照常转发；否则返回 409，调用方应在 input 中携带完整上下文后重试，或开启新对话。

上一章：9. 调用方、API 密钥、认证与授权 · 下一章：11. 配置并分发 MCP 服务与 API 服务