Tài liệu

Xác thực

Kunavo xác thực giống hệt OpenAI: một bearer token duy nhất trong header Authorization. Điểm khác biệt duy nhất so với tích hợp OpenAI thông thường là base URL.

Mọi lệnh gọi API đều gửi đến https://api.kunavo.com/v1 kèm Authorization: Bearer sk-kn-XXX. Chỉ vậy thôi.

URL cơ sở

Endpoint duy nhất dùng chung cho mọi mô hình, mọi phương thức.

Trường	Giá trị
URL cơ sở	`https://api.kunavo.com/v1`
Khu vực	Khu vực chính: Ashburn, Hoa Kỳ, với lớp biên đa khu vực ở phía trước
TLS	Bắt buộc dùng TLS 1.2 trở lên. Chỉ HTTPS.

Cấu trúc đường dẫn tuân theo quy ước của OpenAI:

Phương thức	Đường dẫn
Trò chuyện	`POST /v1/chat/completions`
Liệt kê mô hình	`GET /v1/models`
Tạo hình ảnh	`POST /v1/images/generations`
Chỉnh sửa ảnh / i2i	`POST /v1/images/edits`
Tạo video	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Âm nhạc	`POST /v1/audio/music`

API key

API key được cấp từ /app/keys trong bảng điều khiển. Mỗi khóa:

Bắt đầu bằng sk-kn-, theo sau là ít nhất 30 ký tự ngẫu nhiên.
Chỉ hiển thị một lần khi tạo — sau đó Kunavo chỉ lưu mã băm.
Có tên dễ đọc (ví dụ: prod-web) trong bảng điều khiển.
Có thể thu hồi bất cứ lúc nào — khóa lập tức trả về lỗi 401 sau khi bị thu hồi.
Có thể được đặt giới hạn chi tiêu hàng tháng và danh sách IP cho phép riêng; cả hai đều được cấu hình từ /app/keys và áp dụng cho mọi lệnh gọi.

Giới hạn chi tiêu theo từng khóa (tùy chọn)

Bạn có thể đặt giới hạn chi tiêu hàng tháng tính bằng đô la cho từng khóa. Khi một lệnh gọi sẽ khiến mức sử dụng đã quyết toán của khóa trong tháng dương lịch hiện tại vượt quá giới hạn, lệnh gọi đó sẽ trả về 402 insufficient_quota và không bị tính phí; điều này áp dụng cho đến khi giới hạn được đặt lại vào đầu tháng. Các khóa khác không bị ảnh hưởng — đây là mức trần áp dụng cho một thông tin xác thực, không phải toàn bộ tài khoản.

Đây là biện pháp kiểm soát mà một agent chạy không giám sát thực sự cần: số dư ví được chia sẻ giữa mọi khóa, nên chỉ riêng số dư không thể ngăn một vòng lặp mất kiểm soát tiêu hết tiền. Hãy cấp cho agent một khóa riêng với giới hạn phù hợp với công việc; khi đó, mức thiệt hại tối đa được khống chế ở con số đó. Giới hạn $0 sẽ tạm dừng khóa mà không thu hồi khóa.

Kunavo quyết định có chấp nhận một lệnh gọi hay không dựa trên con số chi tiêu mà hệ thống ghi nhận cho khóa. Con số này có thể trễ tối đa một phút và không tính khoản tiền mà các lệnh gọi đang chạy tạm giữ. Vì vậy, khi gần chạm giới hạn, một lệnh gọi vẫn có thể được chấp nhận và khiến chi tiêu vượt quá giới hạn, và phần vượt quá có thể lên tới số tiền đã bị tính phí qua khóa đó trong một phút vừa qua; nhiều lệnh gọi chạy cùng lúc cũng có thể cùng nhau vượt quá giới hạn. Ngoài ra, lệnh gọi được chấp nhận dựa trên khoản ước tính chi phí của nó, và số tiền cuối cùng bị tính phí có thể cao hơn khoản ước tính đó.

GET /v1/balance, khi được gọi bằng một khóa, trả về giới hạn của khóa đó, số tiền khóa đã chi trong tháng hiện tại và phần còn lại của giới hạn. Endpoint này cũng trả về số dư ví của tài khoản, mà mọi khóa của tài khoản đều đọc được, kể cả khóa có giới hạn. Xem Số dư.

Danh sách IP cho phép theo từng khóa (tùy chọn)

Bạn cũng có thể giới hạn một khóa vào một tập hợp địa chỉ nhất định. Nhập mỗi dòng một địa chỉ IPv4/IPv6 hoặc khối CIDR (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); các lệnh gọi dùng khóa đó từ địa chỉ khác sẽ bị từ chối với 403 permission_error trên mọi endpoint, kể cả /v1/models. Để trống nếu muốn cho phép mọi địa chỉ.

Địa chỉ được kiểm tra là địa chỉ mà proxy biên của chúng tôi quan sát được, không phải địa chỉ mà client có thể tự khai báo trong header — vì vậy không thể vượt qua danh sách cho phép bằng cách giả mạo X-Forwarded-For. Ngược lại, khóa có danh sách IP cho phép sẽ ngừng hoạt động ngay khi bên gọi chuyển sang máy chủ, cổng NAT hoặc mạng mới. Chỉ ghim danh sách cho phép vào máy chủ có địa chỉ gửi ra ổn định, không áp dụng cho máy tính xách tay.

Header yêu cầu

Một yêu cầu tối thiểu có hai header sau:

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

Mọi endpoint cũng đọc khóa từ header x-api-key thay cho Authorization — header mà Anthropic SDK gửi — vì vậy client được xây dựng cho API Anthropic có thể truy cập mọi route, kể cả /v1/models, mà không cần header tùy chỉnh. Nếu yêu cầu có cả hai header, hệ thống sẽ đọc Authorization. Giới hạn chi tiêu và danh sách IP cho phép của khóa đều áp dụng bất kể khóa được gửi qua header nào.

Tùy chọn nhưng nên dùng: User-Agent để nhận diện ứng dụng. Chúng tôi ghi nhật ký user-agent trong bảng điều khiển /app/usage của bạn để giúp tìm nguồn yêu cầu khi gỡ lỗi.

Sử dụng OpenAI SDK

Hầu hết nhóm vẫn dùng OpenAI SDK chính thức và chỉ cần đổi base_url. Cách này hoạt động với cả Python (v1.x trở lên) và Node (v4.x trở lên).

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 dùng baseURL trong Node và base_url trong Python. Cả hai đều trỏ đến cùng một endpoint.

Xoay vòng khóa

Thông lệ tốt nhất là xoay vòng API key mỗi quý hoặc bất cứ khi nào khóa có thể đã bị lộ. Kunavo cho phép bạn có nhiều khóa trên cùng một tài khoản cùng lúc, vì vậy việc xoay vòng diễn ra theo giai đoạn chồng lấn liền mạch, không cần chuyển đổi đột ngột.

# 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-..."

Khóa bị thu hồi sẽ trả về lỗi 401 ngay lập tức. Không có thời gian ân hạn — hãy đảm bảo lưu lượng đã chuyển sang khóa mới trước khi thu hồi khóa cũ.

Lưu ý bảo mật

Không bao giờ để lộ khóa ở phía client. Mã chạy trên trình duyệt và gói ứng dụng di động đều công khai. Luôn chuyển tiếp yêu cầu qua máy chủ của bạn.
Giới hạn phạm vi khóa ở mức cần thiết. Dùng khóa riêng cho từng dự án để có thể thu hồi mà không ảnh hưởng đến tác vụ khác — đồng thời đặt giới hạn chi tiêu và danh sách IP cho phép riêng cho từng khóa, giúp khống chế cả chi phí lẫn nguồn của khóa bị lộ.
Theo dõi bảng điều khiển. Trang /app/usage hiển thị lưu lượng được phân tách theo khóa — nhờ đó dễ phát hiện hoạt động bất thường.
Báo cáo nghi ngờ rò rỉ. Gửi email đến support@kunavo.com để chúng tôi hỗ trợ vô hiệu hóa khóa và xem xét sự cố.