Authentication

Hướng dẫn xác thực khi sử dụng Beeknoee AI API.

API Key

Tất cả request đến API đều cần có API Key trong header.

Lấy API Key

1. Đăng nhập vào platform.beeknoee.com
2. Vào API Keys → Tạo API Key
3. Nhập tên cho key
4. Sao chép key (bắt đầu bằng sk-bee-...)

Sử dụng API Key

Thêm header Authorization với format Bearer YOUR_API_KEY:

curl https://platform.beeknoee.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bee-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Bảo mật API Key

⚠️ QUAN TRỌNG

• KHÔNG commit API key vào git repository
• KHÔNG để lộ key trong frontend code
• KHÔNG chia sẻ key với người khác

Best Practices

1. Sử dụng environment variables

   export BEEKNOEE_API_KEY="sk-bee-your-api-key"
   

2. Trong code Python

   import os
   API_KEY = os.environ.get("BEEKNOEE_API_KEY")
   

3. Trong Node.js

   const API_KEY = process.env.BEEKNOEE_API_KEY;
   

4. Sử dụng file .env (thêm vào .gitignore)

   BEEKNOEE_API_KEY=sk-bee-your-api-key
   

Quản lý API Keys

Xem danh sách keys

Vào API Keys để xem tất cả keys của bạn với thông tin:

• Tên key
• Loại key (🌐 Universal — dùng được với tất cả model)
• Ngày tạo
• Trạng thái: Hoạt động · Tạm ngừng · Hết hạn · Đã thu hồi
• Ngày hết hạn (nếu có, theo giờ Việt Nam GMT+7)

Thu hồi key

Nếu key bị lộ hoặc không còn sử dụng:

1. Vào API Keys
2. Tìm key cần thu hồi
3. Click "Thu hồi"

Key bị thu hồi sẽ không thể sử dụng để gọi API. Thu hồi là vĩnh viễn — muốn tắt tạm thời thì dùng Tạm ngừng.

Tạm ngừng và kích hoạt lại key

Muốn chặn một key ngay mà vẫn giữ để dùng lại (ví dụ nghi bị lộ, tạm khoá một môi trường):

1. Vào API Keys
2. Bấm nút ⏸ Tạm ngừng ở dòng của key và xác nhận

Từ request kế tiếp, key bị từ chối với lỗi 403 api_key_suspended. Request đang chạy dở vẫn chạy nốt; phiên Realtime đang mở của key bị kết thúc ngay (end_reason: api_key_disabled). Thu hồi key cũng vậy. Bấm ▶ Kích hoạt lại để dùng tiếp — key, cấu hình và lịch sử sử dụng giữ nguyên.

Thời hạn sử dụng

Đặt ngày hết hạn ngay khi tạo key (7 / 30 / 90 ngày) hoặc sau đó trong Cấu hình → Cài đặt:

• Key hết hạn lúc 23:59:59 giờ Việt Nam (GMT+7) của ngày đã chọn.
• Sau mốc đó, mọi request bị từ chối với lỗi 401 api_key_expired — không cần chờ hệ thống quét.
• Muốn dùng lại key đã hết hạn: chọn ngày mới hoặc Không hết hạn rồi bấm Lưu.
• Email nhắc được gửi tới email tài khoản khi key còn ≤ 3 ngày (một lần cho mỗi mốc hết hạn; gia hạn sang ngày mới thì được nhắc lại).
• Phiên Realtime đang mở bị kết thúc khi key hết hạn (trễ tối đa khoảng 1 phút).

Giới hạn request/phút cho từng key

Trong Cấu hình → Giới hạn, đặt số request tối đa mỗi phút riêng cho một key (từ 1 tới trần request/phút của gói tài khoản — Free 500, Basic 1.000, Advanced+ 2.000, Ultra 5.000; để trống = không giới hạn):

• Đếm theo cửa sổ 60 giây trượt; tính mọi request gửi đi bằng key (POST…), kể cả request sau đó bị lỗi. Lượt hỏi trạng thái job ảnh/video và tải file về (GET) không tính.
• Vượt trần: lỗi 429 api_key_rpm_exceeded kèm header Retry-After (số giây cần chờ). Header X-RateLimit-Key-Limit / X-RateLimit-Key-Remaining cho biết trần và số lượt còn lại.
• Với chat, Responses, Messages, ảnh, video, giọng nói, Document AI: trần theo gói vẫn áp dụng song song — request phải qua cả hai.

Hạn mức chi tiêu cho từng key

Cũng trong Cấu hình → Giới hạn, đặt số tiền tối đa một key được tiêu theo ngày và/hoặc theo tháng (1.000đ – 10 tỷ đ; để trống = không giới hạn). Màn hình hiện số đã tiêu hôm nay / tháng này.

• Chỉ tính tiền trừ ví (gồm phụ phí web search). Request do gói token hoặc lượt miễn phí phục vụ không tính.
• Ngày tính từ 00:00 giờ Việt Nam (GMT+7); tháng tính từ 00:00 ngày 1.
• Chạm hạn mức: request gửi đi (POST) bị từ chối với lỗi 429 api_key_budget_exceeded, header Retry-After là số giây tới lúc mở lại. Xem kết quả / tải file đã tạo (GET) vẫn được.
• Hạn mức có thể bị vượt nhẹ bởi request đang chạy dở đúng lúc chạm mốc (hệ thống không cắt ngang stream).
• Đổi hạn mức có hiệu lực ngay ở request kế tiếp: hạ dưới số đã tiêu là chặn ngay, nâng là mở ngay.
• Khi đã tiêu 80% hạn mức ngày hoặc tháng, hệ thống gửi email nhắc (một lần mỗi kỳ; nâng hạn mức rồi lại chạm 80% thì nhắc lại).
• Phiên Realtime: trần chi của phiên (max_spend_vnd) tự kẹp về phần hạn mức còn lại của key; chạm hạn mức giữa phiên thì phiên kết thúc (end_reason: api_key_budget).

Default Key (key hệ thống dùng cho Playground) không tạm ngừng, không đặt thời hạn và không đặt giới hạn được.

Xử lý lỗi xác thực

// Response khi lỗi xác thực
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Tiếp theo

• Chat Completions - Bắt đầu gọi API
• Error Handling - Xử lý các loại lỗi