接入中心

Novro API 接入文档

用 OpenAI 或 Anthropic 客户端接入 Kimi、GLM 与 DeepSeek。正式上线后只需配置一个 API Key 和一个 Base URL。

01
创建 API Key
上线后在控制台创建;密钥首次展示后仍可在 Key 列表中重新复制。
02
选择协议
按现有客户端选择 Chat、Responses 或 Messages。
03
发送请求
替换 Base URL 和模型 ID,保留熟悉的 SDK。

01 · 基础信息

鉴权与请求地址

API Key 只放在服务端环境变量中,并通过 Bearer 认证头发送。不要把 Key 写入浏览器代码、移动端安装包、公开仓库或日志。

示例 Base URLhttps://api.example.invalid/v1
鉴权Authorization: Bearer nvr_xxx
请求格式Content-Type: application/json
请求追踪响应头或错误体中的 request_id
环境变量
NOVRO_API_KEY=nvr_your_api_key

02 · 模型选择

使用稳定的模型标识

请求中的 model 决定具体能力和厂商。上下文、输入类型、官方价格和规划状态在模型目录集中维护。

glm-5.2
1M 长上下文与工程任务
deepseek-v4-flash
高吞吐与 Responses
kimi-k3
长程 Coding 与多模态
查看全部模型和官方价格

03 · API 示例

选择你已有的客户端

Chat Completions 适合现有聊天 SDK;Responses 适合新应用;Messages 用于 Anthropic 生态客户端。字段支持度将随模型而异。

OpenAI Chat Completions

POST /v1/chat/completions,支持消息列表、非流式与 SSE 流式响应。

cURL
curl https://api.example.invalid/v1/chat/completions \
  -H "Authorization: Bearer $NOVRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.2",
    "messages": [
      {"role": "system", "content": "回答简洁、准确。"},
      {"role": "user", "content": "用三点说明什么是 RAG。"}
    ]
  }'

OpenAI Responses

POST /v1/responses,转发文本输入、流式输出和基本工具调用字段,能力取决于上游模型。

TypeScript
const response = await client.responses.create({
  model: "deepseek-v4-flash",
  input: "提取这段内容的关键事实,并给出来源位置。",
});

console.log(response.output_text);

Anthropic Messages

POST /v1/messages,使用复数路径;Anthropic SDK 的 Base URL 不带末尾 /v1

TypeScript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.NOVRO_API_KEY,
  baseURL: "https://api.example.invalid",
});

const message = await client.messages.create({
  model: "kimi-k3",
  max_tokens: 2048,
  messages: [{ role: "user", content: "分析这段代码的风险。" }],
});

console.log(message.content);

04 · 流式响应

用 SSE 持续接收增量

请求设置 stream: true 后,客户端逐块处理输出。连接可能中断,应用应保留已接收内容并给用户明确的重试入口。

TypeScript
const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "写一份发布检查清单。" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

05 · 工具调用

模型决定调用,应用负责执行

先把函数定义放入 tools;模型返回 tool_calls 后,由你的服务校验参数、执行本地函数,再把结果回传给模型。模型永远不应直接获得数据库或系统权限。

TypeScript
const tools = [{
  type: "function",
  function: {
    name: "get_weather",
    description: "查询指定城市的天气",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "城市名称" }
      },
      required: ["city"],
      additionalProperties: false
    }
  }
}];

const first = await client.chat.completions.create({
  model: "glm-5.2",
  messages: [{ role: "user", content: "北京今天适合骑车吗?" }],
  tools,
});

// 执行本地函数后,把 tool_call_id 和结果作为 tool 消息回传。
const call = first.choices[0].message.tool_calls?.[0];
校验函数名与参数
为工具设置超时
高风险操作二次确认

06 · 结构化输出

优先使用 JSON Schema

结构化数据场景优先使用 json_schema;仅要求合法 JSON 时使用 json_object。客户端仍需校验响应,不能把模型输出直接写入数据库或拼接 SQL。

TypeScript
const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "提取订单号和总金额。" }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "order",
      strict: true,
      schema: {
        type: "object",
        properties: {
          order_id: { type: "string" },
          total: { type: "number" }
        },
        required: ["order_id", "total"],
        additionalProperties: false
      }
    }
  }
});

07 · 错误处理

按错误类型决定是否重试

错误响应使用稳定的 error.code、固定的 error.type、面向用户的 error.message 和可追踪的 request_id。程序应根据状态码和错误代码分支,不要依赖文案。

状态错误代码含义处理
400invalid_request / unsupported_endpoint请求字段、参数或 API 协议不合法修正请求后再发,不要原样重试
401invalid_api_keyAPI Key 缺失、无效或已撤销检查服务端环境中的 Key
402insufficient_balance账户余额不足,网关未调用上游调整余额后再重试
404not_found / model_not_found路径或模型标识不存在检查 Base URL、路径和模型 ID
500internal_error / billing_error网关内部或计费记录错误记录 request_id 后有限重试
502upstream_unavailable / upstream_error上游暂时不可用或响应无效指数退避并设置最大重试次数

08 · 安全

把 API Key 当作生产密码

每个服务使用独立 Key,定期轮换;怀疑泄露时先撤销再排查。浏览器前端应调用你自己的后端,由后端访问 Novro。

仅服务端使用

不要放进 NEXT_PUBLIC_*、网页脚本或客户端安装包

最小暴露

日志和错误追踪中脱敏 Authorization、Cookie 与敏感提示词

限制工具权限

模型生成的参数必须经过白名单、Schema 和业务权限校验

控制成本

设置请求超时、最大输出、并发限制和异常用量告警

模型厂商资料

模型能力和牌价以厂商页面为准,Novro 模型目录记录最近一次核验值。