チュートリアル
HiAPI API で kimi-k3.1-pro-highspeed を呼び出す方法:curl と Python のサンプル
このページの内容
kimi-k3.1-pro-highspeed とは何か、そしてどんなときに選ぶべきか
kimi-k3.1-pro-highspeed は HiAPI が提供するチャット形式モデルの一つです。呼び出し方はプラットフォーム上の他のどのチャットモデルとも同じです。メッセージの配列を送信し、補完結果を1つ受け取ります。名前に含まれる「high-speed」は、このモデルが想定するトレードオフを示しています。つまり、生の推論の深さよりもレイテンシを重視し、最も遅く最も詳細な回答ではなく、予測可能な応答時間を求める場合に選ぶべきものです。
したがって、次のような具体的なワークロードに適しています。
- インタラクティブなインターフェース——チャット UI、自動補完、インラインアシスタントなど、ユーザーが応答を待っている場面。
- 高スループットのパイプライン——分類、抽出、要約、書き換えなどのタスクで、スループットが必要であり、1リクエストあたりの結果が短いもの。
- マルチホップのエージェントループ——多段階のフローで各呼び出しは小さく、総レイテンシが単一の呼び出しではなく往復回数に主に依存するもの。
大量のコンテキスト上で長時間かつ熟考を要する推論が必要なタスクや、生成する内容が「速い複数回のパスよりも遅くても高品質な1回のパスが勝る」場合は、明らかな選択肢ではありません。そのような場合は、まず出力品質をベンチマークしてから速度を最適化してください。速いが誤った回答は、遅くても正しい回答よりもコストが高くつきます。
このモデルは HiAPI の統一インターフェース経由で提供されるため、後で他のモデルに切り替えたり、他のモデルから戻したりするのは、コードを書き換えるのではなくリクエストペイロードを変更するだけです。モデル名を呼び出し箇所にハードコードせず設定に置けば、リクエスト構築コードを変更せずに他のモデルと A/B テストできます。
「チャット形式」が実際に意味すること
各リクエストは次の構造です。モデル識別子、順序付きのメッセージリスト(各メッセージは role と content を持つ)、そして stream、temperature、max_tokens などの任意パラメータです。システムプロンプトは role: "system" のメッセージとして渡します。これがメンタルモデルのすべてです。本ガイドの残りは、この形を巡る配管作業にすぎません。
前提条件:認証情報、エンドポイント、モデル名
コードを書く前に、次の4項目が揃っていることを確認してください。初回呼び出しの失敗のほとんどは、リクエストボディのバグではなく、このチェックリストの欠落に起因します。
1. API キー
HiAPI アカウントのダッシュボードでキーを生成します。機密情報として扱ってください。環境変数から読み込み、リポジトリにコミットせず、ログや共有ノートブックに現れたらすぐにローテーションします。
export HIAPI_API_KEY="your-key-here"
2. ベース URL
エンドポイントは HiAPI のベース URL にチャット補完のパスを加えたものです。ベース URL を設定に置いておけば、変更時にコードを修正する必要がありません。
export HIAPI_BASE_URL="https://api.hiapi.ai/v1"
3. モデル識別子
送信するモデル文字列は正確に次のとおりです。
kimi-k3.1-pro-highspeed
1文字ずつコピーしてください。モデル名はリテラルに一致します。余分な空白、大文字小文字の違い、綴り間違いはいずれも、他のフィールドの検証エラーではなくモデル未検出系のエラーを返します。そのため、誤った場所を調査することになりかねません。
4. HTTPS を送信できるクライアント
以下の curl サンプルには、curl がインストールされたシェルがあれば十分です。これは macOS やほとんどの Linux イメージに標準で入っています。Python のパートには Python 3.8+ と requests パッケージが必要です。
pip install requests
SDK スタイルのクライアントを好む場合も、同じエンドポイント、キー、モデル名がそのまま使えます。重要なのはワイヤー上の形式であり、本ガイドは何かが抽象化の背後に隠れないよう、生の HTTP を使い続けます。
正常性チェック
完全なリクエストを組み立てる前に、キーとベース URL が解決できるかを確認する簡単なチェックを実行してください。意図的に最小化し、1語だけのプロンプトを含む呼び出しです。これが成功すれば、以降の失敗は認証情報ではなくリクエストペイロードに関するものです。
動作する curl リクエスト
以下は完全で、そのままコピー&ペーストできるリクエストです。システムメッセージで振る舞いを設定し、ユーザーメッセージで実際の要求を行い、テスト時に応答を短く保つため max_tokens を固定しています。
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [
{"role": "system", "content": "あなたは簡潔な技術アシスタントです。2文以内で答えてください。"},
{"role": "user", "content": "冪等キーとは何か、そしてなぜリトライにとって重要なのかを説明してください。"}
],
"temperature": 0.3,
"max_tokens": 200,
"stream": false
}'
フィールドごとの説明
model——前節のモデル識別子。必須です。messages——順序付きの配列です。systemはペルソナと制約を設定し、userはタスクを担います。順序は重要で、後ろのメッセージほど振る舞いの誘導において優先度が高くなります。マルチターンのフローでは、すべてを1つの巨大なユーザーメッセージに連結するのではなく、同じ配列にuserとassistantのターンを追加し続けてください。temperature——サンプリングのランダム性です。低い値はより再現性の高い出力を与え、これが抽出や分類に必要なものです。変化を本当に望む場合にのみ高くしてください。max_tokens——生成応答の上限です。明示的に設定すると、暴走した生成から守られ、レイテンシが予測可能になります。stream——ここではfalseで、生成完了時に1つの JSON オブジェクトを受け取ることを意味します。後の節でtrueを扱います。
何が返るか
応答は choices 配列を含む JSON オブジェクトです。必要なテキストは choices[0].message.content にあります。また token 消費を表す usage ブロックもあります。token 課金の場合、これが1リクエストあたりのコストを示す唯一のシグナルなので記録してください。
デバッグ中なら、出力をフォーマッタに通して読みやすくします。
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | python -m json.tool
リクエストボディを payload.json に入れて -d @payload.json を使えば、ペイロードが数フィールドを超えたあたりからシェルのクォート問題を避けられます。
リクエストを Python に移植する
ここでの目的はデモスクリプトではなく、インポート可能な関数です。リクエストペイロードは curl 版と完全に一致させてください。同じフィールド、同じ名前、同じモデル文字列です。そうすればツールを切り替えても挙動は変わりません。
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"
def chat(
user_message: str,
system_message: str = "あなたは簡潔な技術アシスタントです。",
temperature: float = 0.3,
max_tokens: int = 400,
timeout: float = 30.0,
) -> str:
payload = {
"model": MODEL,
"messages": [
{"role": "system", "content": system_message},
{"role": "user", "content": user_message},
],
"temperature": temperature,
"max_tokens": max_tokens,
"stream": False,
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
data = response.json()
return data["choices"][0]["message"]["content"]
そして:
print(chat("PUT と PATCH の違いを一文で要約してください。"))
なぜこのように書くのか
- 手書き JSON ではなく
json=payloadを使う——requests が正しくシリアライズし、コンテンツタイプを設定するため、クォートに関するバグの一類を丸ごと排除できます。 - 明示的な
timeout——これがないと、停止した接続がワーカープロセスを無期限にハングさせる可能性があります。短い補完なら30秒は余裕があり、対話経路なら短くしてください。 - 早めの
raise_for_status()——HTTP 層の失敗を、3行後ろでchoicesに対してKeyErrorを投げるのではなく、呼び出し境界で例外として表面化させたいからです。 - モジュールレベルの設定——キー、ベース URL、モデルを1箇所に集約します。後で他のモデルを A/B テストするときは定数1つを変えるだけです。
マルチターン会話
実際の会話では、固定の2メッセージを組み立てるのではなく、メッセージリストを引数として受け取ります。
def chat_with_history(messages: list, **kwargs) -> dict:
payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
r = requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=30.0,
)
r.raise_for_status()
body = r.json()
return {
"content": body["choices"][0]["message"]["content"],
"usage": body.get("usage"),
}
アシスタントの返信を role: "assistant" として messages に追加して会話を続け、履歴が長くなったら古いターンを削除してください。コンテキストは課金対象なので、無制限の会話履歴は各リクエストのコストを静かに押し上げます。
ストリーミング応答を有効にして消費する
"stream": true を設定すると、サーバーは最後に1つのオブジェクトを送るのではなく、サーバー送信イベントとして応答を逐次的に送信します。ユーザーが視聴しているものには、クライアント側の追加作業だけの価値があります。総生成時間が同じでも、最初の token までの時間は大幅に短縮されます。
curl の観点
curl -N -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [{"role": "user", "content": "リトライについての俳句を書いてください。"}],
"stream": true
}'
-N は curl の出力バッファリングを無効にし、イベントが送信され次第到着するのを実際に確認できるようにします。受け取るのは一連の行で、各行は data: で始まり JSON の断片を運びます。最後のイベントは data: [DONE] です。このセンチネルは解析可能な JSON ではなく、ストリーム終了マーカーとして扱ってください。
Python クライアント
import json
import requests
def stream_chat(user_message: str, timeout: float = 60.0) -> str:
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": user_message}],
"stream": True,
}
pieces = []
with requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
stream=True,
timeout=timeout,
) as r:
r.raise_for_status()
for raw in r.iter_lines(decode_unicode=True):
if not raw or not raw.startswith("data: "):
continue
data = raw[len("data: "):].strip()
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
pieces.append(text)
print(text, end="", flush=True)
return "".join(pieces)
ストリーミングを正しく保つルール
- 置換ではなく連結。各チャンクは新しい断片だけを運びます。リストに蓄積し、最後に一度だけ join してください。ループ内で文字列に追加すると、長い出力では二次の計算量になります。
- 欠落したコンテンツに備える。メタデータだけを運ぶチャンクもあるため、
deltaにcontentキーがない場合があります。.get()を使い、空値はスキップしてください。 - 不完全な行を処理する。フレーム境界が行を分割する場合があります。
iter_linesはこれを処理しますが、生のバイトストリームを自分で解析する場合は改行が見えるまでバッファリングしてください。 - ストリームに適したタイムアウトを設定する。ストリーム全体は短いリクエストのタイムアウトを合法的に超える場合があります。タイムアウトを完全に無効にするのではなく、より長い読み取りタイムアウトやチャンクごとの読み取り期限を使ってください。
- 非ストリーミング経路を残す。バックグラウンドタスクの最終テキストだけが必要な場合、
stream: falseの方が単純で推論コストも低くなります。ストリーミングは対話経路に取っておいてください。
エラー応答を解釈し、リトライを設計する
失敗が一時的なものである場合にのみ、リトライは役立ちます。不正なリクエストを盲目的にリトライすると、エラーを増幅するだけです。有用な区別は、コード側で修正するエラーと、ネットワークやサーバーが自力で解決するエラーです。
ステータスコードによる分類
リトライしない——リクエストを修正する:
- 400 Bad Request——JSON 形式の誤り、必須フィールドの欠落、パラメータ値の無効。エラーメッセージを読み、リクエストペイロードを修正し、再発防止のテストを追加してください。
- 401 Unauthorized——キーの欠落、形式の誤り、または失効。
Authorizationヘッダの形式と、環境変数が実際に実行プロセスに設定されているか(シェルだけでなく)を確認してください。 - 403 Forbidden——キーは有効だが、この操作やこのモデルの使用が許可されていません。ここでのリトライループは単なるノイズです。
- 404 Not Found——多くの場合、パスの誤りか未知のモデル識別子です。ベース URL と正確なモデル文字列を確認してください。
- 422 系の検証エラー——パラメータの型は正しいが値が受け入れられません(例:範囲外の
temperature)。コード側で値をクランプしてください。
バックオフ付きでリトライする:
- 429 Too Many Requests——レート制限を超えました。バックオフし、応答に retry-after のヒントが含まれていれば推測せずに従ってください。
- 500 / 502 / 503 / 504——サーバー側またはゲートウェイの障害。まさに指数バックオフの出番です。
- 接続エラーとタイムアウト——応答完了前にソケットが失敗しました。リトライしますが、操作が安全に繰り返せる場合に限ります。
行儀の良いリトライループ
import random
import time
import requests
RETRYABLE_STATUS = {429, 500, 502, 503, 504}
def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(url, headers=headers, json=payload, timeout=30.0)
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
else:
if r.status_code < 400:
return r.json()
if r.status_code not in RETRYABLE_STATUS:
raise RuntimeError(f"リトライ不可 {r.status_code}: {r.text[:200]}")
if attempt == max_attempts:
raise RuntimeError(f"リトライ上限に達しました。最後のステータス {r.status_code}")
delay = base_delay * (2 ** (attempt - 1))
time.sleep(delay + random.uniform(0, 0.5))
raise RuntimeError("unreachable")
本番環境で重要な2つの詳細
- ジッターは任意ではない。これがないと、同時にレート制限に当たったワーカーの群れが歩調を合わせてリトライし、スパイクを再び作り出します。上記のランダム項がそれらを分散させます。
- 試行回数だけでなく総時間を制限する。指数バックオフの4回の試行はリクエストの期限を超える可能性があります。最悪の場合でも呼び出し元の予算内に収まるよう試行回数を制限し、残り時間を次の試行のタイムアウトとして下流に渡してください。
ユーザーにすでに送信したテキストをどう扱うかを決めていない限り、部分失敗したストリーミングリクエストをリトライしないでください。一般的なパターンは、まだ何も表示していない場合にのみリトライし、それ以外は切り詰めを明示することです。
本番投入前のチェックリスト
このコードが重要なワークロードになる前に、簡単なチェックリストを実行してください。
- どこにでもタイムアウトがある。すべてのリクエストに明示的な接続/読み取りタイムアウトがあり、その値はサンプルからのコピーではなくレイテンシ予算に由来している。
- 機密情報はリポジトリの外にある。API キーは環境変数やシークレットマネージャーから取得し、ログには決して書き込まない。あらゆるリクエストロガーからヘッダを除去する。
- モデル名は1箇所に集約されている。
kimi-k3.1-pro-highspeedは単一の定数として現れ、検索置換なしで差し替えや A/B テストができる。 - エラーは握りつぶされず分类される。リトライ可能と不可能の経路がコード上で明確に分かれ、バックオフにジッターが含まれ、試行回数に上限がある。
- 使用量を記録する。各応答が返す token 使用量を、レイテンシやステータスと一緒にログに残す。token 課金では、これはプロンプトが静かに大きくなりすぎていることの早期警告になる。
- ストリーミング経路は実際にテストされている。同じプロンプトで連結出力が非ストリーミング出力と等しいこと、ストリーム途中の切断で UI が壊れた状態にならないことを検証する。
- 設計によりコストを制御する。常に
max_tokensを設定し、会話履歴を削減し、長い文書はコンテキストに入れる前に要約する。これら3つのレバーが、支出を価値に比例させます。
これらができていれば、curl の概念実証から本番の呼び出し元への移行は主に設定作業です。非ストリーミング関数から始め、対話経路が存在してからストリーミングを追加し、防げない失敗はリトライラッパーに吸収させてください。