Lựa chọn Gói phân phối TokenLab: Auto, Verified hoặc Official

Một yêu cầu có thể thất bại với mã lỗi 503 ngay cả khi ID mô hình hoàn toàn hợp lệ, và nguyên nhân thường nằm ở cấp độ phân phối mà bạn đã ghim (pin). Trong pipeline của chúng tôi, lỗi này xảy ra khi chúng tôi ép buộc một tùy chọn trên một mô hình không hỗ trợ nó. Hướng dẫn này giải thích ba tùy chọn cấp độ phân phối, thứ tự áp dụng các cài đặt và ý nghĩa của từng tùy chọn đối với hóa đơn của bạn. Tất cả thông tin dưới đây được lấy từ tài liệu của TokenLab và API mô hình trực tiếp, ghi nhận vào ngày 03/10/2026.

Những điểm chính cần lưu ý

• Cấp độ phân phối có ba giá trị: auto, verified và official.
• Header của yêu cầu sẽ ghi đè cài đặt API key, và API key sẽ ghi đè cài đặt mặc định của Workspace.
• Nếu tùy chọn được yêu cầu không có nguồn cung, bạn sẽ nhận được lỗi 503 delivery_tier_unavailable. Khi retryable là false, đừng gửi lại cùng một yêu cầu đó.
• Bạn chỉ trả phí một lần cho tùy chọn đã hoàn tất yêu cầu của bạn.
• Hãy kiểm tra GET /v1/models/{model} trước khi ghim một cấp độ. Nó là công khai và không cần API key.

Ba tùy chọn cấp độ phân phối

Tài liệu API reference (ghi nhận ngày 03/10/2026) định nghĩa ba tùy chọn:

• Auto sử dụng TokenLab Verified khi có sẵn, sau đó đến Official nếu cần. Bạn trả phí cho tùy chọn hoàn tất yêu cầu của mình.
• TokenLab Verified là dịch vụ phân phối được xác minh bởi TokenLab. Áp dụng mức giá của TokenLab.
• Official dựa trên giá công khai của nhà sản xuất mô hình. Mức giá hiển thị trên TokenLab là mức bạn phải trả.

Các yêu cầu tạo nội dung (generation requests) chấp nhận header X-TokenLab-Delivery-Policy: auto | verified | official. Giá trị header không hợp lệ sẽ trả về lỗi 400.

Thứ tự ưu tiên của các cài đặt

Có ba nơi có thể thiết lập cấp độ phân phối. Thứ tự ưu tiên được ghi nhận là:

1. Header của yêu cầu.
2. Cài đặt của API key.
3. Cài đặt mặc định của Workspace.

Header ghi đè lên key, và key ghi đè lên Workspace. Các phiên Realtime là ngoại lệ: chúng sử dụng cài đặt API key hoặc Workspace và không chấp nhận ghi đè qua query-string.

Thiết lập cấp độ phân phối trên một yêu cầu

Dưới đây là một lệnh gọi Chat Completions ghim cấp độ Official. ID mô hình claude-sonnet-5 được liệt kê trong API mô hình trực tiếp với cả hai tùy chọn khả dụng. Xem trang mô hình.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: official" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Header tương tự cũng hoạt động trên endpoint Anthropic Messages. Đối với /v1/messages, header chứa key có thể là x-api-key, điều mà tài liệu API xác nhận rằng Anthropic Messages chấp nhận.

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: $TOKENLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: verified" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Thiết lập cấp độ phân phối trên API key

Để đặt cấp độ phân phối mặc định cho một key, hãy sử dụng Management API với management token (mt-...). Các trang Create API Key và Update API Key (cả hai đều ghi nhận ngày 03/10/2026) ghi nhận trường deliveryPolicy. Các giá trị của nó là auto, verified, official, hoặc null. Giá trị null sẽ kế thừa chính sách của Workspace.

Ví dụ này tuân theo định dạng PATCH đã ghi nhận. ID key là giá trị ví dụ trong tài liệu.

curl -X PATCH "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456" \
  -H "Authorization: Bearer mt-your-management-token" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryPolicy": "verified"
  }'

Thao tác cập nhật yêu cầu ít nhất một trường, vì vậy body này là hợp lệ. Các phản hồi báo cáo cài đặt dưới dạng delivery_policy, trong đó null có nghĩa là key kế thừa mặc định của Workspace. Endpoint tạo key cũng chấp nhận cùng trường deliveryPolicy trong body yêu cầu. Việc bỏ qua trường này khi tạo key là nhất quán với cơ chế kế thừa null đã ghi nhận, vì phản hồi ví dụ khi tạo key hiển thị delivery_policy: null.

Khi tùy chọn được yêu cầu không khả dụng

Nếu tùy chọn bạn yêu cầu không có nguồn cung, TokenLab sẽ trả về lỗi 503 delivery_tier_unavailable kèm theo một ID yêu cầu. Hướng dẫn xử lý lỗi (ghi nhận ngày 03/10/2026) giải thích cách đọc giá trị retryable.

Trạng thái 5xx không phải lúc nào cũng có nghĩa là sự cố tạm thời. Khi tùy chọn được chọn không có nguồn cung ở cấp độ đó, retryable sẽ là false và retry_after sẽ bị lược bỏ. Đừng gửi lại cùng một yêu cầu đó. Thay vào đó:

1. Đọc code và retryable, không đọc message dành cho người dùng.
2. Lưu lại Request ID từ header phản hồi.
3. Kiểm tra tính khả dụng của mô hình với GET /v1/models trước khi chọn mô hình hoặc cấp độ khác.

Hướng dẫn cảnh báo rằng các tên mô hình tương tự không đảm bảo tính khả dụng. Client nên phân nhánh xử lý dựa trên code, và chỉ thử lại lỗi 5xx khi retryable là true, đồng thời tuân thủ retry_after và giới hạn số lần thử.

Kiểm tra các tùy chọn của một mô hình

Endpoint mô hình báo cáo delivery availability by option. Các giá trị này đến từ API mô hình trực tiếp, ghi nhận ngày 03/10/2026:

Model ID	Verified	Official	Trang mô hình
claude-sonnet-5	true	true	/models/claude-5/claude-sonnet-5
gpt-5.6-terra	true	true	/models/gpt-5-6/gpt-5.6-terra
deepseek-v4-flash	false	true	/models/deepseek-v4/deepseek-v4-flash

Ví dụ, việc ghim verified trên deepseek-v4-flash là loại yêu cầu sẽ gặp lỗi delivery_tier_unavailable, vì API báo cáo không có nguồn cung Verified hiện tại. Official và Auto vẫn hợp lệ ở đó.

Tự kiểm tra bất kỳ mô hình nào:

curl "https://api.tokenlab.sh/v1/models/deepseek-v4-flash"

Tính khả dụng được kiểm tra khi mỗi yêu cầu chạy, và hướng dẫn Billing nói rằng các nhãn phân phối mô tả các tùy chọn được hỗ trợ. Hãy coi API mô hình như một ảnh chụp nhanh và đọc lại nó trước khi bạn hard-code một cấp độ ghim.

Lựa chọn ảnh hưởng đến chi phí như thế nào

Hướng dẫn Billing (ghi nhận ngày 03/10/2026) cho biết mỗi yêu cầu hoàn tất được tính phí một lần, cho tùy chọn đã tạo ra kết quả:

• TokenLab Verified sử dụng giá công khai của TokenLab.
• Official sử dụng lớp giá Official dựa trên giá công khai của nhà sản xuất mô hình.
• Auto tính phí dựa trên tùy chọn hoàn tất yêu cầu.

Đối với tạo nội dung trả phí, Console hiển thị ước tính tối đa trước khi xác nhận, và phần Usage hiển thị phí cuối cùng. Bất kỳ khoản dự trữ chưa sử dụng nào cũng sẽ được giải phóng. Trên trang Models, dấu gạch ngang trong cột giá TokenLab có nghĩa là không có ưu đãi Verified nào hiện khả dụng. Nó không có nghĩa là miễn phí.

Hướng dẫn không ghi nhận khoảng cách giá cố định giữa Verified và Official, vì vậy chúng tôi sẽ không khẳng định điều đó. Đối với giá TokenLab trực tiếp trên claude-sonnet-5, API mô hình liệt kê đầu vào là 0.9 USD và đầu ra là 4.5 USD trên 1 triệu token (giá cập nhật ngày 02/10/2026). Ước tính, 100,000 token đầu vào cộng với 10,000 token đầu ra là 0.09 + 0.045 = 0.135 USD. Con số đó chỉ sử dụng giá TokenLab được liệt kê. Hãy đọc giá Official trên trang mô hình trước khi so sánh.

Hướng dẫn quyết định nhanh

• Mặc định là Auto khi bạn muốn yêu cầu hoàn tất và có thể chấp nhận bất kỳ lớp giá nào.
• Ghim Verified khi bạn cần giá của TokenLab và mô hình báo cáo verified: true.
• Ghim Official khi bạn cần cơ sở giá công khai của nhà sản xuất mô hình, hoặc khi mô hình không có nguồn cung Verified.
• Thiết lập mặc định cho key đối với các worker luôn cần cùng một cấp độ, và sử dụng header cho các trường hợp ngoại lệ.

Trước khi ghim, hãy đọc GET /v1/models/{model}. Chạy một bài kiểm tra nhỏ và xác nhận phí trong phần Usage.

Bước tiếp theo: tạo key với chính sách phân phối

Tạo API key trong Console, hoặc gọi POST /v1/management/api-keys với management token và thiết lập deliveryPolicy trong body, như được mô tả trong trang Create API Key. Sau đó gửi một yêu cầu nhỏ với header như trên và kiểm tra phí trong Usage.

Câu hỏi thường gặp

Cài đặt nào thắng nếu header, API key và Workspace không đồng nhất?

Header của yêu cầu thắng. Cài đặt API key ghi đè lên mặc định của Workspace. Các phiên Realtime bỏ qua header và sử dụng cài đặt key hoặc Workspace.

Tại sao tôi nhận lỗi 503 delivery_tier_unavailable, và tôi có nên thử lại không?

Cấp độ bạn yêu cầu không có nguồn cung cho thao tác đó. Hãy đọc retryable: khi nó là false, đừng gửi lại cùng yêu cầu đó. Kiểm tra tính khả dụng với GET /v1/models và thay đổi cấp độ hoặc mô hình.

Official có đắt hơn TokenLab Verified không?

Tài liệu không nêu sự khác biệt cố định. Verified sử dụng giá công khai của TokenLab, và Official sử dụng cơ sở giá công khai của nhà sản xuất mô hình. Hãy so sánh cả hai trên trang mô hình và xác nhận phí cuối cùng trong Usage.

Làm thế nào để xem các tùy chọn phân phối mà một mô hình hỗ trợ?

Gọi GET /v1/models/{model}, không cần key. Hiện tại claude-sonnet-5 và gpt-5.6-terra báo cáo cả Verified và Official, trong khi deepseek-v4-flash chỉ báo cáo Official.

Tôi có thể đặt tùy chọn phân phối cho các phiên Realtime không?

Có, thông qua cài đặt API key hoặc Workspace. Các phiên Realtime không chấp nhận ghi đè qua query-string.

Tạo API key TokenLab của bạn trong Console