Kimi K3.1 Pro API：エンドポイント、ツール呼び出し、キャッシュ、エラーを徹底解説

Kimi K3.1 Pro API は https://api.moonshot.ai/v1 で動作し、モデル ID は kimi-k3.1-pro と kimi-k3.1-pro-highspeed です。3 つのワイヤーフォーマット、すなわち OpenAI Chat Completions、Responses API、Anthropic Messages に対応しているため、すでに使用している SDK がベース URL を変えるだけで動きます。このモデルは最低 $1 のチャージ後に利用可能になります。

これは本番コード向けのリファレンスです。最初の呼び出し、ストリーミング、Codex や Claude Code のセットアップについては Kimi K3.1 Pro の使い方を、コストについては Kimi K3.1 Pro の料金をご覧ください。事実は Moonshot の K3.1 Pro クイックスタートおよびリンクされたドキュメント（2026 年 10 月 24 日閲覧）に基づいています。

Kimi K3.1 Pro の Responses API、Anthropic API、Chat Completions

Moonshot は K3.1 Pro を 3 つの API サーフェスで公開しています。使用しているクライアントライブラリやエージェントがすでに対応しているものを選んでください。モデル、キー、課金は 3 つすべてで同じです。

これらはキャッシュ TTL の設定方法と usage の格納場所が異なります（後述のキャッシュを参照）。K3 からの移行ですか？ 当社の Kimi K3 API ガイドは引き続き有効です。K3.1 Pro は同じ 1,048,576 トークンのコンテキストを持つ、ポストトレーニング済みの K3 です。

Kimi K3.1 Pro API キー：利用開始とアクセス確認

入金済みのアカウントと、正しいプロダクトのキーが必要です。手順は 4 つです。

1. Kimi API プラットフォームで最低 $1 をチャージします。K3.1 Pro はフラッグシップモデルであり、チャージが成功した後にのみ利用可能になります。
2. API キーコンソールでキーを作成し、MOONSHOT_API_KEY としてエクスポートします。
3. GET /v1/models でそのキーにモデルが見えることを確認します。
4. コードから kimi-k3.1-pro を呼び出します。

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

モデルが一覧にない場合は、まずそれを解決してください。Kimi API、Kimi Code、Kimi Membership は別々のプロダクトです。Kimi Code のキーは API エンドポイントでは動作せず、メンバーシップが API の残高になることもありません。

K3.1 Pro で重要なリクエストパラメータ

ほとんどの OpenAI パラメータは想定どおりに動作します。以下は挙動が異なる、または見落としやすいものです。

推論トークンは usage にカウントされるため、分類や抽出には "low" を使用してください。Preserved Thinking は常に有効なので、すべてのアシスタントメッセージは reasoning_content をそのまま保った状態で返されます（thinking モデルガイド）。

Kimi K3.1 Pro のツール呼び出し：Python による完全なループ

K3.1 Pro での本番ツールループは、Moonshot のドキュメントにある 4 つのルールに従います。

• 最初のターンでは tool_choice="required" でツール呼び出しを強制し、その後 "auto" に切り替えます。
• アシスタントメッセージ全体を、reasoning_content と tool_calls を含めて追加します。
• tool_call_id ごとに 1 つの tool メッセージを送信します。
• 混乱したモデルが永久にループしないよう、ターン数に上限を設けます。

import json, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"],
                base_url="https://api.moonshot.ai/v1")

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

典型的なバグは、msg ではなく msg.content を追加してしまい、tool_calls と reasoning_content が失われることです。

search_tools による大規模なツール呼び出し

エージェントが数十個、あるいは数百個のツールを持つ場合、すべてのリクエストで全定義を送信しないでください。Moonshot の K3 ツール呼び出しベストプラクティスでは、次のフローを推奨しています。

1. 1 つの search_tools 関数（バックエンドで実装）といくつかのコアツールを宣言します。
2. 最初のターンで tool_choice: "required" を設定し、モデルが回答前に取得するようにします。
3. tools フィールドを持つ system メッセージを通じて、一致するツール定義を注入します。
4. 以降のターンでは tool_choice を "auto" に戻し、モデルに読み込まれたツールを呼び出させます。

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

注入された定義はトップレベルの tools フォーマットを使用し、そのメッセージ以降に適用されます。サーバーはそれらを保持しないため、以降のリクエストでもそのメッセージを残してください。tool_choice の変更も、定義の追加も、プレフィックスキャッシュを壊しません。

画像と動画の入力

K3.1 Pro はテキストとともに画像や動画を受け取り、テキストを返します。content をパーツの配列にしてください。image_url パーツ（クイックスタートの例では base64 データ URL を送信しており、公開画像 URL はサポートされないと注記されています）か、ms:// ID を持つアップロード済みファイルを指す video_url パーツです。

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

content をユーザーメッセージとして渡し、完了したら client.files.delete(video.id) でファイルを削除してください。

コードでのコンテキストキャッシュ

キャッシュは繰り返されるプレフィックスに対して自動で行われ、デフォルトの TTL は 5 分です。キャッシュヒットは 100 万トークンあたり $0.20 で課金され、非キャッシュ入力の $2.00 と対比されます。また 1 時間の書き込みは $4.00 で、5 分の $2.00 と対比されます。100 万トークンのプレフィックスでは、1 時間 TTL は 2 回のヒットで元が取れます。

安定したコンテンツ（システムプロンプト、ツール定義、ドキュメント）を先頭に置き、変化するコンテンツを最後に置き、プレフィックスにタイムスタンプを入れないでください。openai SDK では、extra_body を通じて TTL を渡します。

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

Anthropic API ではトップレベルの cache_control フィールドで TTL を設定します。メッセージ内のマーカーは無視されます。

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

キャッシュ使用量がどこに表示されるかはサーフェスによって異なります。

Chat Completions をストリーミングする際は、stream_options.include_usage=true を設定すると最終チャンクで usage を取得できます。各ヒットは TTL を更新し、TTL は最初の書き込み時に固定されます。完全なルールはコンテキストキャッシュガイドをご覧ください。

Kimi K3.1 Pro API のエラーと修正

ほとんどの失敗は 6 つのパターンに分類されます。すべての 429 で error.type を確認してください。修正方法は type によって異なります。

リトライに注意してください。OpenAI SDK はデフォルトで接続エラー、408、409、429、5xx に対して 2 回リトライするため、1 回の呼び出しが RPM に対して 3 リクエストになることがあります。低いティアでは、クライアントの max_retries を下げ、error.type に応じて自分でバックオフしてください。429 で中断されたリクエストは課金されません。

サードパーティ製エージェントが失敗する場合は、同じキー、エンドポイント、モデルで API を直接呼び出してください。それで動作すれば、問題はツール側にあります。トラブルシューティングページとエラーコードをご覧ください。

ティア別の Kimi K3.1 Pro レート制限

累計チャージ額が制限ページでティアを決定します。

Tier0 では 1 分あたり 3 リクエストが許可され、ツールループの各ターンは 1 リクエストです。5 ターンのエージェント実行はそのティアではすでに 1 分を超えてしまうため、エージェントを本格的にテストする前に累計 $10 を予算に入れておいてください。

Apidog CLI で Kimi API をコントラクトテストする

コントラクトテストは、ツールループが tool_calls を返さなくなる日に気づくためのものです。コーディングエージェントに Apidog CLI で構築させましょう。インストールと初回ログインを行います。

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

次に Claude Code、Codex、または使用しているエージェントにプロンプトを送ります。

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

エージェントはスキーマを読み取り、ペイロードを検証し、ケースを実行します。

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

テストケースには有効なカテゴリが必要です。apidog test-case category --project <projectId> で一覧を表示できます。実行が通ったら、-r cli,json を -r junit に --out-dir とともに置き換えれば、同じチェックが CI をゲートします。これは当社の Apidog CLI CI/CD ガイドで示しています。エージェントのセットアップは Claude Code での Apidog CLIにあります。Apidog の Free プランは最大 4 ユーザーまで対応します。

FAQ

Kimi K3.1 Pro API のベース URL は何ですか？

Chat Completions と Responses API には https://api.moonshot.ai/v1、Anthropic 互換の Messages API には https://api.moonshot.ai/anthropic です。

Kimi K3.1 Pro API は thinking パラメータをサポートしていますか？

いいえ。思考は常に有効です。トップレベルの reasoning_effort フィールド（"low"、"high"、"max"）で制御してください。

チャージ直後に 429 が返るのはなぜですか？

error.type を読んでください。engine_overloaded_error はサーバー容量の問題であり、チャージしても解決しません。rate_limit_reached_error はティアの制限を意味し、Tier0 では 3 RPM しか許可されません。

キャッシュが機能しているかどうかを知るには？

usage 内のキャッシュ読み取りフィールドがゼロでなければヒットです。Chat Completions では prompt_tokens_details.cached_tokens、Messages では cache_read_input_tokens です。

Kimi K3.1 Pro API の無料ティアはありますか？

いいえ。API には最低 $1 のチャージが必要です。Kimi アプリでの無料チャットが $0 のルートであり、Kimi K3.1 Pro を無料で使う方法で扱っています。モデルの背景については、Kimi K3.1 Pro とは何かをご覧ください。