文字
建立訊息 (Create Message)
使用 Anthropic Messages API 格式建立訊息
概覽
此端點接受原生的 Anthropic Messages 格式,因此 Anthropic SDK 以及基於其構建的工具均可與 TokenLab 的基礎 URL 搭配使用。它適用於 accepted_request_formats 中列出 anthropic_messages 的模型:例如 Claude 模型及其他部分模型。
messages 包含 user 和 assistant 的對話輪次。請將系統指令放入頂層的 system 欄位中。max_tokens 為必填項。若要使用具有 system 或 tool 等角色的 OpenAI 風格訊息,請參閱 聊天補全 (Chat Completions)。
Anthropic SDK 的基礎 URL:https://api.tokenlab.sh(無 /v1 後綴)
請求標頭 (Request Headers)
您的 TokenLab API 金鑰。請發送 x-api-key 或 Authorization: Bearer <API_KEY>。若您同時發送兩者且值不同,TokenLab 將優先使用 x-api-key。
Anthropic API 版本。Anthropic SDK 會自動為您發送;若直接呼叫 API,請使用 2023-06-01。
Anthropic Beta 功能名稱,以逗號分隔。TokenLab 會傳遞此標頭,Beta 功能是否生效取決於模型。引用 file_id 的內容需要 files-api-2025-04-14。
請求主體 (Request Body)
支援的選用參數、接受的值以及預設值取決於所選模型。在設定採樣 (sampling)、推理 (reasoning) 或工具 (tool) 選項之前,請先檢查其 模型詳細資訊。
支援 anthropic_messages 格式的模型 ID。請檢查其 模型詳細資訊 以了解當前功能。
包含 role(user 或 assistant)和 content 的訊息物件陣列。最多支援 100,000 條訊息。
content 可以是純字串或內容區塊陣列。若要發送圖片,請使用結構化的內容區塊,而非直接將圖片 URL 或 Base64 字串放入純文字中。對於支援的模型,也接受其他原生區塊,例如 tool_use、tool_result、thinking 和 document。
內容區塊範例:
- 文字區塊:
{ "type": "text", "text": "描述這張圖片" } - URL 圖片區塊:
{ "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } } - Base64 圖片區塊:
{ "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
生成內容的最大 Token 數。必填:TokenLab 不會添加預設值。可用上限取決於模型;請參閱其 模型詳細資訊 中的 max_output_tokens。較大的數值會增加請求執行期間 TokenLab 從您的餘額中扣留的金額,若餘額不足以支付扣留金額,將回傳 402。
系統提示詞,可以是字串或文字內容區塊陣列,與 messages 陣列分開。
採樣溫度。支援性、允許的值及預設值取決於所選模型;省略此欄位將使用其預設值。
false將回應作為伺服器發送事件 (SSE) 流回傳。請參閱 串流 (Streaming)。
原生思考配置,例如 {"type":"enabled","budget_tokens":10000}。支援的模式、預算以及與其他參數的組合取決於所選模型。對於已知會拒絕手動預算的模型,TokenLab 會以自適應思考模式執行 {"type":"enabled"} 並忽略 budget_tokens。
模型可用的工具。支援性取決於所選模型。
原生工具選擇物件,例如 {"type":"auto"}。支援的類型取決於所選模型。
提示詞快取標記,例如 {"type":"ephemeral"};添加 "ttl": "1h" 可設定一小時快取。在頂層設定可開啟自動快取。您也可以在 system 區塊、tools 和內容區塊上設定它。支援性取決於模型;支援此功能的模型會在 capabilities 中列出 prompt-cache。
核採樣 (Nucleus sampling) 參數。請使用 temperature 或 top_p 其中之一,不要同時使用。支援性取決於所選模型。
僅從每個 Token 的前 K 個選項中進行採樣。支援性取決於所選模型。
自訂停止序列,將導致模型停止生成。最多 8,191 個項目。
Anthropic 格式的請求元資料。user_id 是您終端使用者的不透明識別碼。
僅 auto 和 standard_only 有效。TokenLab 僅對標準層級計費,並忽略任何其他值。
回應 (Response)
唯一訊息識別碼。
固定為 message。
固定為 assistant。
內容區塊陣列,例如 text、thinking 或 tool_use。
產生回應的模型。
停止生成的原因,例如 end_turn、max_tokens、stop_sequence 或 tool_use。模型可能會回傳其他值,例如 refusal。
結束生成的停止序列,若無則為 null。
Token 使用量,包含 input_tokens 和 output_tokens。當模型回報提示詞快取 Token 時,usage 還會包含 cache_creation_input_tokens 和 cache_read_input_tokens。
每個回應都在 request-id 和 X-Request-ID 標頭中包含請求 ID。聯繫支援團隊時請提供此 ID。
請求
curl -X POST "https://api.tokenlab.sh/v1/messages" \
-H "x-api-key: sk-your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"system": "You are a helpful assistant.",
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'回應
{
"id": "msg_abc123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! How can I help you today?"
}
],
"model": "claude-sonnet-5",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 15,
"output_tokens": 10
}
}視覺輸入範例 (Vision Input Example)
對於支援視覺功能的 Claude 模型,請將圖片作為結構化圖片區塊放入 messages[].content 中。
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "請描述這張圖片。"
},
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/demo.jpg"
}
}
]
}
]
}{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "請描述這張圖片。"
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQ..."
}
}
]
}
]
}擴展思考範例 (Extended Thinking Example)
使用具有 reasoning 功能的模型。請根據模型的限制調整 max_tokens 和 budget_tokens;部分模型需要不同的思考配置。
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000
},
messages=[{"role": "user", "content": "解決這個數學問題..."}]
)
for block in message.content:
if block.type == "thinking":
print(f"思考中: {block.thinking}")
elif block.type == "text":
print(f"回應: {block.text}")串流 (Streaming)
設定 "stream": true 以接收 Anthropic 伺服器發送事件:message_start、content_block_start、content_block_delta、content_block_stop、message_delta 和 message_stop。Token 使用量會出現在 message_start 和 message_delta 中。
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "給我講個故事"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)- 當模型運作時,串流可能會攜帶 SSE 註解行,例如
: keep-alive。SDK 會忽略它們。 - 當發生錯誤時,HTTP 狀態碼可能已經是
200。串流開始後的錯誤會以event: error事件形式傳送,並包含與下方相同的錯誤主體。
錯誤 (Errors)
錯誤使用 Anthropic 錯誤格式。request_id 是 TokenLab 的請求 ID。部分錯誤會添加 code 和 hint 等欄位。
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens: 必填。/v1/messages 遵循原生的 Anthropic 合約,不會推斷預設的 max_tokens 值。"
},
"request_id": "req_01JEXAMPLE"
}| 狀態碼 | error.type | 常見原因 |
|---|---|---|
| 400 | invalid_request_error | 缺少或無效的欄位、未知的模型,或不接受 Messages 格式的模型 |
| 401 | authentication_error | API 金鑰缺失或無效 |
| 402 | billing_error | 餘額不足以支付請求(error.code 為 insufficient_balance)。達到消費限額的 API 金鑰也會收到 402,此時 error.code 為 quota_exceeded,error.type 為 rate_limit_error |
| 403 | permission_error | API 金鑰無法使用請求的模型,或帳戶被暫停或限制 |
| 409 | conflict_error | 使用相同的 Idempotency-Key 進行重試。請參閱 使用冪等性金鑰安全重試 |
| 413 | request_too_large | 請求輸入過大 |
| 429 | rate_limit_error | 請求過多 |
| 500, 502, 503 | api_error 或 overloaded_error | 請求無法完成,或目前無可用路由。請稍後重試 |
| 504 | timeout_error | 請求逾時 |
相關介面
授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,用於防止相同請求執行第二次。請為每個請求發送一個新的唯一值(例如 UUID),並在逾時重試時保留該值。使用相同鍵值的重試不會再次執行:它會回傳 409 狀態碼與 idempotency_replay_unavailable,若請求主體已變更,通常會回傳 idempotency_conflict。例外情況:若非串流(non-stream)結果在客戶端斷線後完成,則 24 小時內使用相同鍵值與主體的重試會回傳該結果(上限 1 MB),並帶有 Idempotent-Replayed: true 標頭,且不會進行第二次扣款。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json