Hướng dẫn cốt lõi
Các định dạng API
Chọn Chat Completions, Responses, Messages hoặc Gemini
Một khóa API TokenLab hoạt động với bốn định dạng API phổ biến. Hãy giữ nguyên định dạng mà ứng dụng của bạn đang sử dụng trừ khi bạn cần một tính năng dành riêng cho mô hình.
| Định dạng | Endpoint | Chọn khi |
|---|---|---|
| Chat Completions | /v1/chat/completions | Bạn sử dụng client chat tương thích với OpenAI hoặc muốn khả năng tương thích mô hình rộng rãi |
| Responses | /v1/responses | Ứng dụng của bạn sử dụng các sự kiện Responses, phản hồi nền hoặc các công cụ Responses |
| Anthropic Messages | /v1/messages | Bạn cần các trường Claude Messages như thinking hoặc việc sử dụng công cụ của Claude |
| Gemini | /v1beta/models/:model:generateContent | Bạn đã sử dụng contents, parts, files, cache hoặc các công cụ Gemini |
Kiểm tra tokenlab.accepted_request_formats trên trang mô hình hoặc trong GET /v1/models/{model}. Một mô hình không nhất thiết phải chấp nhận cả bốn định dạng.
Chat Completions
Chat Completions là lựa chọn dễ dàng nhất cho các client tương thích với OpenAI hiện có và các tính năng chat di động.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.chat.completions.create(
model="gpt-5.6-luna",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)Sử dụng định dạng này cho:
- các tích hợp chat tương thích với OpenAI hiện có
- lịch sử tin nhắn và streaming tiêu chuẩn
- gọi hàm (function calling) được hỗ trợ bởi mô hình đã chọn
Các trường duy nhất của định dạng API khác không được đảm bảo hoạt động ở đây.
Responses
Chỉ sử dụng Responses khi mô hình đã chọn liệt kê openai_responses trong accepted_request_formats.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.responses.create(
model="gpt-5.6-terra",
input="Explain why the sky is blue in two sentences.",
)
print(response.output_text)API Responses hỗ trợ tạo, truy xuất, nén, xóa, streaming, tạo và tiếp tục WebSocket, cũng như các phản hồi nền nếu mô hình đã chọn hỗ trợ chúng. Xóa sẽ loại bỏ một phản hồi đã lưu; nó không hủy một phản hồi đang hoạt động.
Anthropic Messages
Sử dụng Anthropic SDK với host TokenLab, không thêm /v1 vào base URL.
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)Chọn Messages cho các trường yêu cầu và phản hồi dành riêng cho Claude. Hãy giữ các lệnh gọi công cụ của Claude, các khối thinking và các trường prompt-cache ở định dạng này.
Gemini
Các yêu cầu Gemini sử dụng host TokenLab và đường dẫn REST của Gemini.
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.6-flash:generateContent" \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Hello!"}]}]
}'Chọn Gemini khi ứng dụng của bạn đã sử dụng các phần nội dung (content parts), khai báo hàm, tệp, nội dung được lưu trong cache hoặc các trường Gemini khác. Cả tên ProtoJSON dạng lowerCamelCase và tên proto dạng snake_case gốc đều được chấp nhận; tránh gửi cả hai cách viết của cùng một trường trong một yêu cầu.
Không trộn lẫn các định dạng trong một cuộc hội thoại
Messages, Responses, Chat Completions và Gemini biểu diễn trạng thái cuộc hội thoại và các lệnh gọi công cụ theo những cách khác nhau. Hãy giữ một định dạng cho một cuộc hội thoại. Nếu bạn phải di chuyển lịch sử đã lưu, hãy chuyển đổi và xác thực nó trong ứng dụng của bạn trước khi gửi yêu cầu tiếp theo.
Các trường không xác định
TokenLab có thể chuyển tiếp các trường mà nó không nhận dạng được, nhưng điều đó không có nghĩa là mọi mô hình đều chấp nhận chúng. Một tính năng chỉ an toàn để phụ thuộc khi mô hình đã chọn ghi lại nó và ứng dụng của bạn xử lý lỗi trường không được hỗ trợ.