Novro API 接入文档
用 OpenAI 或 Anthropic 客户端接入 Kimi、GLM 与 DeepSeek。正式上线后只需配置一个 API Key 和一个 Base URL。
/v1 模型请求即可使用。示例域名 api.example.invalid 不是生产地址,请替换为部署地址。01 · 基础信息
鉴权与请求地址
API Key 只放在服务端环境变量中,并通过 Bearer 认证头发送。不要把 Key 写入浏览器代码、移动端安装包、公开仓库或日志。
https://api.example.invalid/v1Authorization: Bearer nvr_xxxContent-Type: application/jsonrequest_id02 · 模型选择
使用稳定的模型标识
请求中的 model 决定具体能力和厂商。上下文、输入类型、官方价格和规划状态在模型目录集中维护。
03 · API 示例
选择你已有的客户端
Chat Completions 适合现有聊天 SDK;Responses 适合新应用;Messages 用于 Anthropic 生态客户端。字段支持度将随模型而异。
OpenAI Chat Completions
POST /v1/chat/completions,支持消息列表、非流式与 SSE 流式响应。
OpenAI Responses
POST /v1/responses,转发文本输入、流式输出和基本工具调用字段,能力取决于上游模型。
Anthropic Messages
POST /v1/messages,使用复数路径;Anthropic SDK 的 Base URL 不带末尾 /v1。
04 · 流式响应
用 SSE 持续接收增量
请求设置 stream: true 后,客户端逐块处理输出。连接可能中断,应用应保留已接收内容并给用户明确的重试入口。
05 · 工具调用
模型决定调用,应用负责执行
先把函数定义放入 tools;模型返回 tool_calls 后,由你的服务校验参数、执行本地函数,再把结果回传给模型。模型永远不应直接获得数据库或系统权限。
06 · 结构化输出
优先使用 JSON Schema
结构化数据场景优先使用 json_schema;仅要求合法 JSON 时使用 json_object。客户端仍需校验响应,不能把模型输出直接写入数据库或拼接 SQL。
07 · 错误处理
按错误类型决定是否重试
错误响应使用稳定的 error.code、固定的 error.type、面向用户的 error.message 和可追踪的 request_id。程序应根据状态码和错误代码分支,不要依赖文案。
| 状态 | 错误代码 | 含义 | 处理 |
|---|---|---|---|
| 400 | invalid_request / unsupported_endpoint | 请求字段、参数或 API 协议不合法 | 修正请求后再发,不要原样重试 |
| 401 | invalid_api_key | API Key 缺失、无效或已撤销 | 检查服务端环境中的 Key |
| 402 | insufficient_balance | 账户余额不足,网关未调用上游 | 调整余额后再重试 |
| 404 | not_found / model_not_found | 路径或模型标识不存在 | 检查 Base URL、路径和模型 ID |
| 500 | internal_error / billing_error | 网关内部或计费记录错误 | 记录 request_id 后有限重试 |
| 502 | upstream_unavailable / upstream_error | 上游暂时不可用或响应无效 | 指数退避并设置最大重试次数 |
08 · 安全
把 API Key 当作生产密码
每个服务使用独立 Key,定期轮换;怀疑泄露时先撤销再排查。浏览器前端应调用你自己的后端,由后端访问 Novro。
仅服务端使用
不要放进 NEXT_PUBLIC_*、网页脚本或客户端安装包
最小暴露
日志和错误追踪中脱敏 Authorization、Cookie 与敏感提示词
限制工具权限
模型生成的参数必须经过白名单、Schema 和业务权限校验
控制成本
设置请求超时、最大输出、并发限制和异常用量告警
模型厂商资料
模型能力和牌价以厂商页面为准,Novro 模型目录记录最近一次核验值。