✨ API Đa Định dạng

Tổng quan

TokenLab cung cấp bốn bề mặt giao thức với một khóa API: Chat Completions, Responses, Anthropic Messages và Gemini gốc. Điểm vào gốc chỉ khả dụng khi mô hình công bố định dạng đó và có tuyến upstream cùng giao thức; điểm vào gốc không fallback sang Chat Completions. Chỉ điểm vào Chat có thể biên dịch một chiều sang giao thức đích tương thích.

Định dạng OpenAI

/v1/chat/completions Định dạng tiêu chuẩn, tương thích rộng nhất

Responses

/v1/responses Vòng đời và sự kiện Responses gốc

Định dạng Anthropic

/v1/messages Tư duy mở rộng, các tính năng Claude nguyên gốc

Định dạng Gemini

/v1beta/models/:model:generateContent Tích hợp hệ sinh thái Google

Tại sao hỗ trợ đa định dạng?

Lợi ích	Mô tả
SDK gốc của giao thức	Chỉ dùng SDK gốc với mô hình công bố định dạng đó; Chat vẫn là bề mặt di động rộng nhất
Native features	Truy cập các khả năng riêng theo định dạng
Di chuyển ưu tiên gốc	Giữ các tuyến gốc của nhà cung cấp khi hành vi là quan trọng; dùng khả năng tương thích OpenAI `/v1` cho các client kiểu OpenAI hiện có
Single billing	Một tài khoản, một khóa API, tất cả các định dạng

So sánh định dạng

Tính năng	OpenAI	Anthropic	Gemini
Endpoint	`/v1/chat/completions`	`/v1/messages`	`/v1beta/models/:model:generateContent`
Tiêu đề xác thực	`Authorization: Bearer`	`x-api-key`	`Authorization: Bearer`
System Prompt	Trong mảng `messages`	Trường `system` riêng biệt	Trong `systemInstruction`
Extended Thinking	❌	✅	❌
Phát trực tuyến	✅ SSE	✅ SSE	✅ SSE
Gọi công cụ	✅	✅	✅
Vision	✅	✅	✅

Định dạng OpenAI

Hãy dùng tuyến tương thích này cho các tích hợp OpenAI SDK hiện có và các luồng chat hoặc embedding di động. Với hành vi gốc của Claude hoặc Gemini, hãy dùng định dạng Anthropic hoặc Gemini bên dưới.

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1"
)

# Portable chat works across many models
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # Claude via OpenAI format
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

Phù hợp cho:

Sử dụng chung
Các tích hợp hiện có với OpenAI SDK
Tương thích tối đa

Định dạng Anthropic

API Messages gốc của Anthropic. Cần thiết cho các tính năng riêng của Claude như tư duy mở rộng.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh"  # No /v1 suffix!
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a helpful assistant.",  # Separate system field
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

Tư duy mở rộng (Claude Opus 4.6)

Chỉ có sẵn ở định dạng Anthropic:

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this complex problem..."}]
)

# Access thinking process
for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Answer: {block.text}")

Phù hợp cho:

Các tính năng riêng của Claude
Chế độ tư duy mở rộng
Người dùng Anthropic SDK gốc

Định dạng Gemini

Định dạng API Gemini gốc của Google để tích hợp trong hệ sinh thái Google.

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Hello!"}]
    }],
    "systemInstruction": {
      "parts": [{"text": "You are a helpful assistant."}]
    }
  }'

Phát luồng

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a story"}]}]
  }'

Phù hợp cho:

Tích hợp Google Cloud
Mã nguồn sẵn có với Gemini SDK
Các tính năng gốc của Gemini

Gemini Files và Cache: Tuyến Gemini gốc hỗ trợ /upload/v1beta/files, /v1beta/files, /v1beta/files:register và /v1beta/cachedContents. Files dùng các kênh upstream tương thích Gemini File API; tài nguyên Cache tường minh cũng có thể đi qua kênh Vertex AI. Tài nguyên tạo qua TokenLab được gắn với cùng channel/key upstream cho các lần gọi generateContent sau đó.

Ranh giới tương thích công cụ

Công cụ hàm chỉ có thể được biên dịch một chiều từ điểm vào Chat khi đích biểu diễn được toàn bộ vòng lặp công cụ. Công cụ gốc của nhà cung cấp phải ở lại tuyến gốc của nó:

Công cụ hosted và native của OpenAI Responses như tool_search, web_search, file_search, code_interpreter, MCP, shell/apply_patch và công cụ computer-use cần /v1/responses.
Công cụ server/native của Anthropic như web_search_*, web_fetch_*, code_execution_*, tool_search_*, bash, computer-use và text-editor cần /v1/messages.
Công cụ tích hợp của Gemini như googleSearch, codeExecution, urlContext, computerUse và các trường tools tương tự cần /v1beta.

TokenLab không hạ yêu cầu giao thức gốc xuống Chat Completions. Trường chưa biết và tổ hợp công cụ được chuyển tiếp theo best-effort; upstream được chọn quyết định khả năng hỗ trợ.

Chọn định dạng phù hợp

Hướng dẫn chuyển đổi

Từ API chính thức của OpenAI

# Before (OpenAI)
client = OpenAI(api_key="sk-openai-key")

# After (TokenLab)
client = OpenAI(
    api_key="sk-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1"  # Add this line
)
# That's it! Same code works

Từ API chính thức của Anthropic

# Before (Anthropic)
client = Anthropic(api_key="sk-ant-key")

# After (TokenLab)
client = Anthropic(
    api_key="sk-tokenlab-key",
    base_url="https://api.tokenlab.sh"  # Add this line (no /v1!)
)

Từ Google AI Studio

# Before (Google)
import google.generativeai as genai
genai.configure(api_key="google-api-key")

# After (TokenLab) - Use REST API
import requests

response = requests.post(
    "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent",
    headers={"Authorization": "Bearer sk-tokenlab-key"},
    json={"contents": [{"parts": [{"text": "Hello"}]}]}
)

Khả năng tương thích Chat di động

Dùng /v1/chat/completions khi một client cần truy cập các mô hình được cung cấp bởi nhiều giao thức upstream khác nhau. Yêu cầu Chat di động có thể được biên dịch một chiều sang Responses, Messages hoặc Gemini nếu có thể biểu diễn đầy đủ. Yêu cầu Responses, Messages và Gemini gốc không bao giờ được chuyển thành Chat; tên mô hình hay nhà cung cấp không đồng nghĩa với khả năng gốc.

Ranh giới Responses và Gemini

Bề mặt Responses hiện tại gồm create, compact, retrieve, delete và SSE. Background chỉ hoạt động qua HTTP. WebSocket chỉ nhận response.create; stream là ngầm định, còn background và response.cancel không được cung cấp trên transport này. Delete không phải cancel. Trong Gemini, tên ProtoJSON lowerCamelCase và tên proto gốc snake_case đều là chính thức và được giữ nguyên kể cả trong yêu cầu trộn lẫn. Bề mặt hiện tại gồm list/get models, generateContent, streamGenerateContent, countTokens, embedContent và batchEmbedContents; không gồm Interactions hoặc Live. Trường chưa biết được chuyển tiếp theo best-effort và upstream quyết định khả năng hỗ trợ.

Bắt đầu

Hướng dẫn cốt lõi

Hướng dẫn media

✨ API Đa Định dạng

Tổng quan

Định dạng OpenAI

Responses

Định dạng Anthropic

Định dạng Gemini

Tại sao hỗ trợ đa định dạng?

So sánh định dạng

Định dạng OpenAI

Định dạng Anthropic

Tư duy mở rộng (Claude Opus 4.6)

Định dạng Gemini

Phát luồng

Ranh giới tương thích công cụ

Chọn định dạng phù hợp

Hướng dẫn chuyển đổi

Từ API chính thức của OpenAI

Từ API chính thức của Anthropic

Từ Google AI Studio

Khả năng tương thích Chat di động

Ranh giới Responses và Gemini

​Tổng quan

Định dạng OpenAI

Responses

Định dạng Anthropic

Định dạng Gemini

​Tại sao hỗ trợ đa định dạng?

​So sánh định dạng

​Định dạng OpenAI

​Định dạng Anthropic

​Tư duy mở rộng (Claude Opus 4.6)

​Định dạng Gemini

​Phát luồng

​Ranh giới tương thích công cụ

​Chọn định dạng phù hợp

​Hướng dẫn chuyển đổi

​Từ API chính thức của OpenAI

​Từ API chính thức của Anthropic

​Từ Google AI Studio

​Khả năng tương thích Chat di động

​Ranh giới Responses và Gemini

Tổng quan

Tại sao hỗ trợ đa định dạng?

So sánh định dạng

Định dạng OpenAI

Định dạng Anthropic

Tư duy mở rộng (Claude Opus 4.6)

Định dạng Gemini

Phát luồng

Ranh giới tương thích công cụ

Chọn định dạng phù hợp

Hướng dẫn chuyển đổi

Từ API chính thức của OpenAI

Từ API chính thức của Anthropic

Từ Google AI Studio

Khả năng tương thích Chat di động

Ranh giới Responses và Gemini