文档
← 所有文档

文档

认证

Kunavo 的认证方式与 OpenAI 完全相同：在 Authorization 请求头中使用一个 Bearer 令牌。与典型 OpenAI 集成的唯一差别是 base URL。

每次 API 调用都发送到 https://api.kunavo.com/v1，并携带 Authorization: Bearer sk-kn-XXX。就是这样。

基础 URL

为所有模型和所有模态提供服务的统一端点。

字段值
基础 URLhttps://api.kunavo.com/v1
区域美国（阿什本）主区域，多区域边缘节点接入
TLS强制使用 TLS 1.2+。仅支持 HTTPS。

路径布局遵循 OpenAI 的约定：

模态路径
聊天POST /v1/chat/completions
列出模型GET /v1/models
图像生成POST /v1/images/generations
图像编辑 / 图生图POST /v1/images/edits
视频生成POST /v1/video/generations
TTSPOST /v1/audio/speech
音乐POST /v1/audio/music

API 密钥

API 密钥可从控制面板中的 /app/keys 创建。每个密钥：

  • 以 sk-kn- 开头，后接 30+ 个随机字符。
  • 仅在创建时显示一次 — 此后 Kunavo 只保存其哈希值。
  • 具有供控制面板使用的易读名称（例如 prod-web）。
  • 可随时撤销 — 撤销后，该密钥会立即返回 401。
  • 每个密钥都可设置独立的月度支出限额和 IP 允许列表；两者均可在 /app/keys 中设置，并对每次调用生效。

每个密钥的支出限额（可选）

你可以为每个密钥设置美元计价的月度支出限额。如果该密钥在当前自然月的已结算用量将超过限额，使用此密钥发出的调用会返回 402 insufficient_quota，且不产生任何费用，直至月初限额重置。其他密钥不受影响 — 这是单个凭据的支出上限，而非整个账户的上限。

这正是无人值守智能体实际需要的约束：所有密钥共用钱包余额，因此仅靠余额无法阻止某个失控循环耗尽全部资金。为智能体单独创建一个密钥，并按任务设置限额，就能将最坏情况下的支出限制在该数额以内。将限额设为 $0 会暂停该密钥，但不会撤销它。

每个密钥的 IP 允许列表（可选）

也可以将密钥限制为仅允许从一组地址使用。每行输入一个 IPv4/IPv6 地址或 CIDR 网段（203.0.113.7、198.51.100.0/24、2001:db8::/32）；从其他地址使用该密钥发起的调用都会被拒绝，并返回 403 permission_error。此规则适用于包括 /v1/models 在内的所有端点。留空则允许任何地址。

我们检查的是边缘代理观测到的地址，而不是客户端能在请求头中自行声明的地址，因此无法通过伪造 X-Forwarded-For 绕过允许列表。另一方面，设置了允许列表的密钥在调用方切换到新主机、NAT 网关或网络后会立即失效。允许列表应绑定到出口地址稳定的服务器，而非笔记本电脑。

请求头

最简请求需要携带以下两个请求头：

Authorization: Bearer sk-kn-...
Content-Type: application/json

所有端点也支持通过 Anthropic SDK 发送的 x-api-key 请求头读取密钥，以代替 Authorization，因此，为 Anthropic API 构建的客户端无需自定义请求头即可访问所有路由，包括 /v1/models。如果请求同时携带两者，则读取 Authorization。无论密钥通过哪个请求头传入，其支出限额和 IP 允许列表都会生效。

可选但建议设置：使用 User-Agent 标识你的应用。我们会在你的 /app/usage 控制面板中记录 user-agent，方便排查请求来源。

使用 OpenAI SDK

大多数团队继续使用官方 OpenAI SDK，只需替换 base_url。Python（v1.x+）和 Node（v4.x+）均可采用这种方式。

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});
OpenAI SDK 在 Node 中使用 baseURL，在 Python 中使用 base_url。两者都指向同一个端点。

轮换密钥

最佳实践：每季度轮换 API 密钥，或在密钥可能泄露时轮换。Kunavo 允许同一账户同时拥有多个密钥，因此轮换时可以让新旧密钥平稳重叠使用，而无需一次性切换。

# 1. Create a new key in /app/keys, set its name to e.g. "prod-2026-Q2"
# 2. Deploy new key to your servers
# 3. Verify traffic is flowing on the new key (dashboard shows usage)
# 4. Revoke the old key from /app/keys → it 401s immediately

# In code, swap one env var:
export KUNAVO_API_KEY="sk-kn-new-..."
撤销密钥后会立即返回 401，没有宽限期 — 请先确认新密钥的流量已建立，再撤销旧密钥。

安全说明

  • 切勿在客户端公开密钥。 浏览器代码和移动应用安装包都是公开的。请始终通过自己的服务器代理请求。
  • 严格限定密钥用途。 为不同项目使用不同密钥，可在不影响其他工作负载的情况下撤销密钥；每个密钥还可设置独立的支出限额和 IP 允许列表，从而同时限制泄露密钥的费用和来源。
  • 关注控制面板。 /app/usage 页面会按密钥显示流量明细 — 更容易发现异常活动。
  • 报告疑似泄露。 请发送邮件至 support@kunavo.com，我们会协助作废密钥并审查事件。

接下来