Tham khảo API

Tổng quan

TokenLab là ưu tiên native và tương thích OpenAI. Hãy dùng các tuyến gốc của nhà cung cấp như POST /v1/messages cho Anthropic và /v1beta/models/...:generateContent cho Gemini khi bạn cần hành vi native, và dùng các endpoint /v1 tương thích OpenAI khi bạn đang chuyển đổi các SDK hoặc công cụ theo kiểu OpenAI hiện có. POST /v1/responses vẫn là một đường dẫn tùy chọn nâng cao cho hành vi riêng của Responses.

URL cơ sở

https://api.tokenlab.sh

Xác thực

Yêu cầu mô hình dùng khóa API TokenLab. Header xác thực tiêu chuẩn là:

Authorization: Bearer sk-your-api-key

GET /v1/models, GET /v1/models/{model} và GET /v1/pricing là công khai và không cần khóa. Anthropic Messages còn nhận x-api-key; Gemini nhận x-goog-api-key hoặc ?key= bên cạnh Bearer. /v1/management/* cần token quản lý (mt-...).

Lấy API key của bạn từ Dashboard.

Yêu cầu tạo nội dung nhận X-TokenLab-Delivery-Policy: auto | verified | official. Header ưu tiên hơn thiết lập khóa API, rồi đến mặc định của không gian làm việc. auto ưu tiên TokenLab Verified và dùng Official khi cần; phí dựa trên cách hoàn tất yêu cầu. verified dùng giá TokenLab; official dựa trên giá công khai của nhà sản xuất, theo giá hiển thị trên TokenLab. Realtime dùng thiết lập khóa hoặc không gian làm việc, không ghi đè bằng query. Header sai trả 400; phương thức không khả dụng trả 503 delivery_tier_unavailable cùng ID yêu cầu.

Về Interactive Playground: Playground trên trang tài liệu này chỉ dành cho mục đích minh họa và không hỗ trợ nhập API key. Để kiểm tra API, vui lòng sử dụng:

cURL - Sao chép các lệnh ví dụ và thay thế sk-your-api-key bằng key thực tế của bạn
Postman - Nhập OpenAPI spec của chúng tôi
SDK - Sử dụng OpenAI/Anthropic SDK với base URL của chúng tôi

Các Endpoint được hỗ trợ

Chat & Tạo văn bản

Endpoint	Phương thức	Mô tả
`/v1/chat/completions`	POST	Chat completions tương thích với OpenAI
`/v1/messages`	POST	Messages API tương thích với Anthropic
`/v1/responses`	POST	OpenAI Responses API

Embedding và rerank

Endpoint	Phương thức	Mô tả
`/v1/embeddings`	POST	Tạo text embeddings
`/v1/rerank`	POST	Xếp hạng lại (Rerank) tài liệu

Hình ảnh

Endpoint	Phương thức	Mô tả
`/v1/images/generations`	POST	Tạo hình ảnh từ văn bản
`/v1/images/edits`	POST	Chỉnh sửa hình ảnh
`/v1/images/generations/{id}`	GET	Đường dẫn trạng thái tác vụ hình ảnh cho các phản hồi hình ảnh dựa trên tác vụ

Mô hình ảnh có thể trả về ảnh hoàn chỉnh hoặc tác vụ bất đồng bộ. Nếu phản hồi chứa poll_url, hãy dùng URL đó để tra cứu tác vụ.

Âm thanh

Endpoint	Phương thức	Mô tả
`/v1/audio/speech`	POST	Chuyển đổi văn bản thành giọng nói (TTS)
`/v1/audio/transcriptions`	POST	Chuyển đổi giọng nói thành văn bản (STT)

Thời gian thực

Endpoint	Phương thức	Mô tả
`/v1/realtime?model={model}`	WS	Phiên WebSocket thời gian thực

Dùng /v1/realtime cho yêu cầu upgrade WebSocket. GET /v1/realtime thông thường trả về metadata endpoint cho client không thể kiểm tra trực tiếp route WebSocket. Đây không phải là bề mặt REST của OpenAI Realtime; các endpoint client secret, translation client secret, Calls và legacy beta session hiện chưa được mở.

Video

Endpoint	Phương thức	Mô tả
`/v1/videos/generations`	POST	Tạo tác vụ tạo video
`/v1/tasks/{id}`	GET	Lấy trạng thái tác vụ bất đồng bộ cho các công việc video
`/v1/videos/generations/{id}`	GET	Đường dẫn trạng thái tác vụ video tương thích với phiên bản cũ

Đối với các khách hàng mới, ưu tiên sử dụng /v1/tasks/{id} và làm theo poll_url được trả về bởi các phản hồi tạo. Chỉ giữ lại /v1/videos/generations/{id} để tương thích ngược.

Tác vụ bất đồng bộ (Async Tasks)

Endpoint	Phương thức	Mô tả
`/v1/tasks/{id}`	GET	Endpoint trạng thái tác vụ bất đồng bộ thống nhất. Được khuyến nghị khi làm theo `poll_url` được trả về

Endpoint này không giới hạn ở video, âm nhạc và 3D. Một số tác vụ hình ảnh cũng có thể sử dụng /v1/tasks/{id} làm đường dẫn thăm dò (polling) chuẩn.

Âm nhạc

Endpoint	Phương thức	Mô tả
`/v1/music/generations`	POST	Tạo tác vụ tạo âm nhạc
`/v1/music/generations/{id}`	GET	Đường dẫn trạng thái dành riêng cho âm nhạc

Đối với các khách hàng mới, hãy ưu tiên poll_url được trả về trước. Nếu bạn cần một endpoint trạng thái tác vụ cố định, hãy sử dụng /v1/tasks/{id}; giữ lại /v1/music/generations/{id} cho các đường dẫn tương thích dành riêng cho âm nhạc.

Tạo 3D

Endpoint	Phương thức	Mô tả
`/v1/3d/generations`	POST	Tạo tác vụ tạo mô hình 3D
`/v1/3d/generations/{id}`	GET	Đường dẫn trạng thái dành riêng cho 3D

Đối với các khách hàng mới, hãy ưu tiên poll_url được trả về trước. Nếu bạn cần một endpoint trạng thái tác vụ cố định, hãy sử dụng /v1/tasks/{id}; giữ lại /v1/3d/generations/{id} cho các đường dẫn tương thích dành riêng cho 3D.

Mô hình (Models)

Endpoint	Phương thức	Mô tả
`/v1/models`	GET	Liệt kê tất cả các mô hình có sẵn
`/v1/models/{model}`	GET	Lấy thông tin mô hình cụ thể

Gemini (v1beta)

Hỗ trợ định dạng Google Gemini API gốc:

Endpoint	Phương thức	Mô tả
`/v1beta/models/{model}:generateContent`	POST	Tạo nội dung (định dạng Gemini)
`/v1beta/models/{model}:streamGenerateContent`	POST	Tạo nội dung dạng stream (định dạng Gemini)

Các endpoint Gemini hỗ trợ xác thực qua tham số truy vấn ?key= bên cạnh Bearer token tiêu chuẩn.

Định dạng phản hồi

Mỗi endpoint giữ định dạng API tương ứng. Các ví dụ thành công và lỗi dưới đây dùng định dạng Chat Completions.

Phản hồi thành công

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Tính minh bạch trong điều hướng (Routing)

TokenLab không hiển thị chi tiết nhà cung cấp, kênh, chính sách hoặc thông tin xác thực trong body phản hồi công khai. Không dựa vào _routing hoặc các trường điều hướng nội bộ khác như một phần của hợp đồng API công khai.

Khi cần gỡ lỗi hoặc hỗ trợ, hãy dùng các header phản hồi công khai nếu chúng có trong phản hồi:

Header	Mô tả
`X-Routing-Time-MS`	Thời gian chọn route, nếu có
`X-Request-ID`	Định danh yêu cầu để hỗ trợ và gỡ lỗi, nếu có
`X-Task-ID`	Định danh tác vụ async công khai cho phản hồi dạng tác vụ, nếu có
`X-Billing-Transaction-ID`	Định danh giao dịch billing sau khi billing hoàn tất, nếu có

Phản hồi lỗi

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

Giới hạn tốc độ (Rate Limits)

Giới hạn tốc độ dựa trên vai trò và có thể cấu hình bởi quản trị viên. Các giá trị mặc định:

Vai trò	Yêu cầu/phút
User	1,000
Partner	10,000
VIP	10,000

Liên hệ bộ phận hỗ trợ để biết các giới hạn tốc độ tùy chỉnh. Các giá trị chính xác có thể thay đổi tùy theo cấu hình tài khoản.

Khi vượt quá giới hạn tốc độ, API sẽ trả về mã trạng thái 429 với header Retry-After cho biết thời gian cần chờ đợi.

Thông số kỹ thuật OpenAPI

Đặc tả OpenAPI

Tải xuống thông số kỹ thuật OpenAPI 3.1 đầy đủ

Tham khảo API

Tổng quanCopy Anchor Link

URL cơ sởCopy Anchor Link

Xác thựcCopy Anchor Link

Các Endpoint được hỗ trợCopy Anchor Link

Chat & Tạo văn bảnCopy Anchor Link

Embedding và rerankCopy Anchor Link

Hình ảnhCopy Anchor Link

Âm thanhCopy Anchor Link

Thời gian thựcCopy Anchor Link

VideoCopy Anchor Link

Tác vụ bất đồng bộ (Async Tasks)Copy Anchor Link

Âm nhạcCopy Anchor Link

Tạo 3DCopy Anchor Link

Mô hình (Models)Copy Anchor Link

Gemini (v1beta)Copy Anchor Link

Định dạng phản hồiCopy Anchor Link

Phản hồi thành côngCopy Anchor Link

Tính minh bạch trong điều hướng (Routing)Copy Anchor Link

Phản hồi lỗiCopy Anchor Link

Giới hạn tốc độ (Rate Limits)Copy Anchor Link

Thông số kỹ thuật OpenAPICopy Anchor Link