Kimi K3 ハンズオンガイド：新しいパラメータとAPIサポートマトリックス

この記事では、Kimi K3の新しいパラメータと使用上の注意について説明します。AIHubMixでは、K3はチャット完了、レスポンス、およびClaude互換メッセージAPIを通じて利用可能です。詳細については、Moonshot公式プラットフォームドキュメントを参照してください。

各セクションの「検証済み」結論とサンプルレスポンスは、2026年7月17日にAIHubMix API（チャット完了 / レスポンス / メッセージ）で行われた実際の呼び出しから得られたものです。

1. モデル仕様の概要

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

❗ ストップシーケンスに達した場合、メッセージAPIはAnthropicのセマンティクスに従いません：テストでは、stop_reasonは"end_turn"（"stop_sequence"ではなく）、stop_sequenceはnullであり、ストップワードの前の可視テキストは空である可能性があります。これらの2つのフィールドに依存して切り捨てを検出するクライアントは注意が必要です。

# 6エントリでストップ / 33バイトのエントリ -> HTTP 400
"無効なリクエスト：ストップ配列が長すぎます。最大長5の配列が期待されましたが、長さ6の配列が得られました"
"無効なリクエスト：ストップシーケンスは32を超えてはならず、33が得られました"

2. 思考モード：reasoning_effortはmaxのみをサポート

K3の思考はデフォルトでオンであり、reasoning_effortは単一のレベル："max"のみをサポートします。

マルチターンの会話では、思考履歴をそのまま返す必要があります：Moonshotの公式ドキュメントによると、K3は思考を保持して訓練されているため、マルチターンの会話では前のアシスタントメッセージを完全かつ未修正のまま（思考内容を含む）返す必要があります。思考履歴が欠けると出力品質が不安定になります。セッション管理フレームワークやプロキシレイヤーを使用している場合は、思考内容がトリミングされずに返されることを確認してください。
チャット完了

思考内容はレスポンスの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": "カタツムリは10メートルの井戸の底にいます。毎日3メートル登りますが、毎晩2メートル滑り戻ります。頂上に達するまでに何日かかりますか？"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

# マルチターン：前のアシスタントメッセージをそのまま返す
messages = [
    {"role": "user", "content": "フランスの首都はどこですか？"},
    {"role": "assistant", "content": "パリです。", "reasoning_content": "<前のレスポンスからのreasoning_content>"},
    {"role": "user", "content": "その人口は？"},
]

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

思考内容は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="一言で答えてください：フランスの首都は？",
)

# 観察されたresponse.outputアイテムのタイプ: ["reasoning", "message"]; テキスト: "パリ"
# マルチターン：input = [最初のユーザーメッセージ] + response.output + [次のユーザーメッセージ]
# 観察された二回目のターンの答え： "ベルリン"

メッセージ

思考内容はネイティブの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": "一言で答えてください：フランスの首都は？"}
    ],
)

# 観察されたresponse.contentブロックのタイプ: ["thinking", "text"]; テキスト: "パリ"
# マルチターン：response.contentをそのままアシスタントメッセージとして返す

3. サンプリングパラメータは固定されています

K3のサンプリングパラメータはモデルプロバイダーによって固定されています：temperature 1.0、top_p 0.95、n 1、presence_penalty / frequency_penalty 0。公式の推奨は、リクエストからこれらのパラメータを省略することです。

注意：固定されたサンプリング値は公式仕様の一部であり、レスポンス信号から検証することはできません；公式の推奨に従い、これらのパラメータを省略してください。

4. ツール呼び出しと動的ツール読み込み

toolsは最大128のツールをサポートします；tool_choiceはツール呼び出しを強制または無効にすることをサポートします。K3は動的ツール読み込みもサポートしており、システムメッセージのtoolsフィールドを介して会話中に新しいツールを注入できます（チャットAPI特有のメッセージ形状）。
チャット完了

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

messages = [
    {"role": "system", "content": "あなたは役に立つアシスタントです。"},
    {"role": "user", "content": "こんにちは。"},
    {"role": "assistant", "content": "こんにちは、どのようにお手伝いできますか？"},
    # 会話中に新しいツールを注入：ツールフィールドのみ、コンテンツなし
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "現在の時刻を取得",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "今何時ですか？"},
]

# tool_choice="required"でプロンプト"こんにちは" -> モデルはツールを呼び出すことを強制される
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

検証済み：tool_choice: "required"は無関係なプロンプトでもツール呼び出しを強制します；"none"はツール呼び出しを抑制します；contentなしでシステムメッセージを介して会話中に注入されたツールは通常通りに呼び出すことができます。
レスポンス

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

response = client.responses.create(
    model="kimi-k3",
    input="こんにちは",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "都市の天気を取得",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# 観察された出力には次が含まれます: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

メッセージ

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

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "都市の天気を取得",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "こんにちは"}],
)

# 観察された：stop_reason "tool_use"; contentにはget_weatherを呼び出すtool_useブロックが含まれています

5. 構造化出力

構造化出力により、モデルは与えられたJSONスキーマに厳密に準拠したコンテンツを返します。
チャット完了

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

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "パリはフランスの首都です。都市名を抽出してください。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# 観察されたレスポンスコンテンツ: {"city":"パリ"}

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

構造化出力はtext.formatを介して宣言されます。

response = client.responses.create(
    model="kimi-k3",
    input="パリはフランスの首都です。都市名を抽出してください。",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# 観察された出力テキスト: {"city":"パリ"}

メッセージ

❗ Kimi K3の公式メッセージ（Anthropic互換）エンドポイントは構造化出力をサポートしていません：構造化出力フィールドは静かに無視され、リクエストはHTTP 200を返し、自由形式のテキストが返され、エラーやフォールバック通知はありません。構造化出力が必要な場合は、チャット完了またはレスポンスAPIを使用してください。

6. コンテキストキャッシングは自動です

K3のコンテキストキャッシングは自動的に有効になり、パラメータは必要ありません。繰り返しの長いプレフィックスがキャッシュにヒットすると、ヒット量が使用量に報告されます（フィールド名はAPIによって異なります）。キャッシュ料金はモデルページにあります。
チャット完了

# 同一の長いプレフィックスでの2回目の呼び出しの使用量
"prompt_tokens_details": {"cached_tokens": 1536}

検証済み：同一の長いプレフィックスでの2回目のリクエストはusage.prompt_tokens_details.cached_tokensにヒットを報告します。
レスポンス

# 同一の長い指示での2回目のレスポンス呼び出しの使用量
"input_tokens_details": {"cached_tokens": 1536}

メッセージ

# 同一の長いシステムプロンプトでの2回目のメッセージ呼び出しの使用量
"cache_read_input_tokens": 1536

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

プレフィックス完了により、モデルは指定されたプレフィックスから生成を続けることができ、コード完了やフォーマット制御された出力に適しています。
チャット完了

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

messages = [
    {"role": "user", "content": "海についての俳句を書いてください。"},
    {"role": "assistant", "content": "波は泡に折りたたまれ、", "partial": True},
]

# プレフィックス: "波は泡に折りたたまれ、"  ->  モデルによって返される続き
# 塩が空気に漂い—
# 月が潮を引き寄せる。

検証済み：生成は与えられたプレフィックスから続き、繰り返すことはありません。
レスポンス

プレフィックスをinput配列の最後のアシスタントメッセージとして渡します；partialパラメータは必要ありません。

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "海についての俳句を書いてください。"},
        {"role": "assistant", "content": "波は泡に折りたたまれ、"},
    ],
)

# 観察された続き: "塩が空気に漂い— / 月が潮を引き寄せる。"

メッセージ

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

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "海についての俳句を書いてください。"},
        {"role": "assistant", "content": "波は泡に折りたたまれ、"},
    ],
)

# 観察された続き: "塩の風がカモメの鳴き声を運ぶ— / 潮が引く..."

8. ビジョン入力

画像はbase64として渡されます；コンテンツブロックの形式はAPIによって異なります。
チャット完了

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "この画像の主な色は何ですか？一言で。"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# 観察されたレスポンスコンテンツ: "赤"  (入力: 64x64の単色赤PNG)

検証済み：base64画像入力は機能し、モデルはテスト画像を正しく説明します。
レスポンス

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "この画像の主な色は何ですか？一言で。"},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# 観察された出力テキスト: "赤"

メッセージ

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "この画像の主な色は何ですか？一言で。"},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# 観察されたレスポンステキスト: "赤"

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年7月17日にAIHubMixの本番APIへの実際の呼び出しを通じて検証されました；各セルは対応するAPIのパラメータ / フィールド構文を示しています。

FAQ

K3はAIHubMixでどのAPIをサポートしていますか？
チャット完了（/v1/chat/completions）、レスポンス（/v1/responses）、およびClaude互換メッセージAPI（/v1/messages）です。

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

なぜreasoning_contentをマルチターン会話で返す必要があるのですか？
K3は思考を保持して訓練されているため、Moonshotは前のアシスタントメッセージを完全かつ未修正のまま返すことを要求します。思考履歴が欠けると出力品質が不安定になります。

stopパラメータの制限は何ですか？
最大5つのストップシーケンス、各シーケンスは32バイトを超えてはならず、いずれかの制限を超えると400エラーが返されます。

メッセージAPIは構造化出力をサポートしていますか？
❗ いいえ。Kimi K3の公式メッセージ（Anthropic互換）エンドポイントは構造化出力フィールドを静かに無視します（200を返し、自由形式のテキストとエラーなし）。構造化出力が必要な場合は、response_formatをチャット完了で、またはtext.formatをレスポンスで使用してください。

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

料金とリアルタイムのステータスについては、Kimi K3モデルページを参照してください；他のモデルについてはモデルギャラリーをご覧ください。

最終更新日：2026年7月17日