チュートリアル
HiAPI API 経由で gpt-5.6-sol@azure を呼び出す方法:curl と Python
認証、リクエストボディの構造、動作する例、エラー処理
このページの内容
gpt-5.6-sol@azure が HiAPI のモデルターゲットであるということの意味
gpt-5.6-sol@azure はモデル識別子であり、独立した SDK でも、独立したエンドポイントでも、独立した認証方式でもありません。これは HiAPI に送信するチャット補完リクエストの model フィールドに入れる、あの正確な文字列そのものです。
@azure サフィックスは、そのモデルバリアントがどのバックエンドプロバイダーによって提供されているかを示します。アプリケーションの観点から見れば、呼び出し方法は一切変わりません。同じベース URL、同じ bearer 認証、同じリクエストとレスポンスの構造で、プラットフォーム上の他のどのチャットモデルとも一致します。追加で何かをインストールする必要もなく、特定プロバイダーの資格情報も不要です——HiAPI がその側でルーティングとプロバイダーとの関係を処理します。
実際の結果として、すでに使っている OpenAI 互換クライアントであれば、2 か所の変更でこのモデルを指すことができます。クライアントのベース URL を HiAPI に向け、モデル名を gpt-5.6-sol@azure に設定するだけです。設定のどこかにモデル名をハードコードしている場合、プラットフォーム上でモデルを切り替えるときに変更が必要なのはその設定値だけです——これにより A/B 比較が非常に安価になります。
本チュートリアルでは、この識別子は常にリテラル文字列 gpt-5.6-sol@azure として現れます。正確に入力してください。大文字と小文字は区別され、コピー&ペーストで混入する余分な空白は、後述する「不明なモデル」エラーの実際の原因の一つです。
始める前に必要なもの
- プラットフォームにアクセスできる HiAPI アカウント。
- アカウントから生成した API キー。
curlが入ったシェル、またはrequestsライブラリが入った Python 3。
以下の例では他のツールは一切不要です。
API キーを取得して認証を設定する
HiAPI の認証は bearer トークンです。API キーを各リクエストの Authorization ヘッダーに入れ、先頭に Bearer という単語と半角スペースを付けます。
Authorization: Bearer YOUR_API_KEY
キーはアカウントのダッシュボードから生成します。パスワードと同じように扱ってください——残高を消費できる生きた資格情報であり、コミット履歴、スクリーンショット、共有ノートブック、ログ行に絶対に現れてはなりません。
環境変数に保存する
基本となる方法は、シェルセッションごとに一度キーを export し、それ以外の場所では環境から読み取ることです:
export HIAPI_API_KEY="your-key-here"
サーバー上では、チェックインされた .env ファイルを使うのではなく、プロセスマネージャーやシークレットストア経由で設定してください。.env ファイルがどうしても唯一の選択肢である場合は、最初のキーを書き込む前に .gitignore に追加してください。
インラインではなく参照する
curl ではシェル変数を参照し、キーがコマンド履歴やプロセスリストに決して現れないようにします:
curl -H "Authorization: Bearer $HIAPI_API_KEY" ...
Python では、実行時に os.environ から読み取ります:
import os
API_KEY = os.environ["HIAPI_API_KEY"]
あえて os.environ.get("...") ではなく os.environ["..."] を使っています。変数が欠けている場合は、15 行後で紛らわしい認証エラーに遭遇するのではなく、起動時に大声で失敗してほしいからです。
今すぐ内面化すべきキー衛生のルール
- 環境ごとに 1 つのキー。 開発キーと本番キーは分けるべきで、そうすれば一方を壊すことなくもう一方をローテーションまたは失効できます。
- 露出したらローテーション。 キーが公共の場所に現れたことがあるなら、失効して新しいキーを発行してください——コミットを削除するだけでは不十分です。
- ヘッダーをログに記録しない。 すべてのリクエストヘッダーをダンプするリクエストログミドルウェアは、喜んで bearer トークンをディスクに書き込みます。ログに記録する前に
Authorizationをマスクしてください。
最初の呼び出しで認証エラーが発生した場合、原因はほぼ常に次のいずれかです:リクエストを実行するシェルとは別のシェルで変数を export した、Bearer プレフィックスを忘れた、またはキーのコピーに末尾の改行が付いた。
最小限のリクエストボディの構造分析
gpt-5.6-sol@azure へのすべての呼び出しは JSON ボディ付きの POST です。1 つのフィールドだけで有効なリクエストを組み立てられます。これが最良の始め方です。まずレスポンスを取得し、それからつまみを追加します。
必須フィールド
model—— 文字列gpt-5.6-sol@azure。リクエストを正しいターゲットにルーティングする役割を担います。messages—— メッセージオブジェクトの配列。各オブジェクトはroleとcontentを持ちます。慣例的なロールにはsystem(動作を形作る指示)、user(入力)、assistant(マルチターン会話における過去のターン)があります。
最小限のリクエストボディは次のとおりです:
{
"model": "gpt-5.6-sol@azure",
"messages": [
{ "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
]
}
これで十分です。レスポンスはチャット補完の構造で返ります。choices 配列があり、その最初の要素が message.content の下にアシスタントの返答を格納し、さらにトークン消費を記述する usage ブロックが付きます。コードは他のフィールドを仮定せず、choices[0].message.content から読み取るべきです。
知っておく価値のあるオプションフィールド
これらは必須ではありませんが、最初に使うことになるものです:
temperature—— サンプリングのランダム性。低い値は出力をより決定的で反復的にし、高い値はより多様にします。習慣に頼らず、意図をもって値を選んでください。max_tokens(またはクライアントが公開する同等の出力長上限)—— 生成長の上限。レイテンシとコストの制御に役立ちます。top_p—— もう一つのランダム性制御。実際にはtemperatureかtop_pのどちらかを調整し、両方は調整しないでください。さもないと挙動の変化をどちらにも帰属できなくなります。stream—— true にすると、レスポンスは単一の JSON ドキュメントではなく、サーバー送信イベントとして段階的に届きます。ユーザー向けインターフェースには最適ですが、正しく解析するにはより多くの作業が必要です。stop—— 生成を早期に終了させる 1 つまたは複数のシーケンス。
マルチターン会話についての注記
API はステートレスです。リクエスト間で何も保持されません。会話を続けるには、毎回 messages 配列全体を再送し、過去のアシスタントの返答と新しいユーザーメッセージを追加します。したがって長い会話はリクエストボディを成長させ、トークン使用量もそれに伴って増えます——チャット機能を設計する際はこのことを予算に入れてください。
最初はリクエストボディを簡潔に保つ
2 つの必須フィールドから始め、妥当なレスポンスが得られることを確認します。それから一度に 1 つのパラメータを追加し、違いを観察します。最近の既知の良好なベースラインがあると、デバッグはずっと楽になります。
動作する curl リクエスト
これは完全で実行可能なリクエストです。地域やプランが異なる場合は、ベース URL をプラットフォーム API ドキュメントに表示されている URL に置き換え、HIAPI_API_KEY が現在のシェルで export されていることを確認してください。
curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol@azure",
"messages": [
{ "role": "system", "content": "You are a concise technical assistant." },
{ "role": "user", "content": "Give me three practical uses for idempotency keys." }
],
"temperature": 0.3
}'
各フラグの役割
-sSは進行状況バーを非表示にしますが、エラーは表示します——これにより失敗が見えなくなることはありません。-X POSTはメソッドを明示的に設定します。主に可読性のためです。Authorizationヘッダーは環境からの bearer トークンを運びます。Content-Type: application/jsonは必須です。これがないとサーバーはリクエストボディをどう解析すればよいか分かりません。-dは JSON ペイロードを提供します。シェルが内部の二重引用符を解釈しないよう、シングルクォートで囲みます。
レスポンスを読む
成功した呼び出しは choices 配列を含む JSON を返します。欲しいテキストは choices[0].message.content にあります。さらに、プロンプトと補完のトークン数を含む usage オブジェクトもあります——これを記録してください。消費が予想外になる前にその傾向を観察する唯一の安価な方法だからです。
ターミナルと格闘せずに構造を直接確認したい場合は、フォーマッターにパイプできます:
curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
| python3 -m json.tool
この 1 行は新しいキーが存在するかどうかの最速のスモークテストです。アプリケーションコードに触れる前にこれを実行してください——失敗した場合、問題は資格情報か接続性にあり、あなたのプログラムではありません。
Python での同じリクエスト
requests 版は短いですが、慎重に書くべきです。レスポンスボディを解析する前にステータスコードを確認してください。エラーレスポンスの構造は成功レスポンスとは異なるため、そのまま choices にアクセスすると紛らわしい KeyError が発生します。
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"
payload = {
"model": "gpt-5.6-sol@azure",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Give me three practical uses for idempotency keys."},
],
"temperature": 0.3,
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
if response.status_code != 200:
# Surface the status and the server's error body, not just the exception.
print(f"HTTP {response.status_code}: {response.text}")
response.raise_for_status()
data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))
重要な 3 つの詳細
data=json.dumps(payload) ではなく json=payload を使う。 辞書を json= に渡すと、コンテンツタイプヘッダーが自動で設定され、毎回正しくシリアライズされます。手動でのシリアライズは、フォーマットエラーのリクエストボディのほとんどの原因です。
常に timeout を設定する。 これがないと、停止したリクエストがワーカープロセスを無期限にハングさせます。寛大なタイムアウトでも、ないよりははるかにましです。
失敗時に response.text を出力する。 エラーボディには必要な詳細——エラータイプ、コード、人間が読めるメッセージ——が含まれています。raise_for_status() の例外メッセージだけを記録するとこれらの情報が失われ、推測するしかなくなります。
関数にラップする
呼び出しが動作したら、それを関数に昇格させ、messages 配列を引数として受け取り、コンテンツ文字列を返すようにします。これによりアプリケーションコードが整理され、モデル名、タイムアウト、または後でリトライポリシーを変更する場所がちょうど 1 か所になります。
よくあるエラーのトラブルシューティング
失敗する初回呼び出しのほぼすべては 4 つのカテゴリのいずれかに属します。以下はそれらを素早く見分ける方法です。
認証の失敗
症状:401 レスポンス、またはキーは有効だが要求されたリソースへのアクセス権がない場合は 403。
順番に確認してください:
HIAPI_API_KEYは実際にリクエストを発行するシェルまたはプロセスに設定されていますか?echo $HIAPI_API_KEYで何かが表示されるはずです。- ヘッダーにはリテラル単語
Bearerと、キーの前にちょうど 1 つの半角スペースが含まれていますか? - キーにコピー&ペーストで末尾の改行や引用符が付いていませんか?きれいに再 export してください。
- コピーして以来、キーは失効またはローテーションされていませんか?新しいものを発行してください。
不明なモデル識別子
症状:400 または 404、メッセージでモデルに言及している。
通常の原因は、タイプミス、大文字と小文字の不一致、または文字列内の余分な空白です。gpt-5.6-sol@azure は正確でなければなりません——@、ハイフン、小文字の綴りがすべて重要です。設定ファイルや環境変数からモデル名を読み取る場合は、その値と長さを出力してください。不可視の空白がよくある犯人です。
フォーマットエラーのリクエストボディ
症状:400、JSON 解析またはフィールドの欠落についての苦情。
- エラーが解析に言及している場合、リクエストボディが有効な JSON ではありません。
curlでは、ペイロードをシングルクォートで、キーをダブルクォートで囲みます。Python ではjson=payloadを使います。 messagesに言及している場合、生の文字列ではなく、roleとcontentを持つオブジェクトの配列を渡しているか確認してください。modelの欠落に言及している場合、キーの綴りが間違っているか、ネストの階層が間違っています。
簡単な健全性チェック:送信する前にペイロードを JSON バリデータに通してください。ほんの数秒でカテゴリ全体を排除できます。
レート制限とクォータ
症状:429 レスポンス、時には retry-after ヒント付き。
これはリクエストが正しくフォーマットされ認証済みだが、速すぎるかクォータを超えたことを意味します。修正方法はタイトなループでの即時リトライではありません——それはさらに悪化させるだけです。ジッター付きの指数バックオフを使い、試行回数を制限し、持続的な 429 は並行度を見直すシグナルとして扱ってください。
サーバー側のエラー
500 や 502 はあなたのせいではありません。バックオフでリトライしてください。持続する場合は、エスカレーションする前に完全なリクエスト ID とレスポンスボディを取得してください——これらの詳細がサポートとの会話を生産的にします。
汎用的なデバッグの習慣
失敗した呼び出しごとに 4 つのことを記録してください:HTTP ステータス、レスポンスボディ、エンドポイントパス、モデル名。API キーは記録しないでください。この 4 つ組は上記のすべてのカテゴリを数秒で区別できますが、裸の例外メッセージではめったにできません。
最初の成功した呼び出しの後の次のステップ
スモークテストがコンテンツを返したら、動作する統合が手に入ったことになります。以下はそれを持続させる方法です。
意識的にパラメータを調整する
ユースケースに合った temperature を 1 つ選び、その理由を書き留めてください。抽出や分類のタスクは通常低いランダム性を望み、ブレインストーミングはより多くを望みます。各実験では 1 つのパラメータだけを変更し、結果を帰属できるようにしてください。ストリーミングを検討しているなら、早めにプロトタイプを作ってください——レスポンス解析の違いは十分に大きいため、後から改造する方が最初から使うより骨が折れます。
リトライとタイムアウトを事後対応ではなくポリシーとして
429 と 5xx レスポンスにのみ、指数バックオフ付きのリトライラッパーで呼び出しを包んでください。400 や 401 を決してリトライしないでください——リクエストまたは資格情報が誤っており、リトライは時間の無駄です。各リクエストにクライアントタイムアウトを設定し、ユーザーフロー用の全体の締め切りも検討してください。
初日からコストとレイテンシを監視する
usage ブロックを独自のレイテンシ測定と一緒に記録してください。トークン数はすべてのコストの会話への入力であり、レイテンシはすべてのユーザー体験の会話への入力です。これらがなければ、盲目的に最適化していることになります。
モデル名を設定に入れる
3 つのファイルに gpt-5.6-sol@azure をハードコードすることは、移行が苦痛になる方法です。1 つの設定値に保存すれば、モデルの切り替えは 1 行の変更になります——これもまた、プラットフォーム上でモデルを公平に比較する方法です。
キーを適切なシークレット管理に移す
ノートパソコンの環境変数から始めた場合、本番への道筋は実行時に注入されるマネージドシークレットストアです。同じコード、より安全な保管。
出力パスを強化する
モデルの出力は信頼できない入力です。HTML としてレンダリングする場合はエスケープしてください。JSON として解析する場合は、行動する前に検証してください。下流システムにルーティングする場合は、レスポンスが空または切り詰められたときに何が起こるかを明示的に決めてください。
プラットフォーム上の他のモデルターゲットを探索する準備ができたら、それらは同じリクエスト構造を使います——変わるのは model 文字列だけなので、上記で構築したすべてはそのまま保持されます。