Messages API

エンドポイント：POST /v1/messages。リクエストとレスポンスはAnthropicのMessages APIと完全に一致するため、Anthropic SDKや同APIに対応するツールは、ベースURLとキーを変更するだけでKunavoを利用できます。

どのエンドポイントを使えばよいですか？

KunavoではClaudeファミリーを2通りの方法で利用できます。料金は同じです。コードがすでに使っているリクエスト形式に合わせて選んでください。

認証

ベース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の書き込みもAnthropicの2倍より低い1.25倍で請求します。

ストリーミング

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内の画像も同様に処理されます。上限は1リクエストあたり16枚、画像あたり5 MB、合計20 MBです。取得できない画像がある場合はスキップせず、エラーを返します。

使用量オブジェクト

すべてのレスポンス（およびストリーミングのmessage_delta / message_startイベント）には、ネイティブAnthropicのusageオブジェクトが含まれます。

サーバーツール

Anthropicのサーバーツール（web_search、web_fetch、code_execution）は、通常のツール定義としてそのまま渡されます。会話に追加される内容（検索結果、取得したページ、プログラム出力）はusageにトークンとして返され、上記の料金で請求されます。

ウェブ検索は、これらのトークン料金に加えて検索ごとに課金されます。Anthropicの料金は1,000回あたり$10で、Kunavoでは各モデル独自の割引率が適用されます。件数はレスポンス内のusage.server_tool_use.web_search_requests、またはストリームの最後のmessage_deltaに表示されます。max_uses_exceededなど、エラーを返す検索はカウントされません。ウェブ取得とコード実行は、トークン料金以外に費用はかかりません。

対応モデル

有効なClaudeモデルはどれも/v1/messagesを受け付けます。Kunavoのスラッグを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互換のチャット補完
• 課金の仕組み（トークン料金、キャッシュ料金、上乗せ）
• すべてのチャットモデルを見る