> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Kimi K3 実測呼び出しガイド：新パラメータと3インターフェース対応マトリクス > 2026年7月の Kimi K3 呼び出しガイド：reasoning_effort max と思考履歴の返送、動的ツールロード、構造化出力、自動キャッシュ、partial 継続生成、視覚入力を解説。AIHubMix の Chat / Responses / Messages 3 インターフェース例付き。 Kimi K3 実測呼び出しガイド：思考モード、動的ツールロードとコンテキストキャッシュ > 本記事では [Kimi K3](https://aihubmix.com/model/kimi-k3) の新パラメータと呼び出し時の注意点を解説します。K3 は AIHubMix で Chat Completions、Responses、および Claude 互換の Messages インターフェースから呼び出せます。あわせて参照：[Moonshot 公式プラットフォームドキュメント](https://platform.moonshot.ai/docs)。 > > 各節の「実測」結論とレスポンス例は、いずれも 2026-07-17 に AIHubMix インターフェース（Chat Completions / Responses / Messages）経由で実際に呼び出して得たものです。 ## 1. モデル仕様クイックリファレンス | 項目 | 値 | | :---------- | :------------------------------------------------- | | コンテキストウィンドウ | 1M tokens | | 最大出力 | `max_completion_tokens` デフォルト 131,072、最大 1,048,576 | | 入力モダリティ | テキスト、画像（動画入力は Moonshot 公式ドキュメントを参照） | | 思考モード | デフォルトで有効、`reasoning_effort` は `"max"` のみ対応 | | 停止シーケンス | `stop` は最大 5 個、各 32 バイト以内 | > **実測**：`stop` の 2 つの上限はいずれも検証され、超過すると 400 が返ります。Messages インターフェースの `stop_sequences` にも同じ検証が適用されます。 > > ❗ **Messages インターフェースで停止語にヒットした場合、Anthropic のセマンティクスどおりには返りません**：実測では `stop_reason` が `"end_turn"`（`"stop_sequence"` ではなく）、`stop_sequence` が `null` となり、停止語より前の可視テキストが空になることがあります。この 2 つのフィールドで打ち切り理由を判定しているクライアントは注意が必要です。 ```text theme={null} # stop with 6 entries / a 33-byte entry -> HTTP 400 "Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead" "Invalid request: stop sequence must not be longer than 32, but got 33 instead" ``` ## 2. 思考モード：`reasoning_effort` は `max` のみ K3 の思考はデフォルトで有効になっており、`reasoning_effort` は `"max"` の 1 段階のみ対応します。 **マルチターン会話では思考履歴をそのまま返送する必要があります**：Moonshot 公式の説明によると、K3 は preserved thinking 方式で学習されており、マルチターン会話では前のターンで返された assistant メッセージ（思考内容を含む）を**そのまま完全に**返送する必要があります。思考履歴が欠落すると出力品質が不安定になります。会話管理フレームワークやプロキシ層を使用する場合は、返送前に思考内容が切り詰められていないことを確認してください。 思考内容はレスポンスの `reasoning_content` フィールドで返されます。マルチターンでは前のターンの assistant メッセージ（`reasoning_content` を含む）をそのまま返送してください。 ```text theme={null} from openai import OpenAI client = OpenAI( base_url="https://aihubmix.com/v1", api_key="", ) completion = client.chat.completions.create( model="kimi-k3", reasoning_effort="max", messages=[ {"role": "user", "content": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"} ], ) print(completion.choices[0].message.reasoning_content) print(completion.choices[0].message.content) ``` ```text theme={null} # Multi-turn: pass the previous assistant message back verbatim messages = [ {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris.", "reasoning_content": ""}, {"role": "user", "content": "And its population?"}, ] ``` > **実測**：レスポンスに `reasoning_content` が返されます。前のターンの assistant メッセージ（`reasoning_content` を含む）をそのまま返送すると、以降のターンも正常に応答します。 思考内容は `reasoning` 出力項目として返されます。マルチターンでは前のターンの出力項目（`reasoning` + `message`）をそのまま `input` に連結して返送してください。 ```text theme={null} from openai import OpenAI client = OpenAI( base_url="https://aihubmix.com/v1", api_key="", ) response = client.responses.create( model="kimi-k3", input="Answer in one word: capital of France", ) # Observed response.output item types: ["reasoning", "message"]; text: "Paris" # Multi-turn: input = [first user message] + response.output + [next user message] # Observed second-turn answer with output items passed back: "Berlin" ``` 思考内容はネイティブの `thinking` コンテンツブロックとして返されます。マルチターンでは前のターンの assistant のコンテンツブロック（thinking ブロックを含む）をそのまま返送してください。 ```text theme={null} from anthropic import Anthropic client = Anthropic( api_key="", base_url="https://aihubmix.com" ) response = client.messages.create( model="kimi-k3", max_tokens=4096, messages=[ {"role": "user", "content": "Answer in one word: capital of France"} ], ) # Observed response.content block types: ["thinking", "text"]; text: "Paris" # Multi-turn: pass response.content back verbatim as the assistant message ``` ## 3. サンプリングパラメータは固定値 K3 のサンプリングパラメータは公式の固定値です：`temperature` 1.0、`top_p` 0.95、`n` 1、`presence_penalty` / `frequency_penalty` 0。公式はリクエストにこれらのパラメータを含めないことを推奨しています。 > **補足**：サンプリングの固定値は公式仕様であり、レスポンスのシグナルから検証することはできません。公式の推奨どおり、これらのパラメータは省略してください。 ## 4. ツール呼び出しと動的ツールロード `tools` は最大 128 個のツールに対応します。`tool_choice` はツール呼び出しの強制と無効化に対応します。さらに K3 は動的ツールロードに対応しており、会話の途中で system メッセージの `tools` フィールドを通じて新しいツールを注入できます（Chat インターフェース特有のメッセージ形式）。 `tool_choice` は `auto` / `none` / `required` に対応し、`required` はモデルにツール呼び出しを強制します。動的ツールロード：ツールを注入する system メッセージには `content` を付けません。注入されたツールは以降のターンで有効になり、各ターンのリクエストで毎回含める必要があります。 ```text theme={null} messages = [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello."}, {"role": "assistant", "content": "Hi, how can I help you?"}, # Inject a new tool mid-conversation: tools field only, no content { "role": "system", "tools": [ { "type": "function", "function": { "name": "get_time", "description": "Get the current time", "parameters": {"type": "object", "properties": {}}, }, } ], }, {"role": "user", "content": "What time is it now?"}, ] ``` ```text theme={null} # tool_choice="required" with prompt "Hello" -> the model is forced to call the tool "finish_reason": "tool_calls", "tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}] ``` > **実測**：`tool_choice: "required"` は無関係な質問に対してもツール呼び出しを強制的に発生させます。`"none"` はツール呼び出しを抑制します。`content` なしの system メッセージで途中注入したツールは正常に呼び出せます。 ツール定義はフラットな構造（`name` がトップレベル）で、強制呼び出しは同じく `tool_choice: "required"` を使用し、呼び出しは `function_call` 出力項目として返されます。動的ツールロードは対応準備中のため、現時点ではトップレベルの `tools` パラメータで全ツールを宣言してください。 ```text theme={null} response = client.responses.create( model="kimi-k3", input="Hello", tools=[{ "type": "function", "name": "get_weather", "description": "Get weather for a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, }], tool_choice="required", ) # Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"} ``` ツールは Anthropic 形式（`input_schema`）で定義し、強制呼び出しは `tool_choice: {"type": "any"}`、無効化は `{"type": "none"}` です。❗ **Kimi K3 公式の Messages（Anthropic 互換）エンドポイントは動的ツールロードに対応していません**：実測では注入メッセージに 200 が返るものの、注入されたツールは機能しません（モデルは呼び出せません）。トップレベルの `tools` パラメータで全ツールを宣言してください。 ```text theme={null} response = client.messages.create( model="kimi-k3", max_tokens=4096, tools=[{ "name": "get_weather", "description": "Get weather for a city", "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, }], tool_choice={"type": "any"}, messages=[{"role": "user", "content": "Hello"}], ) # Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather ``` ## 5. 構造化出力 構造化出力を使うと、指定した JSON Schema に厳密に準拠した内容をモデルに返させることができます。 `response_format` は `json_schema` と `strict` モードに対応します。 ```text theme={null} completion = client.chat.completions.create( model="kimi-k3", messages=[ {"role": "user", "content": "Paris is the capital of France. Extract the city name."} ], response_format={ "type": "json_schema", "json_schema": { "name": "extract", "strict": True, "schema": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, }, }, ) # Observed response content: {"city":"Paris"} ``` > **実測**：schema に準拠した正しい JSON が出力されます。 構造化出力は `text.format` で宣言します。 ```text theme={null} response = client.responses.create( model="kimi-k3", input="Paris is the capital of France. Extract the city name.", text={ "format": { "type": "json_schema", "name": "extract", "strict": True, "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, } }, ) # Observed output text: {"city":"Paris"} ``` ❗ **Kimi K3 公式の Messages（Anthropic 互換）エンドポイントは構造化出力に対応していません**：構造化出力フィールドはサイレントに無視されます。リクエストは HTTP 200 と自由形式テキストを返し、エラーもフォールバックの通知もないため、下流の JSON パースは失敗します。構造化出力が必要な場合は Chat Completions または Responses インターフェースを使用してください。 ## 6. コンテキストキャッシュは自動で有効 K3 のコンテキストキャッシュは自動的に有効になり、パラメータを渡す必要はありません。繰り返しの長いプレフィックスがキャッシュにヒットすると、ヒット量が usage で報告されます（フィールド名はインターフェースにより異なります）。キャッシュ料金は[モデルページ](https://aihubmix.com/model/kimi-k3)をご覧ください。 ```text theme={null} # usage of the second call with an identical long prefix "prompt_tokens_details": {"cached_tokens": 1536} ``` > **実測**：同一の長いプレフィックスによる 2 回目のリクエストでは、`usage.prompt_tokens_details.cached_tokens` にヒット量が報告されます。 ```text theme={null} # usage of the second Responses call with identical long instructions "input_tokens_details": {"cached_tokens": 1536} ``` ```text theme={null} # usage of the second Messages call with an identical long system prompt "cache_read_input_tokens": 1536 ``` ## 7. `partial` プレフィックス継続生成 プレフィックス継続生成は、指定したプレフィックスから続きをモデルに生成させる機能で、コード補完や形式を制御した出力に適しています。 最後の assistant メッセージに `"partial": true` を指定します。 ```text theme={null} messages = [ {"role": "user", "content": "Write a haiku about the sea."}, {"role": "assistant", "content": "Waves fold into foam,", "partial": True}, ] # Prefix: "Waves fold into foam," -> continuation returned by the model # salt hangs in the air— # moon pulls the tide home. ``` > **実測**：生成は指定したプレフィックスから継続し、プレフィックスを繰り返しません。 プレフィックスを `input` 配列末尾の assistant メッセージとして渡します。`partial` パラメータは不要です。 ```text theme={null} response = client.responses.create( model="kimi-k3", input=[ {"role": "user", "content": "Write a haiku about the sea."}, {"role": "assistant", "content": "Waves fold into foam,"}, ], ) # Observed continuation: "salt hangs in the air— / moon pulls the tide home." ``` プロトコルネイティブの assistant プレフィルで同等の機能を実現できます。`partial` パラメータは不要で、プレフィックスを最後の assistant メッセージとして渡すだけです。 ```text theme={null} response = client.messages.create( model="kimi-k3", max_tokens=4096, messages=[ {"role": "user", "content": "Write a haiku about the sea."}, {"role": "assistant", "content": "Waves fold into foam,"}, ], ) # Observed continuation: "salt wind carries the gull's cry— / tide pulls ..." ``` ## 8. 視覚入力 画像は base64 で渡します。コンテンツブロックの書き方はインターフェースにより異なります。 ```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "What is the dominant color of this image? One word."}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,"}}, ], } ] # Observed response content: "Red" (input: a 64x64 solid red PNG) ``` > **実測**：base64 画像入力が利用でき、モデルはテスト画像の内容を正しく説明しました。 ```text theme={null} input = [ { "role": "user", "content": [ {"type": "input_text", "text": "What is the dominant color of this image? One word."}, {"type": "input_image", "image_url": "data:image/png;base64,"}, ], } ] # Observed output text: "Red" ``` ```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "What is the dominant color of this image? One word."}, {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}}, ], } ] # Observed response text: "Red" ``` ## 9. 実測リファレンス：長時間タスク単発呼び出しの所要時間と使用量 K3 の思考は max 段階に固定されているため、複雑なタスクにおける単一リクエストの所要時間は通常のモデルより大幅に長くなります。単一ファイル HTML ゲーム生成タスク（参考画像付きの単一プロンプト、1 回生成、反復なし）の実測データ：単一リクエストの所要時間は 2,541 秒（約 42 分）、completion tokens は 74,994、うち思考部分が 54,486 で 73% を占め、最終的に 1 回でそのまま実行可能な 1,275 行のコードを出力し、`finish_reason` は `stop` でした。 呼び出し側の推奨事項： * クライアントのタイムアウトは分単位以上に設定し、長時間タスクではストリーミングレスポンスを優先してください。 * `max_completion_tokens` には十分な余裕を確保してください。本例では思考だけで 54,486 tokens を消費しています。 ## 10. 機能 × インターフェース対応マトリクス 以下の各セルは、いずれも 2026-07-17 に AIHubMix の本番インターフェースで実際に呼び出して検証した結果です。セル内は対応するインターフェースのパラメータ / フィールドの書き方を示します。 | 機能 | Chat Completions | Responses | Messages | | :--------------- | :-------------------------------------------- | :------------------------------------------- | :------------------------------------------------------------------------------------------ | | 思考内容の返却 | ✅ `reasoning_content` フィールド | ✅ `reasoning` 出力項目 | ✅ `thinking` コンテンツブロック | | 思考履歴の返送 | ✅ assistant メッセージをそのまま返送 | ✅ 出力項目をそのまま返送 | ✅ コンテンツブロックをそのまま返送 | | ツール呼び出しの強制 / 無効化 | ✅ `tool_choice: "required"` / `"none"` | ✅ `tool_choice: "required"` | ✅ `{"type": "any"}` / `{"type": "none"}` | | 動的ツールロード | ✅ system メッセージに `tools`（`content` なし） | ➖ 対応準備中 | ❗ 公式 Messages（Anthropic 互換）エンドポイントは非対応 | | 構造化出力 | ✅ `response_format`（json\_schema + strict） | ✅ `text.format`（json\_schema） | ❗ 公式エンドポイントは非対応、フィールドは**サイレントに無視**（200 + 自由形式テキスト）、Chat / Responses を使用 | | 自動キャッシュヒット計測 | ✅ `usage.prompt_tokens_details.cached_tokens` | ✅ `usage.input_tokens_details.cached_tokens` | ✅ `usage.cache_read_input_tokens` | | プレフィックス継続生成 | ✅ `"partial": true` | ✅ assistant プレフィル | ✅ assistant プレフィル（プロトコルネイティブ） | | 視覚入力 | ✅ `image_url`（base64） | ✅ `input_image`（base64） | ✅ `image` コンテンツブロック（base64） | | 停止シーケンス | ✅ `stop`（上限検証あり） | ➖ 対応準備中 | ❗ `stop_sequences` の上限検証は同一だが、ヒット時に `stop_reason: "stop_sequence"` / `stop_sequence` 値が返らない | ## よくある質問（FAQ） **K3 は AIHubMix でどのインターフェースに対応していますか？** Chat Completions（`/v1/chat/completions`）、Responses（`/v1/responses`）、および Claude 互換の Messages（`/v1/messages`）です。 **思考を無効化したり、思考強度を下げたりできますか？** できません。K3 の思考はデフォルトで有効になっており、`reasoning_effort` は `"max"` の 1 段階のみ対応します。 **マルチターン会話でなぜ `reasoning_content` を返送する必要があるのですか？** K3 は preserved thinking 方式で学習されており、公式は前のターンの assistant メッセージをそのまま完全に返送することを求めています。思考履歴が欠落すると出力品質が不安定になります。 **`stop` パラメータにはどのような制限がありますか？** 停止語は最大 5 個、各 32 バイト以内です。超過すると 400 エラーが返ります。 **Messages インターフェースは構造化出力に対応していますか？** ❗ 対応していません。Kimi K3 公式の Messages（Anthropic 互換）エンドポイントは構造化出力フィールドをサイレントに無視します（200 と自由形式テキストが返り、エラーは出ません）。構造化出力が必要な場合は Chat Completions の `response_format` または Responses の `text.format` を使用してください。 **K3 の単一リクエストはなぜ時間がかかるのですか？** K3 の思考は max 段階に固定されており、複雑なタスクでは思考 token の割合が高くなります（実測ケースでは completion tokens の 73%）。クライアントのタイムアウトを分単位以上に設定し、ストリーミングレスポンスの使用を推奨します。 *** モデルの料金とリアルタイムステータスは [Kimi K3 モデルページ](https://aihubmix.com/model/kimi-k3)、その他のモデルは[モデル一覧](https://aihubmix.com/models)をご覧ください。 更新日：2026-07-17