Kimi K3 実践ガイド：新パラメータとAPIサポートマトリクス

本記事では Kimi K3 の新しいパラメータと利用上の注意点を解説します。AIHubMix では、K3 は Chat Completions、Responses、Claude 互換の Messages API を通じて利用できます。関連情報：Moonshot 公式プラットフォームドキュメント。

各セクションの「検証済み」の結論とサンプルレスポンスは、2026-07-17 に AIHubMix API（Chat Completions / Responses / Messages）で実際に行った呼び出しから得たものです。

1. モデル仕様の概要

検証済み：stop の両方の制限は検証されており、いずれかを超えると 400 が返されます。Messages API も stop_sequences に同じ検証を適用します。

❗ ストップシーケンスに到達した場合、Messages API は Anthropic の仕様に従いません：テストでは、stop_reason は（"stop_sequence" ではなく）"end_turn" になり、stop_sequence は null となり、ストップワードより前の表示テキストが空になることもありました。この2つのフィールドで打ち切りを判定しているクライアントは注意してください。

# 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" のみサポートします。

複数ターンの会話では、思考履歴をそのまま返す必要があります：Moonshot の公式ドキュメントによると、K3 は思考保持（preserved thinking）で学習されているため、複数ターンの会話では直前のアシスタントメッセージを（思考内容を含めて）完全かつ未変更の状態で渡す必要があります。思考履歴が欠けると出力品質が不安定になります。セッション管理フレームワークやプロキシ層を使用している場合は、思考内容が切り詰められずに返されているか確認してください。
Chat Completions

思考内容はレスポンスの reasoning_content フィールドで返されます。複数ターンの会話では、直前のアシスタントメッセージ（reasoning_content を含む）をそのまま返してください。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_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)

# 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": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "And its population?"},
]

検証済み：レスポンスには reasoning_content が含まれます。直前のアシスタントメッセージ（reasoning_content を含む）をそのまま返すと、以降のターンも正常に応答します。
Responses

思考内容は reasoning 出力アイテムとして返されます。複数ターンの会話では、前のターンの出力アイテム（reasoning + message）を input にそのまま追加してください。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_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"

Messages

思考内容はネイティブの thinking コンテンツブロックとして返されます。複数ターンの会話では、直前のアシスタントのコンテンツブロック（thinking ブロックを含む）をそのまま返してください。

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_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 は動的ツール読み込みにも対応しており、tools フィールドを持つシステムメッセージ（Chat API 固有のメッセージ形式）を介して、会話の途中で新しいツールを注入できます。
Chat Completions

tool_choice は auto / none / required をサポートし、required はモデルにツール呼び出しを強制します。動的ツール読み込み：ツールを注入するシステムメッセージには content を含めず、注入されたツールは以降のターンで有効になります。このメッセージは毎回のリクエストに再度含める必要があります。

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?"},
]

# 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 を含まないシステムメッセージで会話の途中に注入されたツールは、正常に呼び出せます。
Responses

ツール定義はフラットな構造を使用します（name がトップレベル）。呼び出しの強制も同様に tool_choice: "required" を使用し、呼び出しは function_call 出力アイテムとして返されます。動的ツール読み込みのサポートは準備中です。現時点では、すべてのツールをトップレベルの tools パラメータで宣言してください。

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\"}"}

Messages

ツールは Anthropic 形式（input_schema）を使用します。呼び出しの強制は tool_choice: {"type": "any"}、無効化は {"type": "none"} で行います。❗ Kimi K3 の公式 Messages（Anthropic 互換）エンドポイントは動的ツール読み込みをサポートしていません：テストでは、注入用メッセージは 200 を返しますが、注入されたツールは効果がなく（モデルはそのツールを呼び出せません）。すべてのツールをトップレベルの tools パラメータで宣言してください。

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 に厳密に準拠した内容を返します。
Chat Completions

response_format は strict モードの json_schema をサポートします。

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"}

検証済み：出力は、スキーマに準拠した有効な JSON です。
Responses

構造化出力は text.format で宣言します。

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"}

Messages

❗ Kimi K3 の公式 Messages（Anthropic 互換）エンドポイントは構造化出力をサポートしていません：構造化出力のフィールドは黙って無視され、リクエストは HTTP 200 で自由形式のテキストを返します。エラーもフォールバックの通知もないため、下流の JSON パースは失敗します。構造化出力が必要な場合は、Chat Completions または Responses API を使用してください。

6. コンテキストキャッシュは自動

K3 のコンテキストキャッシュは自動で有効になり、パラメータは不要です。繰り返される長いプレフィックスがキャッシュにヒットした場合、そのヒット量が usage に報告されます（フィールド名は API によって異なります）。キャッシュの料金は モデルページに掲載されています。
Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}

検証済み：同一の長いプレフィックスを持つ 2 回目のリクエストでは、ヒットが usage.prompt_tokens_details.cached_tokens に報告されます。
Responses

# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}

Messages

# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536

7. partial プレフィックス補完

プレフィックス補完は、指定したプレフィックスから続けて生成させる機能で、コード補完や形式制御された出力に適しています。
Chat Completions

最後のアシスタントメッセージに "partial": true を渡します。

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.

検証済み：指定したプレフィックスから生成が続き、プレフィックス自体は繰り返されません。
Responses

プレフィックスを input 配列の末尾にアシスタントメッセージとして渡します。partial パラメータは不要です。

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."

Messages

同じ機能は、プロトコルネイティブのアシスタントプリフィル（assistant prefill）で実現されます。partial パラメータは不要で、最後のアシスタントメッセージとしてプレフィックスを渡します。

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 で渡します。コンテンツブロックの形式は API によって異なります。
Chat Completions

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,<BASE64>"}},
        ],
    }
]

# Observed response content: "Red"  (input: a 64x64 solid red PNG)

検証済み：base64 画像入力は動作し、モデルはテスト画像を正しく説明しました。
Responses

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,<BASE64>"},
        ],
    }
]

# Observed output text: "Red"

Messages

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": "<BASE64>"}},
        ],
    }
]

# Observed response text: "Red"

9. 検証済みリファレンス：長い単一呼び出しタスクのレイテンシーと使用量

K3 の思考は最大レベルに固定されているため、複雑なタスクの単一リクエストは一般的なモデルよりも大幅に時間がかかります。単一ファイルの HTML ゲーム生成タスク（参照画像付きのプロンプト1件、反復なしで一度に生成）の実測データ：単一リクエストは 2,541 秒（約 42 分）かかり、完了トークンは 74,994 件、そのうち 54,486 件（73%）が思考トークンでした。最終出力は 1,275 行の直接実行可能なコードで、finish_reason は stop でした。

クライアント側の推奨事項：

• クライアントのタイムアウトは数分以上に設定し、長いタスクにはストリーミングを優先してください。
• max_completion_tokens には十分な余裕を持たせてください。今回のケースでは、思考だけで 54,486 トークンを消費しました。

10. 機能 × API サポートマトリクス

以下の表の各セルは、2026-07-17 に AIHubMix の本番 API へ実際に呼び出して検証したものです。各セルには、対応する API のパラメータ / フィールドの構文を示しています。

FAQ

K3 は AIHubMix でどの API をサポートしていますか？
Chat Completions（/v1/chat/completions）、Responses（/v1/responses）、Claude 互換の Messages API（/v1/messages）です。

思考を無効化したり弱めたりできますか？
いいえ。K3 の思考はデフォルトでオンで、reasoning_effort は単一の "max" レベルのみサポートします。

多輪会話でreasoning_contentを渡す必要があるのはなぜですか？
K3は保持型思考（preserved thinking）で学習されており、Moonshotは直前のassistantメッセージを完全かつ改変せずに渡すことを求めています。思考履歴が欠けると、出力品質が不安定になります。

stopパラメータの上限は？
stopシーケンスは最大5個まで、それぞれ32バイト以下です。いずれかの上限を超えると400エラーが返されます。

Messages APIは構造化出力に対応していますか？
❗ いいえ。Kimi K3の公式Messages（Anthropic互換）エンドポイントは、構造化出力のフィールドを黙って無視します（エラーなしで200を返し、自由形式のテキストを出力します）。構造化出力が必要な場合は、Chat Completionsではresponse_formatを、Responsesではtext.formatを使用してください。

単一のK3リクエストに時間がかかるのはなぜですか？
K3の思考は最大レベルに固定されており、複雑なタスクでは思考トークンが出力トークンの大きな割合を占めます（測定したケースでは出力トークンの73%）。クライアントのタイムアウトは数分以上に設定し、ストリーミングを使用してください。

料金とリアルタイムのステータスについてはKimi K3モデルページをご覧ください。その他のモデルはモデルギャラリーでご確認いただけます。

最終更新日：2026-07-17