Kimi API 接続チュートリアル：Base URL、モデル名、初回呼び出し(2026)

Kimi API は OpenAI インターフェースと互換性があり、移行時は通常 3 か所だけを変更します。Base URL、API キー、モデル名です。ただし 2026 年のインターフェースには見落としやすい点がいくつかあります。旧モデルは提供終了しており、max_tokens は非推奨になり、K3 は既定で最高の推論強度を使い、ストリーミングの使用量は最後のブロックでしか返りません。

本記事ではゼロから接続を一通り行います。まずサイトとプロトコルを確認し、次にモデルを選び、curl と Python の初回呼び出しを完了し、最後に移行チェックリストとエラー対応表を示します。モデルと価格はサイト内のモデル価格を基準にしてください。

注記：Moonshot、Kimi はその権利者の商標です。本記事は技術的な接続方法の説明のみを目的としています。モデル一覧、コンテキスト長、パラメータの規則は変更される場合があるため、公式ドキュメントの現行バージョンを基準にしてください。

一、接続前に確認する 3 点

サイト：中国サイトは platform.kimi.com、国際サイトは platform.kimi.ai です。両サイトのアカウント、残高、キーは完全に独立しています。
プロトコル：ほとんどのプロジェクトは OpenAI 互換の Chat Completions を使います。Anthropic SDK を使っているプロジェクトは Messages 互換の入口も利用できます。
モデル：アカウントで利用できるモデルを確認してからコードに書きます。数か月前のチュートリアルをそのまま写さないでください。

中国サイトのリクエストドメインは https://api.moonshot.cn、国際サイトは https://api.moonshot.ai です。ドメインとキーは必ず対応させる必要があり、これが 401 の最もよくある原因の 1 つです。

二、Base URL とインターフェースのパス

プロトコル	Base URL	インターフェースのパス
OpenAI Chat Completions	`https://api.moonshot.cn/v1`	`/chat/completions`
OpenAI Responses	`https://api.moonshot.cn/v1`	`/responses`
Anthropic Messages	`https://api.moonshot.cn/anthropic`	`/v1/messages`
モデル一覧	`https://api.moonshot.cn/v1`	`/models`
残高照会	`https://api.moonshot.cn/v1`	`/users/me/balance`

国際サイトではドメインを api.moonshot.ai に置き換え、パスは変わりません。OpenAI SDK の base_url は /v1 までを指定し、SDK が /chat/completions を自分で結合します。curl の場合は完全なパスを書きます。両者を混ぜると /v1 が 1 層増えたり抜けたりし、404 として現れます。

Anthropic 互換入口の Base URL は /v1 を含まない点が、OpenAI 入口と異なります。Claude Code や他の Anthropic SDK で接続する場合は、公式の例に従って https://api.moonshot.cn/anthropic を指定してください。

三、モデル名の選び方

モデル名	コンテキスト	向くタスク	注意
`kimi-k3`	1M	複雑な推論、ソフトウェアエンジニアリング、知識作業、超長文書	既定の `reasoning_effort` は `max`
`kimi-k2.7-code`	256K	コード生成、リポジトリの質問応答、Agent	長いコンテキストでの指示追従がより良い
`kimi-k2.7-code-highspeed`	256K	低遅延の補完、対話的なコーディング	標準版と同じモデルで、速度がより速い
`kimi-k2.6`	256K	汎用対話、抽出、視覚とテキストの入力	思考モードと非思考モードに対応

旧モデルは提供終了しています。moonshot-v1 の全系列と kimi-k2.5 は 2026 年 8 月 31 日にサポートを終了し、kimi-k2 系列は 2026 年 5 月 25 日に終了、kimi-latest はさらに早く終了しました。これらの名前を使っているプロジェクトは、アップグレード時に kimi-k3 または K2 系列へ直接移行し、古いドキュメントを探し続けないでください。

汎用タスクでは、既定で K3 を使う必要はありません。K3 は能力が高い一方、既定の推論強度が高く、遅延と出力 Token が増えます。単純な分類や固定形式の抽出には kimi-k2.6 のほうが適することが多いです。コードタスクでは K2.7 Code 系列を検討してください。

中国サイトと国際サイトでは、利用規約、本人確認の方法、請求の通貨も異なります。同じ業務でも、対象とする利用者と支払いの経路によって適切なサイトが変わります。開発環境と本番環境でサイトを分ける場合は、キーだけでなく、利用量の集計と請求の単位も分けて管理してください。モデル名は設定ファイルや環境変数にまとめ、コードへ直接埋め込まないでください。K3 と K2 系では推論強度と最大出力の既定値が異なるため、環境ごとに設定を分けて管理すると、移行時の確認作業を減らせます。

四、最初の呼び出し：curl

export MOONSHOT_API_KEY="あなたのキー"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "「接続成功」とだけ返してください"}
    ],
    "max_completion_tokens": 64
  }'

200 が返り、内容が期待どおりなら、キー、サイト、モデル名、パスの 4 つが通っています。401 が返る場合はまずサイトとキーの対応を、404 の場合はモデル名と /v1 を、400 の場合はエラーメッセージにコンテキストや出力上限への言及がないかを確認してください。

五、Python SDK とストリーミング出力

OpenAI SDK の 1.0 以上をインストールし、base_url とキーを変更するだけです。

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "API ゲートウェイが向くチームを 3 点で説明してください"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\n使用量：", chunk.usage)

ストリーミングのレスポンスは SSE で、各行は data: で始まり、最後は data: [DONE] で終わります。include_usage を有効にすると、終了前に choices が空で usage だけを持つブロックが追加で返ります。接続が途中で切れるとこのブロックを受け取れない場合があるため、使用量の統計をクライアントだけに依存させないでください。

六、max_completion_tokens と推論強度

max_tokens は非推奨になり、新しいコードでは max_completion_tokens を統一して使います。これは期待する出力長を表し、入力と出力の合計長ではありません。K3 の既定値は 131072 で、最大 1048576 まで設定できます。入力とこの値の合計がコンテキストウィンドウを超えると、リクエストは invalid_request_error を返します。

実用的な規則は 2 つあります。

テストや固定形式のタスクでは、値を小さく設定します。たとえば 256 から 1024 です。モデルが長文を出力するのを避けられます。
上限に達すると finish_reason は length になり、正常終了は stop です。length を見てもすぐに再試行せず、出力が本当に長く必要か、プロンプトが開放的すぎるかを先に判断してください。

K3 にはトップレベルのパラメータ reasoning_effort があり、low、high、max から選べ、既定は max です。単純なタスクを low にすると、遅延と Token 消費を抑えられます。複雑な推論では上げてください。OpenAI SDK を使う場合、そのバージョンにこのパラメータが組み込まれていなければ extra_body で渡します。K3 の思考内容は reasoning_content にあり、マルチターンやツール呼び出しではそのまま返送する必要があります。

利用量の上限や予算の通知も合わせて設定し、想定外の消費を早期に発見できる体制を整えてください。本番環境では、モデル名、推論強度、最大出力の組み合わせを環境変数で管理し、変更履歴を残すと、障害時の切り分けが容易になります。

七、OpenAI または旧版 Moonshot からの移行

コードと設定にある旧モデル名をすべて洗い出し、置き換え表を作る。
base_url を変更する。中国サイトは https://api.moonshot.cn/v1、国際サイトは https://api.moonshot.ai/v1。
対応するサイトのキーに変更する。サイトをまたいで再利用しない。
モデル名を置き換える。kimi-k3 または K2 系列の現行モデルを優先する。
max_tokens を max_completion_tokens に変更する。
K2.x の thinking 設定を K3 の reasoning_effort に変更し、同時に送らない。
ストリーミングのリクエストに stream_options={"include_usage": True} を追加する。
同じ実タスクの組で回帰テストを行い、品質、遅延、finish_reason、使用量を記録する。
旧設定を 1 リリース分残し、問題がないことを確認してから削除する。

移行は一度に全量切り替えないでください。まずテスト環境、次に低リスクの業務、最後に中核の経路へと進み、各段階でロールバック用のスイッチを残します。

八、よくあるエラー対応表

ステータスコード	エラーの種類	よくある原因	対処
400	`invalid_request_error`	パラメータの誤り、コンテキスト超過、出力上限の逸脱	リクエストを修正
400	`content_filter`	入力または出力がコンテンツ安全基準に触れた	プロンプトを調整
401	`invalid_authentication_error`	キーが無効、サイトの不一致	キーを変更するかドメインを修正
404	`resource_not_found_error`	モデル名またはパスの誤り	モデル一覧を確認
429	`rate_limit_reached_error`	同時実行、RPM、TPM、TPD の超過	速度を下げるかプランを上げる
429	`exceeded_current_quota_error`	未払いまたは残高不足	チャージ
504	`Gateway Time-out`	非ストリーミングの長いリクエストの待ちすぎ	ストリーミングに変更

非ストリーミングのリクエストは、サーバー側の待ち時間が 900 秒を超えると 504 を返す場合があります。長文生成、長い文書の分析、コード Agent はできるだけストリーミングを使い、クライアントが継続的にデータを受け取れるようにし、「タイムアウトしてから再試行する」無駄を減らしてください。

よくある質問

Base URL はどこまで指定しますか？

OpenAI SDK は https://api.moonshot.cn/v1 を指定し、/chat/completions は付けません。curl は完全な https://api.moonshot.cn/v1/chat/completions を書きます。Anthropic SDK は https://api.moonshot.cn/anthropic を指定します。

max_tokens が効かないのはなぜですか？

このパラメータは非推奨で、一部のモデルでは無視されるかエラーになります。max_completion_tokens に変更し、これが出力の上限であり入力込みの上限ではないことに注意してください。

K3 の応答が思ったより遅いのはなぜですか？

K3 の既定の reasoning_effort は max で、深い推論を行います。単純なタスクでは low または high に下げ、出力長を制限すると、通常は遅延が明確に改善します。

ストリーミング終了後に usage がないのはなぜですか？

stream_options={"include_usage": True} を明示的に設定する必要があります。設定しても、接続が中断すると最後のブロックを受け取れない場合があるため、本番環境ではサーバー側でも別途記録してください。

OpenAI からの移行で他に変更することはありますか？

多くのコードは Base URL、キー、モデル名だけで済みます。さらに max_tokens、ストリーミングの使用量、エラーの種類のマッピング、再試行方針、特に 429 の分類処理を確認してください。

次のステップ

まず ZSQH AI Gateway でテストキーを作成し、kimi-k3 と kimi-k2.6 でそれぞれ実タスクを 1 件実行してください。経路を確認してから本番に接続します。利用可能なモデルと課金はモデル価格を基準にしてください。