TokenLab

文字

建立訊息 (Create Message)

使用 Anthropic Messages API 格式建立訊息

POST
/v1/messages

概覽

此端點接受原生的 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)

x-api-keystringheader

您的 TokenLab API 金鑰。請發送 x-api-key 或 Authorization: Bearer <API_KEY>。若您同時發送兩者且值不同,TokenLab 將優先使用 x-api-key。

anthropic-versionstringheader

Anthropic API 版本。Anthropic SDK 會自動為您發送;若直接呼叫 API,請使用 2023-06-01。

anthropic-betastringheader

Anthropic Beta 功能名稱,以逗號分隔。TokenLab 會傳遞此標頭,Beta 功能是否生效取決於模型。引用 file_id 的內容需要 files-api-2025-04-14。

請求主體 (Request Body)

支援的選用參數、接受的值以及預設值取決於所選模型。在設定採樣 (sampling)、推理 (reasoning) 或工具 (tool) 選項之前,請先檢查其 模型詳細資訊。

modelstring必填

支援 anthropic_messages 格式的模型 ID。請檢查其 模型詳細資訊 以了解當前功能。

messagesarray必填

包含 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..." } }
max_tokensinteger必填

生成內容的最大 Token 數。必填:TokenLab 不會添加預設值。可用上限取決於模型;請參閱其 模型詳細資訊 中的 max_output_tokens。較大的數值會增加請求執行期間 TokenLab 從您的餘額中扣留的金額,若餘額不足以支付扣留金額,將回傳 402。

systemstring | array

系統提示詞,可以是字串或文字內容區塊陣列,與 messages 陣列分開。

temperaturenumber

採樣溫度。支援性、允許的值及預設值取決於所選模型;省略此欄位將使用其預設值。

streamboolean預設值: false

將回應作為伺服器發送事件 (SSE) 流回傳。請參閱 串流 (Streaming)。

thinkingobject

原生思考配置,例如 {"type":"enabled","budget_tokens":10000}。支援的模式、預算以及與其他參數的組合取決於所選模型。對於已知會拒絕手動預算的模型,TokenLab 會以自適應思考模式執行 {"type":"enabled"} 並忽略 budget_tokens。

toolsarray

模型可用的工具。支援性取決於所選模型。

tool_choiceobject

原生工具選擇物件,例如 {"type":"auto"}。支援的類型取決於所選模型。

cache_controlobject

提示詞快取標記,例如 {"type":"ephemeral"};添加 "ttl": "1h" 可設定一小時快取。在頂層設定可開啟自動快取。您也可以在 system 區塊、tools 和內容區塊上設定它。支援性取決於模型;支援此功能的模型會在 capabilities 中列出 prompt-cache。

top_pnumber

核採樣 (Nucleus sampling) 參數。請使用 temperature 或 top_p 其中之一,不要同時使用。支援性取決於所選模型。

top_kinteger

僅從每個 Token 的前 K 個選項中進行採樣。支援性取決於所選模型。

stop_sequencesarray

自訂停止序列,將導致模型停止生成。最多 8,191 個項目。

metadataobject

Anthropic 格式的請求元資料。user_id 是您終端使用者的不透明識別碼。

service_tierstring

僅 auto 和 standard_only 有效。TokenLab 僅對標準層級計費,並忽略任何其他值。

回應 (Response)

idstring

唯一訊息識別碼。

typestring

固定為 message。

rolestring

固定為 assistant。

contentarray

內容區塊陣列,例如 text、thinking 或 tool_use。

modelstring

產生回應的模型。

stop_reasonstring

停止生成的原因,例如 end_turn、max_tokens、stop_sequence 或 tool_use。模型可能會回傳其他值,例如 refusal。

stop_sequencestring | null

結束生成的停止序列,若無則為 null。

usageobject

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!"}
    ]
  }'

回應

Response
{
  "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常見原因
400invalid_request_error缺少或無效的欄位、未知的模型,或不接受 Messages 格式的模型
401authentication_errorAPI 金鑰缺失或無效
402billing_error餘額不足以支付請求(error.code 為 insufficient_balance)。達到消費限額的 API 金鑰也會收到 402,此時 error.code 為 quota_exceeded,error.type 為 rate_limit_error
403permission_errorAPI 金鑰無法使用請求的模型,或帳戶被暫停或限制
409conflict_error使用相同的 Idempotency-Key 進行重試。請參閱 使用冪等性金鑰安全重試
413request_too_large請求輸入過大
429rate_limit_error請求過多
500, 502, 503api_error 或 overloaded_error請求無法完成,或目前無可用路由。請稍後重試
504timeout_error請求逾時

相關介面

授權

BearerAuth
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

選填鍵值,用於防止相同請求執行第二次。請為每個請求發送一個新的唯一值(例如 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