hiapi API で kimi-k3 を使う方法：curl、Python、実行可能なリクエスト例

構築するもの

kimi-k3 は推論能力を備えた対話モデルで、標準の OpenAI 互換 /v1/chat/completions エンドポイントを通じて hiapi 上で利用できます——非同期タスクのポーリングも、画像のアップロードも不要です。本ガイドでは、ゼロから curl と Python で実行可能な呼び出しを完成させ、その後、本番環境でつまずきやすい 2 つのポイント、推論トークンが max_tokens の予算を圧迫すること、そしてストリーミング出力について解説します。

前提条件：hiapi API キー。まだお持ちでない場合はコンソールから取得してください——以下の各リクエストは Authorization: Bearer sk-<your-key> で認証します。

最小限の実行可能な例

kimi-k3 はテキストモデルであるため、hiapi が画像/動画モデルに使用する /v1/tasks タスクキューを経由しません——直接の同期対話補完呼び出しです。

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
    ],
    "max_tokens": 300
  }'

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [
            {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
        ],
        "max_tokens": 300,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

成功時のレスポンスは次のようになります：

{
  "id": "chatcmpl-fb762e7481bd4442abb1d8ed3892b4f5",
  "model": "FW-Kimi-K3",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need answer user: \"Reply with exactly the word OK.\" ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 95,
    "completion_tokens": 52,
    "total_tokens": 147,
    "completion_tokens_details": {"reasoning_tokens": 38}
  }
}

最終的な回答は choices[0].message.content にあります。リクエスト内のモデル ID は素の ID kimi-k3 です——hiapi は内部でマッピングを行います（レスポンスボディの model フィールドには基盤となるラベル、例えば FW-Kimi-K3 がエコーバックされますが、これは想定された動作です）。

唯一の落とし穴：推論トークンと max_tokens

kimi-k3 は推論モデルであり、最終的な content を生成する前に思考の連鎖を message.reasoning_content に書き出しますが、両者は同一の max_tokens 予算を共有します。max_tokens を低く設定しすぎると、モデルは予算全体を推論に費やしてしまい、finish_reason: "length" を返しつつ content フィールドが空になることがあります：

{
  "choices": [{
    "message": {"content": "", "reasoning_content": "The user is asking me to say \"OK\""},
    "finish_reason": "length"
  }]
}

これはバグではありません——単に推論プロセスが最終回答に到達する前に空間を使い果たしただけです。対処法は 2 つあります：

• 余裕を持たせる。簡潔な事実回答であれば、200〜300 の max_tokens で通常は推論と回答をカバーできます。より長い生成内容の場合は、予算をそれに応じて増やしてください。
• finish_reason を確認する。"length" が返り、かつ content が空の場合は、max_tokens を増やして再試行してください。空の文字列を最終回答として扱わないでください。

ストリーミング出力

"stream": true を設定すると、完全なレスポンスを待たずにサーバー送信イベント（SSE）を取得できます。データチャンクはまず増分の delta.reasoning_content を運び、モデルが最終回答を書き始めると delta.content を運びます：

import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Count to 3."}],
        "max_tokens": 200,
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data: ") and line != b"data: [DONE]":
            print(line.decode("utf-8"))

チャット UI を構築する場合は、delta.content のみをストリーミング表示してください——ほとんどのアプリでは delta.reasoning_content は「思考中」トグルの背後に隠すか折りたたんで表示し、インラインで見せることはありません。

本番環境での注意点

• エラー処理。無効または欠落したキーは HTTP 401 と構造化されたレスポンスボディを返します：

  {"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}
  

  request_id を記録してください——チケットを起票する際、サポートチームが必要とします。
• リトライ。対話補完は同期であるため、ポーリングすべきタスク ID も、登録すべきコールバックもありません（そのパターンは hiapi の非同期画像/動画モデル向けであり、テキストには適用されません）。タイムアウトや 5xx に遭遇した場合は、リクエストをそのまま再試行してください。サーバー側でキューに積まれるタスクはないため、通常の冪等な GET 的なリトライとして扱えます。
• 課金。kimi-k3 はプラットフォーム上の他のテキストモデルと同様にトークン単位で課金されます——スケール時のコストを見積もる前に、料金ページで現在のレートを確認してください。推論トークンは補完トークンとしてカウントされるためです。

よくある質問

kimi-k3 はストリーミング出力をサポートしていますか？ はい——"stream": true を渡し、上記のように text/event-stream レスポンスを読み取ってください。

レスポンスの content が空なのはなぜですか？ finish_reason はほぼ確実に "length" です——モデルが最終回答に到達する前に、max_tokens 予算の全体を reasoning_content に費やしてしまっています。max_tokens を増やして再試行してください。

kimi-k3 は hiapi の /v1/tasks エンドポイントを使用する必要がありますか？ いいえ。/v1/tasks は非同期の画像、動画、音楽生成モデル向けです。kimi-k3 は同期テキストモデルであり、標準の /v1/chat/completions エンドポイントを通じて提供されます。

ネイティブの requests の代わりに OpenAI Python SDK を使用できますか？ はい——SDK の base_url を https://api.hiapi.ai/v1 に設定し、hiapi キーを API キーとして渡してください。リクエスト/レスポンスの構造は OpenAI と互換です。

リクエストにはどのモデル ID を渡すべきですか？ 素の ID kimi-k3 です。レスポンスボディの model フィールドに FW-Kimi-K3 のような内部ラベルがエコーバックされますが、これは想定された動作であり、課金や挙動には影響しません。