Tài liệu
API quản lý
Khóa quản lý cho phép hệ thống của chính bạn tạo, nhóm, giới hạn và thu hồi các khóa API trong tài khoản, cũng như đọc số tiền chúng đã chi qua API. Khóa này không gọi được mô hình.
Dùng để làm gì
Một số tích hợp cấp cho mỗi khách hàng, nhóm hoặc người dùng một khóa API riêng, đặt khóa của từng khách hàng vào một nhóm, giới hạn số tiền một nhóm được chi và đọc lại chi phí theo khóa hoặc theo nhóm. Trên trang Khóa API, cách đó đủ cho một vài khóa. Với nhiều khóa hơn, khóa quản lý cho phép một tập lệnh hoặc công cụ quản trị của bạn làm điều tương tự qua API.
Khóa quản lý là một thông tin xác thực khác với khóa API. Nơi nào chấp nhận khóa API thì nơi đó không chấp nhận khóa quản lý: khóa này không gọi được /v1/chat/completions, /v1/messages hay bất kỳ tuyến mô hình nào khác. Khóa chỉ hoạt động trên /v1/management/, và khóa API không hoạt động ở đó.
Tạo khóa quản lý
- Mở trang Khóa API và cuộn xuống cuối trang. Trong mục Khóa quản lý, chọn “Khóa quản lý mới”. Mục này luôn thu gọn cho đến khi bạn mở ra.
- Đặt tên cho khóa, ví dụ billing sync, để trang cho biết chương trình nào đã thực hiện từng thay đổi.
- Nhập các địa chỉ được phép gọi, mỗi dòng một địa chỉ: một địa chỉ đơn như 203.0.113.7, hoặc một dải như 203.0.113.0/24. Nếu không có danh sách IP cho phép, bất kỳ ai giữ khóa đều có thể dùng nó, và hộp thoại sẽ cảnh báo bạn nếu để trống danh sách.
- Sao chép khóa khi nó được hiển thị. Khóa chỉ hiển thị một lần: Kunavo chỉ lưu hash của nó.
Một tài khoản có thể có hai khóa quản lý đang hoạt động cùng lúc. Hãy thu hồi một khóa để nhường chỗ cho khóa khác.
Cách gọi
Gửi khóa dưới dạng Bearer token tới https://api.kunavo.com/v1/management. Khóa quản lý không được chấp nhận từ trình duyệt: phản hồi không có header CORS, nên trang trên một site khác không gọi được. Khóa chỉ nên đặt trên máy chủ của bạn, không bao giờ trong mã front-end.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Phản hồi ở dạng JSON. Lỗi có cùng cấu trúc với phần còn lại của API: một đối tượng error gồm message, type, code và, khi áp dụng, param bị sai. Đây là các mã trạng thái bạn sẽ gặp:
| Trạng thái | Ý nghĩa |
|---|---|
401 | Khóa bị thiếu, gõ sai hoặc đã bị thu hồi, hoặc tài khoản của khóa bị tạm ngưng hoặc đang được xem xét. |
403 | Khóa có danh sách IP cho phép và yêu cầu đến từ một địa chỉ không có trong danh sách. |
404 | Nhóm hoặc khóa không tồn tại, đã bị xóa hoặc thuộc tài khoản khác. Cả ba trường hợp đều trả lời giống nhau, nên một ID từ tài khoản khác không tiết lộ gì. |
409 | Thay đổi xung đột với trạng thái của tài khoản: tên nhóm đã được dùng, khóa đã bị thu hồi, hoặc tài khoản đã đạt mức tối đa 500 khóa đang hoạt động. |
429 | Khóa này đã thực hiện 60 yêu cầu trong phút vừa qua. Header Retry-After cho biết cần chờ bao nhiêu giây. |
Nhóm
GET /v1/management/groups liệt kê các nhóm của tài khoản, kèm giới hạn hàng tháng của từng nhóm và số khóa đang hoạt động trong nhóm. POST tạo một nhóm, với monthly_limit_usd tùy chọn; tên đã được dùng sẽ trả về 409. PATCH /v1/management/groups/{id} đổi tên hoặc giới hạn: gửi null để không giới hạn, và 0 để tạm dừng mọi khóa trong nhóm mà không thu hồi khóa nào. DELETE xóa một nhóm, và các cuộc gọi của nhóm vẫn giữ tên nhóm trên trang Mức dùng. Các khóa của nhóm vẫn hoạt động và trở thành không thuộc nhóm nào, trừ khi bạn thêm ?revoke_keys=true, khi đó chúng cũng bị thu hồi.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Khóa
GET /v1/management/keys liệt kê khóa, mới nhất trước. Một trang có 50 khóa, và limit nâng con số đó lên 100. status mặc định là active, hoặc revoked hay all, và group_id thu hẹp danh sách về một nhóm. Khi has_more là true, hãy truyền next_after làm after để đọc trang tiếp theo. Văn bản gốc của khóa không bao giờ được liệt kê.
POST /v1/management/keys tạo khóa với một tên và, tùy chọn, group_id, monthly_limit_usd và ip_allowlist. Phản hồi chứa văn bản gốc của khóa trong trường key, chỉ một lần. Một POST được lặp lại sẽ tạo khóa thứ hai, nên trước khi thử lại, hãy liệt kê các khóa và tìm tên của nó.
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} đổi tên, nhóm, giới hạn hoặc danh sách IP cho phép của khóa; group_id bằng null đưa khóa ra khỏi nhóm. DELETE thu hồi khóa. Thu hồi một khóa đã bị thu hồi không phải là lỗi. Khóa đã thu hồi không thể thay đổi.
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Mức dùng
GET /v1/management/usage báo cáo mức dùng của toàn tài khoản trong tối đa 90 ngày UTC, cũng như GET /v1/usage báo cáo mức dùng của một khóa. group_by nhận mọi tổ hợp của group, api_key, model và day, mặc định là api_key. Các con số mang cùng ý nghĩa như trên trang Mức dùng: một cuộc gọi được tính vào nhóm mà khóa của nó thuộc về lúc thực hiện, cuộc gọi thất bại không tốn phí, và tổng của một khoảng thời gian khớp với bản xuất CSV của cùng những ngày đó đến từng xu. group_id và api_key_id thu hẹp báo cáo về một nhóm hoặc một khóa.
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date sau hôm nay được đọc là hôm nay, và phản hồi trả lại ngày kết thúc đã dùng.Giữ an toàn
- Hãy đặt danh sách IP cho phép. Một khóa chỉ hoạt động từ địa chỉ máy chủ của bạn có rất ít giá trị với kẻ đánh cắp nó.
- Lưu khóa trong kho bí mật trên máy chủ chạy công cụ của bạn. Không bao giờ đặt nó trong trình duyệt, ứng dụng di động hay kho mã.
- Nếu khóa bị lộ, hãy thu hồi ở cuối trang Khóa API, hoặc bằng
DELETEtrên khóa đó. Hộp thoại thu hồi cũng có thể thu hồi các khóa do khóa đó tạo ra. - Mọi thay đổi mà khóa thực hiện qua API đều được liệt kê trong mục Khóa quản lý trên trang Khóa API, kèm thời gian, địa chỉ nguồn và khóa đã thực hiện: 50 thay đổi gần nhất. Các thay đổi làm thủ công trên trang đó không được liệt kê.
- Khóa tự ngừng hoạt động khi tài khoản bị tạm ngưng hoặc đưa vào diện xem xét, và khi khóa bị thu hồi.
Một khóa quản lý được thực hiện 60 yêu cầu mỗi phút. Hãy gửi một yêu cầu cho mỗi thay đổi, và đọc danh sách theo trang thay vì từng khóa một.
Liên quan
Nhóm, giới hạn hàng tháng và cách tính số liệu được giải thích trên trang nhóm khóa. Số liệu mức dùng giống như trên trang Mức dùng.