Cốt lõi
Tham chiếu API
Các endpoint, xác thực, tiêu đề phản hồi và lỗi
Tổng quan
TokenLab hỗ trợ các endpoint tương thích với OpenAI cùng với các định dạng yêu cầu của Anthropic và Gemini. Các client OpenAI hiện có có thể sử dụng /v1; chỉ chọn định dạng khác khi ứng dụng của bạn cần hành vi cụ thể cho API đó. POST /v1/responses là tùy chọn và phụ thuộc vào sự hỗ trợ của model.
Base URL
https://api.tokenlab.shXác thực
Các yêu cầu model sử dụng khóa API TokenLab. Tiêu đề xác thực tiêu chuẩn là:
Authorization: Bearer sk-your-api-keyGET /v1/models, GET /v1/models/{model}, GET /v1/models/{model}/pricing, và GET /v1/pricing là công khai và không cần khóa. Anthropic Messages cũng chấp nhận x-api-key; Gemini chấp nhận x-goog-api-key hoặc ?key= cũng như xác thực Bearer. /v1/management/* yêu cầu một token quản lý (mt-...).
Lấy khóa API của bạn từ Console.
Chính sách phân phối
Các yêu cầu tạo (generation) chấp nhận X-TokenLab-Delivery-Policy: auto | verified | official. Tiêu đề yêu cầu sẽ ghi đè cài đặt khóa API, vốn ghi đè mặc định của Workspace.
Autosử dụng TokenLab Verified khi có sẵn, sau đó là Official nếu cần. Bạn trả phí cho tùy chọn hoàn thành yêu cầu của mình.TokenLab Verifiedlà dịch vụ được xác minh bởi TokenLab. Giá Verified sẽ được áp dụng.Officialtính phí theo giá Official, là giá đã công bố của nhà sản xuất model.- Các phiên Realtime sử dụng khóa API hoặc cài đặt Workspace và không chấp nhận ghi đè từ yêu cầu.
Tiêu đề không hợp lệ sẽ trả về 400. Nếu tùy chọn được yêu cầu không khả dụng, TokenLab trả về 503 delivery_tier_unavailable cùng với ID yêu cầu. Đọc retryable: khi thao tác đã chọn không có nguồn cung, giá trị này là false. Không lặp lại cùng một yêu cầu mà không thay đổi.
Các trang API có biểu mẫu yêu cầu sẽ chấp nhận khóa API TokenLab của bạn và gửi các yêu cầu thực tế. Các yêu cầu này sử dụng số dư và giới hạn tài khoản của bạn. Bạn cũng có thể sử dụng cURL, Postman hoặc SDK.
Các Endpoint được hỗ trợ
Chat & Tạo văn bản
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/chat/completions | POST | Hoàn thành chat tương thích với OpenAI |
/v1/messages | POST | Messages tương thích với Anthropic |
/v1/messages/count_tokens | POST | Đếm token đầu vào của một yêu cầu Messages |
/v1/messages/batches | POST, GET | Tạo và liệt kê Message Batches |
/v1/messages/batches/{message_batch_id} | GET, DELETE | Truy xuất hoặc xóa một Message Batch |
/v1/messages/batches/{message_batch_id}/results | GET | Đọc kết quả |
/v1/messages/batches/{message_batch_id}/cancel | POST | Hủy một Message Batch |
/v1/responses | POST | API OpenAI Responses |
/v1/responses/{id} | GET, DELETE | Truy xuất hoặc xóa một phản hồi đã lưu |
/v1/responses/compact | POST | Nén ngữ cảnh của một cuộc hội thoại Responses |
/v1/translations | POST | Dịch văn bản sang văn bản |
Embeddings & Rerank
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/embeddings | POST | Tạo embeddings văn bản |
/v1/multimodal/embeddings | POST | Tạo embeddings với model embedding đa phương thức |
/v1/rerank | POST | Xếp hạng lại tài liệu |
Quyết định (Decisions)
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/systemone | POST | Đánh giá các câu hỏi quyết định có kiểu dữ liệu |
Tệp & Batches
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/files | POST, GET | Tải lên và liệt kê tệp |
/v1/files/{file_id} | GET, DELETE | Truy xuất hoặc xóa tệp |
/v1/files/{file_id}/content | GET | Tải xuống nội dung tệp |
/v1/batches | POST, GET | Tạo và liệt kê batches |
/v1/batches/{batch_id} | GET | Truy xuất một batch |
/v1/batches/{batch_id}/cancel | POST | Hủy một batch |
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/variations | POST | Tạo các biến thể hình ảnh |
/v1/images/generations/{id} | GET | Đường dẫn trạng thái tương thích cho các phản hồi hình ảnh dựa trên tác vụ |
Các model hình ảnh có thể trả về một hình ảnh đã hoàn thành hoặc một tác vụ bất đồng bộ. Nếu phản hồi bao gồm status: "pending" hoặc ID tác vụ, hãy poll GET /v1/tasks/{id}.
Âm thanh
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/audio/speech | POST | Chuyển văn bản thành giọng nói (TTS) |
/v1/audio/transcriptions | POST | Chuyển giọng nói thành văn bản (STT) |
/v1/audio/translations | POST | Dịch giọng nói sang văn bản tiếng Anh |
Realtime
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/realtime?model={model} | WS | Các phiên WebSocket thời gian thực |
Sử dụng /v1/realtime để nâng cấp WebSocket. Một yêu cầu GET /v1/realtime thông thường sẽ trả về metadata của endpoint. Đây không phải là giao diện REST Realtime của OpenAI; client-secret, Calls và các endpoint phiên beta cũ không khả dụng.
Video
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/videos/generations | POST | Tạo tác vụ tạo video |
/v1/videos/generations/{id} | GET | Đường dẫn trạng thái tương thích |
/v1/videos/assets | POST, GET | Tạo và liệt kê tài sản vật liệu Seedance |
/api/v3/contents/generations/tasks | POST, GET | Các tác vụ Seedance với định dạng yêu cầu Volcengine |
Poll GET /v1/tasks/{id} với id của tác vụ. /v1/videos/generations/{id} vẫn khả dụng cho các tích hợp hiện có.
Tác vụ bất đồng bộ (Async Tasks)
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/tasks/{id} | GET | Trạng thái cho bất kỳ tác vụ bất đồng bộ nào |
/v1/tasks/{id} | DELETE | Hủy một tác vụ bất đồng bộ |
Poll GET /v1/tasks/{id} cho mọi tác vụ bất đồng bộ: hình ảnh, video, âm nhạc, 3D, Worlds và chuyển đổi âm thanh bất đồng bộ. Sử dụng id hoặc task_id từ phản hồi tạo. Phản hồi tạo Worlds trả về một poll_url dưới /v1/worlds/generations/{id}; hãy poll /v1/tasks/{id} tại đó. Các đường dẫn trạng thái theo phương thức trên trang này là các endpoint tương thích cho các tích hợp hiện có.
Â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 tương thích |
Tạo 3D
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/3d/generations | POST | Tạo tác vụ tạo model 3D |
/v1/3d/generations/{id} | GET | Đường dẫn trạng thái tương thích |
Worlds
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/worlds/generations | POST | Tạo tác vụ tạo thế giới |
/v1/worlds/list | POST | Liệt kê các thế giới |
/v1/worlds/{id} | GET, DELETE | Truy xuất hoặc xóa một thế giới |
/v1/worlds/media-assets/prepare-upload | POST | Chuẩn bị tải lên tài sản phương tiện |
Models & Định giá
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1/models | GET | Liệt kê tất cả các model khả dụng |
/v1/models/{model} | GET | Lấy thông tin model cụ thể |
/v1/models/{model}/pricing | GET | Lấy giá của một model |
/v1/pricing | GET | Liệt kê giá model |
Gemini (v1beta)
Hỗ trợ định dạng API Google Gemini gốc:
| Endpoint | Phương thức | Mô tả |
|---|---|---|
/v1beta/models | GET | Liệt kê các model chấp nhận yêu cầu Gemini |
/v1beta/models/{model} | GET | Lấy một model |
/v1beta/models/{model}:generateContent | POST | Tạo nội dung |
/v1beta/models/{model}:streamGenerateContent | POST | Tạo nội dung dạng stream |
/v1beta/models/{model}:countTokens | POST | Đếm token |
/v1beta/files, /v1beta/cachedContents | POST, GET, DELETE | Tệp Gemini và nội dung được lưu cache |
Các endpoint Gemini hỗ trợ xác thực bằng tham số truy vấn ?key= ngoài token Bearer tiêu chuẩn.
Quản lý
/v1/management/* quản lý số dư, khóa API và webhook bằng token quản lý. Xem API Quản Lý.
Định dạng phản hồi
Mỗi endpoint bảo toàn định dạng API của nó. Các ví dụ thành công và lỗi dưới đây sử 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
}
}Tiêu đề phản hồi
Sử dụng các tiêu đề này khi chúng xuất hiện.
| Tiêu đề | Mô tả |
|---|---|
X-Request-ID | Định danh yêu cầu để hỗ trợ và gỡ lỗi |
X-Routing-Time-MS | Không streaming: tổng thời gian (mili giây) đến khi upstream phản hồi, bao gồm hàng đợi và suy luận của upstream. Streaming: luôn là 0. Không phải số đo định tuyến hay hàng đợi. |
X-Task-ID | Định danh tác vụ bất đồng bộ công khai cho các phản hồi dựa trên tác vụ |
X-Billing-Transaction-ID | Định danh giao dịch thanh toán sau khi thanh toán hoàn tất |
Các yêu cầu bị từ chối chính thức có thể bao gồm upstream với lỗi được dịch vụ báo cáo và tên dịch vụ công khai. Xem Xử lý lỗi API.
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)
Các giới hạn phụ thuộc vào cấp độ tài khoản và áp dụng cho mỗi khóa API. Phản hồi 429 sẽ mang theo Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Xem Giới hạn tốc độ để biết các cấp độ và cách thử lại.
Đặc tả OpenAPI
OpenAPI Spec
Tải xuống đặc tả OpenAPI 3.1 đầy đủ