Messages API

端點：POST /v1/messages。請求和回應與 Anthropic 的 Messages API 完全一致，因此只要更換基底 URL 和金鑰，便可使用 Anthropic SDK 或任何支援此格式的工具呼叫 Kunavo。

我應該使用哪個端點？

Kunavo 提供兩種方式呼叫 Claude 系列。兩者計費相同；請依你現有程式碼使用的請求格式選擇。

驗證

將基底 URL 設為 https://api.kunavo.com——Anthropic SDK 會自行附加 /v1/messages。將 Kunavo 金鑰（sk-kn-...）作為 API 金鑰傳入；此端點接受透過 x-api-key 標頭（Anthropic SDK 預設）或 Authorization: Bearer 傳入。

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-kn-...",                  # your Kunavo key
    base_url="https://api.kunavo.com",    # SDK appends /v1/messages
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a senior staff engineer.",
    messages=[
        {"role": "user", "content": "Pros and cons of event sourcing?"},
    ],
)
print(msg.content[0].text)

提示快取

這是使用原生端點的主要原因。你可以在任何 system 區塊、訊息內容區塊或工具定義上設定 cache_control 中斷點。標記的前綴會寫入快取一次，之後共用該前綴的呼叫即可重複使用。

快取本身並不需要這個端點：在 /v1/chat/completions 和 /v1/responses 上，對於較長的提示，Kunavo 會自行為 Claude 模型設定中斷點。這個端點的不同之處在於不會新增任何中斷點：請求本文會依你送出的原樣傳遞，因此其中的每個中斷點都是你自己設定的。

# Mark a large, stable prefix with cache_control. The first call writes that
# span to cache at 1.25× the input token price; later calls that reuse it read
# it back at ~10%.
msg = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_STYLE_GUIDE,            # tens of thousands of tokens
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "Review this PR against the guide."}],
)
u = msg.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens)

Kunavo 上 Claude 系列的價格：

• cache_read_input_tokens——從快取提供，按輸入費率的 0.10× 計費（折扣 90%）；在Claude Fable 5.1上的比例為0.025×，在Claude Opus 5.5上的比例為0.05×。
• cache_creation_input_tokens——寫入快取，按輸入費率的 1.25 倍計費。Kunavo 對 1 小時 TTL 的寫入也按 1.25 倍計費，低於 Anthropic 的 2 倍。

串流

設定 stream: true（或使用 SDK 的 stream() 輔助函式）。Kunavo 會原樣轉送 Anthropic 原生事件串流——message_start、content_block_delta、message_delta、message_stop。

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain CRDTs in one paragraph."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

圖片

將圖片以 base64 或 url 來源傳送。url 來源是本文中 Kunavo 會改寫的唯一部分：Kunavo 會自行下載 https 圖片（或解開 data: URI），再以 base64 轉送，因為上游會忽略 url 來源，並像未收到圖片一樣回覆。tool_result 內的圖片也會以相同方式處理。限制：每個請求最多 16 張圖片、每張 5 MB、總計 20 MB；無法取得的圖片會導致錯誤，而不會被略過。

用量物件

每個回應（以及串流的 message_delta／message_start 事件）都會附帶原生 Anthropic usage 物件：

伺服器工具

Anthropic 的伺服器工具（web_search、web_fetch、code_execution）會以一般工具定義的方式轉送。這些工具加入對話的內容（搜尋結果、擷取的網頁或程式輸出）會以 token 形式回傳於 usage，並依上述費率計費。

網頁搜尋除了上述 token 費用外，也會按搜尋次數計費：Anthropic 列出的價格為每 1,000 次搜尋 $10，而 Kunavo 會依各模型自身的折扣收取此費用。搜尋次數位於回應中的 usage.server_tool_use.web_search_requests，或串流的最後一個 message_delta 中；發生錯誤的搜尋（例如 max_uses_exceeded）不會計入。網頁擷取和程式碼執行除 token 費用外不另收費。

支援的模型

任何已啟用的 Claude 模型都接受 /v1/messages。請將 Kunavo slug 作為 model 傳送：

• claude-fable-5, claude-sonnet-5
• claude-opus-5, claude-opus-4-7, claude-opus-4-6
• claude-sonnet-4-6, claude-haiku-4-5

此處無法使用 GPT 模型——請透過 /v1/chat/completions 呼叫。

原始 HTTP

不需要 SDK——此端點接受一般 JSON POST：

curl https://api.kunavo.com/v1/messages \
  -H "x-api-key: sk-kn-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

接下來可以查看

• OpenAI 相容的聊天完成 API
• 計費方式（token 定價、快取費率、加價）
• 瀏覽所有聊天模型