Quản lý
API Quản Lý
Quản lý số dư tổ chức, API key, usage và billing theo từng key bằng management token.
Tổng Quan
Management API cho phép bạn lấy tổng số dư tổ chức, quản lý API key của tổ chức và lấy usage cũng như billing cho một key cụ thể mà không cần dùng inference API key thông thường.
Tạo token quản lý tại Dashboard → API → Management Tokens:
Authorization: Bearer mt-your-management-tokenManagement token khác với inference API key. Dùng mt-... cho /v1/management/*, và dùng sk-... cho các endpoint suy luận như /v1/responses.
Endpoint Khả Dụng
| Điểm cuối | Phương thức | Mô tả |
|---|---|---|
/v1/management/balance | GET | Lấy các tổng số dư hiện tại của tổ chức |
/v1/management/api-keys | GET | Liệt kê API key do người dùng quản lý trong tổ chức hiện tại |
/v1/management/api-keys | POST | Tạo một API key người dùng mới |
/v1/management/api-keys/{keyId} | PATCH | Cập nhật tên, giới hạn sử dụng, model được phép, thời hạn hết hạn hoặc trạng thái |
/v1/management/api-keys/{keyId}/usage | GET | Lấy chi tiết usage có phân trang cho một key cụ thể |
/v1/management/api-keys/{keyId}/billing | GET | Lấy breakdown billing tổng hợp cho một key cụ thể |
Hợp Đồng Bộ Lọc Usage
GET /v1/management/api-keys/{keyId}/usage hỗ trợ các query parameter sau:
| Tham số | Kiểu | Mặc định / Giới hạn | Ghi chú |
|---|---|---|---|
page | integer | mặc định 1, tối thiểu 1 | Số trang tính từ 1 |
limit | integer | mặc định 50, tối thiểu 1, tối đa 100 | Kích thước trang |
model | string | tối đa 100 ký tự | Tên model được yêu cầu |
modelVendor | string | tối đa 100 ký tự | Nhà cung cấp model công khai |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime |
startDate | string | - | Cận dưới bao gồm; chấp nhận RFC3339 có múi giờ hoặc YYYY-MM-DD |
endDate | string | - | Cận trên bao gồm; chấp nhận RFC3339 có múi giờ hoặc YYYY-MM-DD |
Nếu truyền cả startDate và endDate, thì startDate phải nhỏ hơn hoặc bằng endDate.
Hợp Đồng Body API Key
POST /v1/management/api-keys
| Trường | Kiểu | Mặc định / Giới hạn | Ghi chú |
|---|---|---|---|
name | string | tùy chọn, mặc định Default Key, độ dài 1-50 | Tên hiển thị, máy chủ sẽ loại bỏ khoảng trắng ở đầu và cuối |
limitAmount | number | string | null | 0–100000 USD | null nghĩa là không giới hạn; 0 ngăn phát sinh chi phí. Chuỗi thập phân hỗ trợ tối đa 6 chữ số sau dấu thập phân. Khi tạo khóa, bỏ qua trường này nghĩa là không giới hạn. |
limitCurrency | enum | mặc định USD | Chỉ hỗ trợ USD. Gửi CNY sẽ trả về 400 currency_retired. |
models | string[] | mặc định [] | Danh sách cho phép model tùy chọn |
deliveryPolicy | string | null | auto, verified, official, null | null kế thừa chính sách cung cấp của không gian làm việc. |
expiresAt | string | null | datetime RFC3339 | null nghĩa là không hết hạn |
PATCH /v1/management/api-keys/{keyId}
| Trường | Kiểu | Mặc định / Giới hạn | Ghi chú |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | độ dài 1-50 | Tên hiển thị đã cập nhật |
limitAmount | number | string | null | 0–100000 USD | null nghĩa là không giới hạn; 0 ngăn phát sinh chi phí. Chuỗi thập phân hỗ trợ tối đa 6 chữ số sau dấu thập phân. |
limitCurrency | enum | mặc định USD | Chỉ hỗ trợ USD. Gửi CNY sẽ trả về 400 currency_retired. Khi được chỉ định, phải có cả limitAmount. |
models | string[] | - | Danh sách cho phép model đã cập nhật |
deliveryPolicy | string | null | auto, verified, official, null | null kế thừa chính sách cung cấp của không gian làm việc. |
expiresAt | string | null | datetime RFC3339 | null sẽ xoá thời hạn hết hạn |
PATCH phải có ít nhất một trường.
Trường tiền tệ
- Các trường tiền tệ trong yêu cầu và phản hồi của API Quản lý chỉ hỗ trợ USD.
limitCurrencymặc định làUSD; gửiCNYsẽ trả về400 currency_retired.
Ngữ Nghĩa Báo Cáo
modellà model công khai mà người gọi yêu cầu.modelVendorlà nhà cung cấp model công khai, không phải tuyến vật lý ẩn.scenelà ngữ cảnh yêu cầu công khai được suy ra từ endpoint hoặc loại tác vụ.
Phản hồi chỉ hiển thị các trường billing và reporting công khai. Chi tiết routing nội bộ và metadata provider vật lý vẫn bị ẩn.
- Các mục
/usagecó thể bao gồmbilling_transaction_idsau khi request cơ bản đã đạt trạng thái billing đã thanh toán. Dùngrequest_id+billing_transaction_idđể đối soát ở mức request.
Lưu ý về phân trang thanh toán
/usage có phân trang. /billing hiện là endpoint breakdown tổng hợp và không trả về metadata phân trang kiểu page / limit. Nếu cần bản ghi cấp dòng, hãy dùng /usage.
Ví Dụ Nhanh
Bắt đầu bằng cách kiểm tra số dư tổ chức với management token hiện tại:
Yêu cầu
curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"Sau đó liệt kê các API key hiện có cho cùng management token:
Yêu cầu
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"Phản hồi
{
"object": "list",
"data": [
{
"id": "key_abc123def456",
"name": "Backend Worker",
"key_prefix": "sk-abc123...",
"status": "active",
"limit_amount": 500.0,
"limit_amount_decimal": "500",
"used_amount": 148.25,
"used_amount_decimal": "148.25",
"models": [
"gpt-4o-mini",
"claude-3-7-sonnet"
],
"expires_at": "2026-04-30T00:00:00.000Z",
"last_used_at": "2026-03-27T08:12:45.000Z",
"created_at": "2026-03-01T10:00:00.000Z",
"delivery_policy": null
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1
}
}