Anthropic Messages API

傳送非串流與串流 AIXHUB Anthropic 相容 Messages 請求、檢查回應，並安全重試。

所選 AIXHUB 模型路由支援 Messages 時，請使用 Anthropic 相容介面。原始 HTTP 呼叫使用完整端點 POST https://api.aixhub.org/v1/messages；Anthropic SDK 與客戶端通常使用根 Base URL https://api.aixhub.org，再自行附加 /v1/messages。

設定	值
Anthropic SDK 或相容客戶端 Base URL	`https://api.aixhub.org`
完整 HTTP 端點	`https://api.aixhub.org/v1/messages`
認證	`x-api-key: AIXHUB_API_KEY`
必要版本標頭	`anthropic-version: 2023-06-01`
範例模型	從模型路由複製的 `panel-anthropic-model-id`

執行範例前先建立專用 AIXHUB API 金鑰。不可用 OpenAI Bearer 標頭取代 x-api-key。

Bash 請求

read -rsp "AIXHUB API key: " AIXHUB_API_KEY && echo
export AIXHUB_API_KEY
export AIXHUB_MODEL="panel-anthropic-model-id"

curl --fail-with-body --silent --show-error \
  https://api.aixhub.org/v1/messages \
  --header "x-api-key: $AIXHUB_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data "{\"model\":\"$AIXHUB_MODEL\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK only.\"}]}"

PowerShell 請求

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$env:AIXHUB_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:AIXHUB_MODEL = "panel-anthropic-model-id"

$headers = @{
  "x-api-key" = $env:AIXHUB_API_KEY
  "anthropic-version" = "2023-06-01"
}
$body = @{
  model = $env:AIXHUB_MODEL
  max_tokens = 16
  messages = @(@{ role = "user"; content = "Reply with OK only." })
} | ConvertTo-Json -Depth 4 -Compress

$response = Invoke-RestMethod `
  -Method Post `
  -Uri "https://api.aixhub.org/v1/messages" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body
$response.content |
  Where-Object { $_.type -eq "text" } |
  Select-Object -ExpandProperty text

請把模型替代值換成完整 Messages 相容路由。在可丟棄 Shell 完成測試後，Bash 執行 unset AIXHUB_API_KEY AIXHUB_MODEL。PowerShell 要同時移除環境值與所有持有衍生金鑰的物件：

Remove-Item Env:AIXHUB_API_KEY, Env:AIXHUB_MODEL -ErrorAction SilentlyContinue
Remove-Variable headers, body, response, secureKey -ErrorAction SilentlyContinue

請求欄位

欄位	必要	含義
`model`	是	從 AIXHUB 模型路由複製的完整 Anthropic 相容模型 ID
`max_tokens`	是	最多生成 Token 數量，不代表一定會使用相同數量
`messages`	是	依序排列的使用者與助手回合；最小範例只送出一個使用者回合
`messages[].role`	是	`user` 或 `assistant`；系統指示應放在頂層 `system` 欄位
`messages[].content`	是	字串或支援的內容區塊陣列
`system`	否	頂層系統指示；不可在 `messages` 放入 `system` 角色
`stream`	否	設為 `true` 時接收 Server-Sent Events，不使用單一 JSON 回應
`temperature`	否	只有所選路由接受時才使用的取樣控制

先使用最小欄位。工具、圖片、提示快取或其他選用功能，必須等路由說明確認支援，而且基本請求已出現在用量記錄後再加入。

回應範例

以下 JSON 顯示應檢查的穩定結構。ID 與 Token 數量只供說明，不可寫死。

{
  "id": "msg_01Example",
  "type": "message",
  "role": "assistant",
  "model": "panel-anthropic-model-id",
  "content": [
    {
      "type": "text",
      "text": "OK"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 1
  }
}

從 content 讀取文字區塊，並先檢查 stop_reason 再判定輸出完整。調查失敗時，請保留 HTTP 狀態，以及服務實際回傳時的 request ID 標頭。

串流

加入 "stream": true，並停用 curl 緩衝：

curl --no-buffer --fail-with-body --silent --show-error \
  https://api.aixhub.org/v1/messages \
  --header "x-api-key: $AIXHUB_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data "{\"model\":\"$AIXHUB_MODEL\",\"max_tokens\":16,\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK only.\"}]}"

一般文字串流會依序出現 message_start、content_block_start、一個或多個 content_block_delta、content_block_stop、message_delta 與 message_stop。內容事件之間可能插入 ping。只依事件順序串接文字 delta 內容區塊，並在 message_stop 前儲存最後一筆 message_delta.delta.stop_reason。

message_stop 表示訊息在協定層結束，之後還要檢查儲存的 stop_reason 才能判斷輸出是否完整。這個有邊界的 OK 測試應為 end_turn；max_tokens 代表輸出遭截斷，其他原因則要依應用程式情境處理。串流可能在最初 HTTP 200 後傳送 error 事件；此時要保留錯誤、不可用部分文字推斷成功，並先查看用量再判斷是否適合建立新請求。

錯誤與重試

觀察結果	處理方式	重試規則
400 或無效請求	檢查 JSON、必要欄位、模型 ID 與協定	修正後才重試
401	確認 `x-api-key` 與完整專用金鑰	修正認證後才重試
403	檢查金鑰狀態、分組、訂閱與餘額；`INSUFFICIENT_BALANCE` 是 403	帳戶狀態變更後才重試
413	縮小提示內容或附件	使用較小請求重試
429	降低速率與並行數；實際出現時遵守 `Retry-After`	使用有上限退避與有限次數
502 或 503	保留時間與 request ID，再檢查用量和服務狀態	等待後只做有限次數重試
SSE `error` 事件	把部分輸出視為不完整，並保留事件內容	建立新訊息前先確認接受狀態與用量

模型 ID 或路由問題不一定是 404。任何暫時性重試都最多三次總嘗試（包含原始請求），而且回應實際提供 Retry-After 時必須遵守。除非應用程式明確接受重複輸出與費用，或能證明先前生成未被接受，否則不可重送 5xx、斷線或 SSE error。來源分類與安全診斷請參考錯誤代碼。

驗證

非串流範例應輸出：

OK

串流必須讀到 message_stop，並確認這個有邊界測試最後的 message_delta.delta.stop_reason 是 end_turn；max_tokens 要視為輸出遭截斷，不是完整成功。接著開啟 AIXHUB 用量，核對請求時間、所選模型與成功狀態。用量有顯示協定時，也要確認是 Anthropic 相容路由。

Messages 請求回傳包含 OK 的助手文字區塊，串流到達 message_stop 且 stop_reason 為 end_turn，而且 AIXHUB 記錄的模型與狀態相符。

接著可使用 Anthropic Python SDK，或設定 Claude Code。

官方資料

最後核對：2026-07-14

Anthropic Messages API

本頁目錄