TokenLab Management API Bổ Sung Tính Năng Tra Cứu Số Dư Workspace

Việc để quy trình sản xuất tự động bị gián đoạn do hết số dư hoàn toàn có thể ngăn ngừa được. Tính năng tra cứu số dư của TokenLab Management API cung cấp cho các quy trình làm việc tự động khả năng truy vấn tổng số dư bằng management token thay vì inference key.

Hướng dẫn này đề cập đến quy chuẩn endpoint GET /v1/management/balance, các yêu cầu xác thực, xử lý tiền tệ, và cách xác thực schema phản hồi trực tiếp dựa trên tài liệu chính thức.

Những Điểm Chính

• Endpoint số dư của Management API (GET /v1/management/balance) trả về số dư workspace hiện tại, tổng số tiền nạp và chi tiêu sử dụng tích lũy.
• Việc xác thực yêu cầu một management token (mt-...) được tạo trong Dashboard → API → Management Tokens, giúp tách biệt việc kiểm tra vận hành khỏi các model inference key (sk-...).
• Tất cả các giá trị tiền tệ được trả về bằng USD. Các phép tính chính xác nên sử dụng các chuỗi thập phân được trả về (balance_decimal, total_recharge_decimal, total_used_decimal).
• Endpoint này kết hợp với các báo cáo cấp độ key như /v1/management/api-keys/{keyId}/usage và /v1/management/api-keys/{keyId}/billing.

Management Token và Model Inference API Key

Management token và model inference key đảm nhận các vai trò vận hành riêng biệt trong TokenLab:

• Model inference API key (sk-...): Được sử dụng để gọi các endpoint suy luận như POST /v1/chat/completions, POST /v1/responses, native Anthropic Messages trên POST /v1/messages, và Gemini trên /v1beta/models/.... Các key này thực thi những yêu cầu tạo nội dung nhưng không để lộ dữ liệu tài chính cấp tổ chức.
• Management token (mt-...): Giới hạn trong các route /v1/management/*. Chúng cho phép các hệ thống backend kiểm tra số dư workspace, liệt kê hoặc chỉnh sửa API key, và giám sát mức độ sử dụng mà không cấp quyền truy cập tạo nội dung từ mô hình.

Việc tách biệt các thông tin xác thực này đảm bảo các script kế toán và giám sát tài chính không thể kích hoạt các lệnh gọi suy luận có tính phí, đồng thời các worker chạy mô hình không bao giờ có quyền truy cập vào quản trị tài khoản.

Quy Chuẩn Wire Contract Của Endpoint Số Dư

Gửi một yêu cầu GET đến https://api.tokenlab.sh/v1/management/balance kèm xác thực bằng management token của bạn trong header Authorization:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

Schema Phản Hồi

Một yêu cầu thành công sẽ trả về mã 200 OK với một đối tượng organization_balance:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

Các Trường Phản Hồi

• object (string): Luôn là organization_balance.
• organization_id (string): Tổ chức liên kết với management token hiện tại.
• balance (number): Số dư workspace hiện tại bằng USD dưới dạng số thực dấu phẩy động dùng để hiển thị.
• balance_decimal (string): Số dư workspace hiện tại chính xác bằng USD được định dạng dưới dạng chuỗi thập phân để đối soát tài chính.
• total_recharge (number): Tổng số tiền nạp vào workspace thành công bằng USD.
• total_recharge_decimal (string): Tổng số tiền nạp vào workspace thành công chính xác bằng USD được định dạng dưới dạng chuỗi thập phân.
• total_used (number): Tổng chi tiêu sử dụng của workspace bằng USD.
• total_used_decimal (string): Tổng chi tiêu sử dụng của workspace chính xác bằng USD được định dạng dưới dạng chuỗi thập phân.

Các trường tiền tệ hoàn toàn bằng USD. Khi phân tích cú pháp số dư theo phương thức lập trình để kiểm tra ngưỡng hoặc đối soát sổ cái, hãy parse balance_decimal bằng thư viện số thập phân có độ chính xác tùy ý thay vì các kiểu nguyên thủy dấu phẩy động để tránh mất độ chính xác.

Triển Khai Kiểm Tra Số Dư

Các mô hình tích hợp phổ biến bao gồm:

1. Rào chắn trước đợt xử lý (Pre-Batch Guardrails): Trước khi điều phối các khối lượng công việc lớn—chẳng hạn như tạo nội dung quy mô lớn trên các mô hình như gpt-5.5 hoặc glm-5.2—hãy truy vấn /v1/management/balance. Nếu balance_decimal giảm xuống dưới chi phí ước tính của batch, hãy tạm dừng hàng đợi công việc.
2. Cảnh báo số dư thấp: Dù thông báo qua email tự động có thể được định cấu hình trong Console → Settings, một cron giám sát theo lịch trình có thể định kỳ kiểm tra endpoint và kích hoạt các thông báo nội bộ qua Slack, PagerDuty hoặc webhook.
3. Đối soát hóa đơn: Kết hợp số dư workspace trực tiếp với các bản ghi sử dụng của từng key riêng lẻ (/v1/management/api-keys/{keyId}/usage) để đối soát chi phí token với các dòng hóa đơn đã thanh toán.

Để biết thông số kỹ thuật đầy đủ của endpoint và các phương thức quản lý key, hãy xem Tài liệu tham khảo API Get Workspace Balance và Tổng quan về Management API.