文件
← 所有文件

文件

驗證

Kunavo 的驗證方式與 OpenAI 完全相同：在 Authorization 標頭中放入單一 Bearer Token。與一般 OpenAI 整合的唯一差異是基底 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
圖片編輯 / i2iPOST /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，我們會協助撤銷金鑰並檢視事件。

接下來可以查看