Messages API

端点：POST /v1/messages。请求和响应与 Anthropic 的 Messages API 完全一致，因此 Anthropic SDK 或任何支持该协议的工具，只需更换基础 URL 和密钥即可用于 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)

提示缓存

这是使用原生端点的主要原因。可将 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 倍计费。对于 1 小时 TTL 的写入，Kunavo 也按 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 兼容的聊天补全
• 计费方式（token 定价、缓存费率、加价）
• 浏览所有聊天模型