Tài liệu
Nhóm khóa
Cấp cho mỗi khách hàng của bạn các khóa API riêng, gom chúng vào một nhóm, xem mỗi khách hàng và mỗi khóa đã chi bao nhiêu trong bất kỳ khoảng thời gian nào, và giới hạn số tiền mỗi khách hàng được chi trong một tháng. Một tài khoản, một số dư.
Nhóm là một thư mục khóa API trong tài khoản của bạn, ví dụ mỗi khách hàng một nhóm: CID000001, CID000002. Khóa trong nhóm gọi API như mọi khóa khác, và nhóm không có số dư, lần nạp tiền hay đăng nhập riêng; nhóm có thể có giới hạn chi tiêu hàng tháng tính trên tất cả các khóa của nhóm. Mỗi khóa thuộc một nhóm hoặc không thuộc nhóm nào.
Thiết lập nhóm trong ba bước
- Tạo nhóm. Trên trang Khóa API, chọn “Nhóm mới” và đặt tên theo khách hàng.
- Đưa khóa vào nhóm. Chọn “Khóa mới” trên tiêu đề của nhóm để tạo khóa ngay trong nhóm. Để xếp một khóa đã có, mở menu của khóa đó và chọn “Chuyển vào nhóm”.
- Đọc số liệu. Trang Khóa API hiển thị số tiền mỗi khóa đã chi trong tháng dương lịch này và tổng của mỗi nhóm. Trang Mức dùng hiển thị các khóa đó theo nhóm cho hôm nay, 7 hoặc 30 ngày qua, tháng này, tháng trước, hoặc những ngày bạn chọn, tối đa 90 ngày.
Xem một tháng và xuất ra
Trên trang Mức dùng, chọn “Tháng trước” (hoặc “Tháng này”, hay “Tùy chỉnh” để chọn ngày) ở phía trên. Trong “Theo khóa API”, tiêu đề của mỗi nhóm hiển thị chi phí và số cuộc gọi của nhóm. Menu nhóm ở phía trên thu hẹp cả trang về một nhóm: số liệu, biểu đồ, mô hình và cuộc gọi của nhóm đó. “Xuất CSV” tải xuống những gì trang đang hiển thị, cùng khoảng thời gian và cùng nhóm, theo khóa hoặc theo ngày.
Theo khóa, tệp có một dòng cho mỗi khóa và nhóm, với tên dạng kunavo-cost-by-key_2026-10-01_2026-10-31.csv. Tệp liệt kê mọi khóa có cuộc gọi trong khoảng thời gian, kể cả khóa đã thu hồi, dưới nhóm nơi mỗi cuộc gọi được thực hiện, và mọi khóa đang hoạt động không có cuộc gọi trong nhóm hiện tại của nó, với giá trị 0, để danh sách khóa của mỗi khách hàng là đầy đủ. Các nhóm theo thứ tự trên bảng điều khiển, khóa trong mỗi nhóm từ đắt nhất đến rẻ nhất, và khóa không thuộc nhóm nào ở cuối. Theo ngày, tệp có cột date ở đầu và một dòng cho mỗi ngày một khóa thực hiện cuộc gọi trong một nhóm.
| Cột | Nội dung |
|---|---|
group | Nhóm nơi các cuộc gọi được thực hiện; để trống với các cuộc gọi không thuộc nhóm nào. Nhóm bị xóa sau đó có (deleted) sau tên. |
key_name | Tên khóa. |
key_prefix | Phần đầu của khóa, như bảng điều khiển hiển thị. Không bao giờ là toàn bộ khóa. |
key_status | active hoặc revoked. |
calls | Số cuộc gọi bằng khóa này trong khoảng thời gian. |
errors | Số cuộc gọi thất bại trong đó. Cuộc gọi thất bại không tính phí. |
input_tokens | Token đầu vào, gồm cả token đọc và ghi bộ nhớ đệm. |
output_ | Token đầu ra. |
cached_ | Phần token đầu vào được đọc từ bộ nhớ đệm prompt. |
cache_ | Phần token đầu vào được ghi vào bộ nhớ đệm prompt. |
cost_usd | Số tiền đã tính cho các cuộc gọi, bằng đô la Mỹ, lấy tám chữ số thập phân. |
=, +, - hoặc @ sẽ được ghi kèm một dấu nháy đơn ở đầu, để bảng tính hiển thị nó như văn bản thay vì chạy nó như công thức.Giới hạn số tiền mỗi nhóm chi trong một tháng
Mở menu của nhóm trên trang Khóa API và chọn “Đặt giới hạn hàng tháng”. Giới hạn tính số tiền tất cả các khóa trong nhóm cùng chi trong một tháng dương lịch (UTC): các cuộc gọi mỗi khóa thực hiện khi đang ở trong nhóm. Yêu cầu sẽ khiến nhóm vượt giới hạn bị từ chối với mã 402 và không bị tính phí. Để trống ô nếu không giới hạn, hoặc đặt 0 để tạm dừng mọi khóa trong nhóm mà không thu hồi khóa nào.
Giới hạn hàng tháng riêng của từng khóa vẫn áp dụng, và giới hạn nào đạt trước sẽ từ chối yêu cầu. Tiêu đề của nhóm hiển thị chi tiêu trong tháng so với giới hạn, với “Đã chạm giới hạn” khi các yêu cầu bắt đầu bị từ chối, và “Đã tạm dừng” khi giới hạn là 0.
Kunavo gửi email đến địa chỉ của tài khoản bạn khi một nhóm, hoặc một khóa có giới hạn riêng, đã dùng 80% giới hạn hàng tháng, và gửi thêm lần nữa khi các yêu cầu bắt đầu bị từ chối vì giới hạn đó: mỗi loại email tối đa một lần mỗi tháng cho mỗi giới hạn.
Cách tính các con số
- Chi phí là số tiền đã tính. Chi phí của mỗi cuộc gọi là số tiền bị trừ khỏi số dư của bạn khi cuộc gọi hoàn tất. Cuộc gọi thất bại không tính phí.
- Tháng và ngày tính theo UTC. Tháng này bắt đầu lúc 00:00 UTC ngày 1. Ví dụ ở Yangon (UTC+6:30), tháng 10 kết thúc lúc 06:30 ngày 1 tháng 11 theo giờ địa phương. Trang Mức dùng ghi rõ các ngày của khoảng thời gian đang hiển thị.
- 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. Khi chuyển một khóa sang nhóm khác, chỉ các cuộc gọi từ đó trở đi mới được tính ở nhóm mới; các cuộc gọi trước đó vẫn ở chỗ cũ. Vì vậy tổng tháng của một nhóm trên trang Khóa API có thể khác tổng của các khóa đang được liệt kê dưới nhóm đó.
- Khóa đã thu hồi vẫn ở lại nhóm của nó. Số tiền khóa đã chi trước khi bị thu hồi vẫn được tính vào tổng của nhóm đó và có trong tệp xuất.
- Nhóm đã xóa vẫn giữ các cuộc gọi của mình. Các cuộc gọi đó vẫn nằm dưới tên nhóm, được đánh dấu là đã xóa, trên trang Mức dùng và trong tệp xuất, và tên đó có thể dùng lại cho một nhóm mới.
- Ba nơi, một con số. Trong cùng một tháng dương lịch, tổng của một nhóm trên trang Khóa API, tổng của nhóm ở mục “Tháng này” trên trang Mức dùng và tổng các dòng của nhóm trong CSV đều bằng nhau đến từng xu.
Câu hỏi
- Mỗi nhóm có số dư riêng không? Không. Mọi nhóm đều dùng chung một số dư của tài khoản. Để giới hạn số tiền một khách hàng có thể chi, hãy đặt giới hạn hàng tháng cho nhóm của khách hàng đó, hoặc cho từng khóa của họ.
- Khách hàng của tôi có thể đăng nhập để xem mức sử dụng không? Không. Chỉ bạn thấy được các nhóm. Một khóa có thể đọc mức sử dụng của chính nó bằng GET /v1/usage, phản hồi này không cho biết nhóm của khóa. Khi nhóm của khóa có giới hạn hàng tháng,
GET /v1/balancecho khóa biết giới hạn đó và số tiền cả nhóm đã chi trong tháng này, nhưng không cho biết tên nhóm. - Điều gì xảy ra khi tôi xóa một nhóm? Bạn chọn: các khóa của nhóm vẫn hoạt động và từ đó không thuộc nhóm nào, hoặc bị thu hồi cùng với nhóm. Dù chọn cách nào, các cuộc gọi các khóa đã thực hiện vẫn nằm dưới tên nhóm.
- Nếu một khóa chuyển từ khách hàng này sang khách hàng khác thì sao? Chuyển khóa sang nhóm của khách hàng kia: các cuộc gọi của khóa được tính ở đó từ lúc ấy, còn các cuộc gọi trước đó vẫn thuộc khách hàng đầu tiên.
- Tôi có thể xem các khoảng thời gian khác không? Có: chọn “Tùy chỉnh” trên trang Mức dùng và chọn tối đa 90 ngày. Với chương trình, GET /v1/usage trả về chi phí theo ngày của một khóa trong cùng khoảng thời gian.
Để tạo, nhóm, đặt giới hạn và thu hồi khóa của khách hàng từ công cụ của riêng bạn thay vì làm thủ công, hãy dùng API quản lý. Khóa của API này là một thông tin xác thực riêng và chỉ hoạt động trên API đó.