Bắt đầu
Xác thực
Xác thực các yêu cầu API của TokenLab bằng API key
API Keys
Các lệnh gọi mô hình và tài nguyên riêng tư yêu cầu phải có API key. Các endpoint khám phá công khai như GET /v1/models và GET /v1/models/{model} có thể hoạt động mà không cần key. Phản hồi khám phá thành công không xác minh rằng key của bạn hoạt động; hãy làm theo phần Quickstart để gửi một yêu cầu mô hình. Hãy sử dụng toàn bộ key đã lưu; tiền tố trong danh sách key không thể dùng để xác thực.
Đối với các endpoint tương thích với OpenAI, hãy gửi dưới dạng:
Authorization: Bearer sk-your-api-keyĐối với các yêu cầu /v1/messages tương thích với Anthropic, bạn cũng có thể sử dụng:
x-api-key: sk-your-api-keyCác yêu cầu /v1beta/* tương thích với Gemini cũng chấp nhận x-goog-api-key: sk-your-api-key. Ưu tiên sử dụng header thay vì tham số truy vấn ?key=, vì URL thường bị lưu lại trong nhật ký (logs).
Management Tokens
Các endpoint của Management API sử dụng một loại token riêng biệt:
Authorization: Bearer mt-your-management-tokenChỉ sử dụng management token với các endpoint /v1/management/*. Mở API → Tokens cho workspace đã chọn để tạo hoặc thay thế token. Hãy lưu lại toàn bộ token khi nó được hiển thị; nó chỉ được hiển thị một lần duy nhất sau khi tạo hoặc thay thế.
Management tokens không thể được sử dụng để suy luận mô hình (model inference), và các API key tiêu chuẩn sk-... không thể được sử dụng cho Management API.
Nhận API key
- Đăng nhập vào TokenLab Console
- Mở API Keys
- Tạo một key mới
- Đặt cho nó một cái tên dễ nhận biết
- Sao chép ngay lập tức vì nó chỉ được hiển thị một lần duy nhất
- Không bao giờ để lộ API key trong mã nguồn phía client
- Không bao giờ commit API key vào hệ thống quản lý phiên bản
- Sử dụng biến môi trường hoặc trình quản lý bí mật (secret manager)
- Định kỳ xoay vòng (rotate) các key
- Xóa các key không sử dụng
Sử dụng API key
Xem Bắt đầu nhanh để biết về các biến môi trường và yêu cầu đầu tiên hoàn chỉnh. Sử dụng SDK phù hợp với định dạng API mà bạn đã chọn; hãy giữ các key ở phía máy chủ.
Cài đặt key
Bạn có thể thiết lập các tùy chọn này cho từng API key trong Console và thông qua API Quản Lý:
| Cài đặt | Mô tả |
|---|---|
| Giới hạn chi tiêu | No limit cho phép key sử dụng số dư của Workspace. Fixed limit khiến key trả về lỗi 402 quota_exceeded sau khi đạt đến hạn mức. |
| Mô hình được phép | Key chỉ có thể gọi các mô hình này. Các mô hình khác sẽ trả về lỗi 403 model_not_allowed. Để trống nghĩa là không có hạn chế ở cấp độ key. |
| Tùy chọn phân phối | Auto, Verified, hoặc Official cho các yêu cầu từ key này. Để trống sẽ sử dụng mặc định của Workspace. Xem Thanh toán và giá cả. |
| Ngày hết hạn | Sau thời gian này, key sẽ trả về lỗi 401 expired_api_key. |
| Trạng thái | Một key ở trạng thái inactive (tạm dừng) sẽ trả về lỗi 401 invalid_api_key. Một key đã revoked (thu hồi) không thể được kích hoạt lại. |
Tiền tố key
Tất cả API key của TokenLab đều bắt đầu bằng sk-.
Phản hồi lỗi
| Mã trạng thái | Loại | Mã | Mô tả |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | API key bị thiếu, không hợp lệ, không hoạt động hoặc đã bị thu hồi |
| 401 | expired_api_key | expired_api_key | Key đã hết hạn |
| 402 | insufficient_balance | insufficient_balance | Số dư tài khoản không đủ |
| 402 | quota_exceeded | quota_exceeded | Đã đạt đến giới hạn sử dụng của API key |
| 403 | permission_error | model_not_allowed | Key không được phép sử dụng mô hình được yêu cầu |
| 403 | permission_error | user_suspended, account_restricted | Tài khoản không thể sử dụng API |
| 429 | rate_limit_exceeded | rate_limit_exceeded | Quá nhiều lần xác thực thất bại từ một địa chỉ IP. Hãy đợi theo Retry-After và sửa lại key; không lặp lại yêu cầu khi gặp lỗi 401 |
Ví dụ:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}