チュートリアル
HiAPI APIでgpt-6-solを使う方法:curl、Pythonと1回で成功するリクエスト
このページの内容
初回呼び出しの前に準備するもの
コードを書く前に、3つ用意してください。このチュートリアルの残りの内容はこれを土台に進みます。
HiAPI APIキー
HiAPI APIへのリクエストは毎回、APIキーによる認証が必要です。HiAPIアカウントのダッシュボードでキーを作成し、安全な場所に保管してください。できればソースコードファイルではなく環境変数に置きましょう。パスワードと同じように扱い、漏えいしたらすぐにローテーションしてください。
export HIAPI_API_KEY="your-api-key-here"
ベースエンドポイント
このガイドのすべての呼び出しはHiAPI APIのベースエンドポイントに送られ、各モデルは同じリクエストパスの形式でアクセスします。モデルごとに別のホストやSDKを用意する必要はありません。gpt-6-sol はクライアント設定の変更ではなく、リクエストボディで選択します。
HTTPクライアント
次のいずれかが必要です:
curl。ほとんどのLinuxやmacOSシステム、およびWindowsのターミナルでデフォルトで利用できます。requestsライブラリをインストールしたPython(pip install requests)。依存関係を増やしたくない場合は標準ライブラリのurllibでも構いません。
他のツールは不要です。特定ベンダーのSDKも、モデル関連のインストールも必要ありません。JSONボディとヘッダーを付けたHTTPS POSTリクエストを送れるなら、gpt-6-sol を呼び出せます。
今のうちに身につけておきたい習慣:動作するリクエストを書き留めたドラフトファイルを残しておきましょう。失敗したときに、失敗した呼び出しを直近の動作確認済みの呼び出しと比較できます。
bearerキーによる認証
認証は初回呼び出しで最もつまずきやすい部分なので、丁寧に扱う価値があります。
Authorizationヘッダー
HiAPI APIは、キーを標準のbearerヘッダーに入れることを期待します:
Authorization: Bearer $HIAPI_API_KEY
すなわち文字通りの単語 Bearer、半角スペース1つ、その後にキーです。よくある間違いは、Bearer という単語を忘れる、値をコピーする際に余分な改行が入る、クライアントがすでに引用符を付けているのにキーにさらに引用符を付ける、などです。
Content-TypeはJSONでなければならない
リクエストはJSONボディを運ぶため、Content-Typeヘッダーも一致させる必要があります:
Content-Type: application/json
このヘッダーがなくてもボディを解析するサーバーもありますが、それに頼るべきではありません。明示的に設定してください。Content-Typeの不一致は、ボディのエラーのように見えるリクエスト検証エラーのよくある原因です。
最小限のヘッダーセット
必要なヘッダーは上記の2つだけです:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
ヘッダーセットはできるだけ小さく保ちましょう。他のAPIの例から借用した推測的なヘッダーは、役立つよりも混乱を招く可能性が高いです。この2つのヘッダーを使った呼び出しが成功すれば、後で比較できるクリーンなベースラインが得られます。
キーをシェルの履歴やコミット済みファイルに直接貼り付けないでください。上記のように環境変数を参照すれば、キーをソースコードやターミナル履歴から遠ざけられます。
gpt-6-solのリクエストボディを構築する
リクエストボディはJSONで、中心はメッセージのリストです。最小構成から始め、呼び出しが成功してからフィールドを追加してください。
最小限のリクエストペイロード
最小限の有用なリクエストボディでは、モデルを指定し、メッセージを1つ提供します:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "API bearer tokenとは何かを一文で説明してください。" }
]
}
ここでは2つのフィールドが機能します:
modelはgpt-6-solを選択します。これにより、同じエンドポイントで後から他のモデルも扱えます。messagesは順序付けられた会話ターンのリストです。各エントリにはrole(system、user、またはassistant)とcontent文字列があります。
安全なデフォルトと任意の追加項目
model と messages を必須と考えてください。それ以外はすべて任意で、意識的に追加するものです:
messagesの先頭に置くsystemメッセージは、会話の振る舞いやトーンを設定します。これは通常のメッセージであり、独立したトップレベルのフィールドではありません。- 必要に応じて、出力長の制御はリクエストボディ内のパラメータとして設定します。デフォルトの出力がユースケースに対して短すぎるか長すぎる場合にのみ追加してください。
- サンプリング系のパラメータは有効性ではなく出力の形を変えます。失敗した呼び出しのデバッグ中は変更を避けてください。認証やリクエストボディ構造のエラーを修正することはできません。
実用的なルール
失敗したときは、リクエストペイロードを最小例にできるだけ近づけてください。任意のフィールドを1つずつ削除して呼び出しが成功するまで続け、その後で再び追加します。これにより問題をすばやく切り分けられます。不良パラメータは、5つの正常なパラメータに埋もれた不良パラメータよりも見つけやすいです。
curlで1回の成功するリクエストを送信する
以下は完全なコマンドで、キーがエクスポートされていればそのまま実行できます。上記のHiAPI API規約に合ったプレースホルダーのエンドポイントパスを使用しています。
curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "API bearer tokenとは何かを一文で説明してください。" }
]
}'
HIAPI_BASE_URL はHiAPIダッシュボードのベースエンドポイントに設定してください。各フラグは重要です:
-X POSTはメソッドを設定します。これらの呼び出しはすべてPOSTです。-Hは各ヘッダーを1行に1つ追加します。-dはJSONボディを提供します。シングルクォートはシェルによる補間を防ぎます。-sSは出力を静かに保ちつつ、エラーは表示します。スクリプト化するときに必要な挙動です。
レスポンスを読む
成功したレスポンスはJSONです。通常はトップレベルオブジェクトにモデル名とchoicesリストが含まれ、各choiceにはメッセージがあり、その content に生成されたテキストが入っています。本文より先に構造を読んでください。オブジェクトがパースできることを確認し、その後contentフィールドを特定します。
可読性を上げるには、JSONフォーマッターにパイプします:
... | python -m json.tool
ターミナルに代わりにエラーオブジェクトが表示されたなら、呼び出しは成功していません。プロンプトを調整するのではなく、エラーのセクションに進んでください。リクエストがモデルにまったく届いていない場合、問題はプロンプトにありません。
Pythonで同じリクエストを送信する
curlで検証したリクエストペイロードはそのまま移せます。ボディを完全に一致させておけば、ターミナルで検証した修正がコードにも適用できます。
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-6-sol",
"messages": [
{"role": "user", "content": "API bearer tokenとは何かを一文で説明してください。"}
],
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
for choice in data.get("choices", []):
message = choice.get("message", {})
print(message.get("content", ""))
このバージョンがアプリケーションコードでより安全な理由
- ボディは辞書です。
json=payloadを渡すと、requestsがシリアライズしてContent-Typeを設定してくれますが、明示的なヘッダーを残すことでクライアントを切り替えた際の予期せぬ挙動を避けられます。 - キーは環境変数から取得します。 秘密情報がハードコードされていないため、このファイルはコミットできます。
raise_for_status()を先に実行します。 非2xxレスポンスは即座に例外を投げるので、エラーレスポンスボディに存在しないフィールドを読もうとする前に止まります。- タイムアウトを設定します。 タイムアウトがないと、停滞した接続がワーカープロセスを無期限にハングさせる可能性があります。
choices を反復するループはキー欠落にも対処し、出力がほとんどまたはまったくないレスポンスにも耐えられる例になっています。この骨組みの周りに本番用ラッパーを構築してください:検証し、送信し、ステータスを確認し、それから解析します。
待つのではなくレスポンスをストリーミング受信する
デフォルトでは、APIは完全な回答を1つのJSONレスポンスで返します。長い出力や対話的なインターフェースでは、代わりに生成中に段階的にレスポンスを届けるよう要求できます。
ストリーミングのスイッチ
ストリーミングは別のエンドポイントではなく、リクエストボディのフラグで有効にします:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "HTTPステータスコードについて短い文章を書いてください。" }
],
"stream": true
}
このフラグは非ストリーミングの呼び出しがすでに動いてから最後に追加してください。これはリクエストが有効かどうかではなく、レスポンスの構成方法を変えるものです。
差分出力を消費する
ストリーミングを有効にすると、レスポンスは単一のJSONドキュメントではなくなります。一連のイベントとして到着し、通常は行区切りで、各イベントが出力の小さな断片を運びます。クライアントはレスポンスボディ全体に対して .json() を呼ぶのではなく、到着するたびに読み取る必要があります。
with requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
stream=True,
timeout=60,
) as response:
response.raise_for_status()
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))
ターミナルでは、同じスイッチでも非ストリーミングの呼び出しとは挙動が異なります。出力が段階的に現れるため、途中で切れたパイプは、実際にはストリームが中断されただけなのに失敗したリクエストのように見えることがあります。
どちらを使うべきか
バッチ処理、テスト、そして完全なオブジェクトを一度に取得したいあらゆる場面では非ストリーミングを使います。誰かがテキストを待っている場合や、出力が長くて遅延が目立つ場合にはストリーミングを使います。非ストリーミング経路のほうがデバッグしやすいので、コードベースには両方の経路を残しておきましょう。
よくあるエラーコードを読み取って修正する
まずステータスコードで診断し、次にレスポンスボディで診断します。どの層が失敗しているか特定する前に、モデルを変えたりプロンプトを書き直したりしないでください。
401 Unauthorized
原因: キーが欠落、形式不正、または取り消されています。修正: ヘッダーが正確に Authorization: Bearer <key> になっていることを確認し、隠れた空白文字や期限切れの環境変数がないかチェックし、キーがダッシュボードでまだ有効かを検証します。空変数のエラーを捕まえるには、値ではなく変数の長さを出力してください。
400 Bad Request
原因: リクエストボディがパースできない、または必須フィールドが欠けています。修正: model と messages だけを含む最小のリクエストペイロードを再度送信します。送信前に python -m json.tool でJSONを検証してください。末尾のカンマや model のスペルミスがよくある原因です。Content-Type が application/json であることを確認します。
403 Forbidden
原因: キーは有効ですが、要求されたリソースへのアクセス権がありません。修正: アカウントが gpt-6-sol にアクセスできるか、またリクエストボディのモデル名がアカウント設定と一致しているかを確認します。
404 Not Found
原因: URLパスが誤っています。多くの場合、エンドポイントのスペルミス、またはベースパスの欠落や重複です。修正: 完全なURLを、動作するcurl呼び出しと1文字ずつ比較します。
429 Too Many Requests
原因: アカウントで許可された範囲を超える速度でリクエストを送信しています。修正: バックオフして遅延を増やしながら再試行します。レスポンスヘッダーの再試行ガイダンスがあれば従い、ループ内で密に再試行しないでください。問題が悪化します。これはサーバー側の問題を示す5xxとは区別してください。5xxはリクエストレートの問題ではありません。
5xx サーバーエラー
原因: 有効なはずのリクエストをサービスが処理できません。修正: バックオフして再試行します。問題が続く場合はレスポンスボディとリクエストIDを取得し、リクエストペイロードはすでに動作しているので変更しないでください。
再現可能なデバッグ手順
- ステータスコード——認証、パス、ボディのどれが問題か?
- レスポンスボディ——問題のあるフィールドを指し示しているか?
- リクエストペイロード構造——最小例に戻る。
- プロンプトやパラメータは最後に検討する。
この順序は失敗から修正までの時間を着実に短縮します。呼び出しが安定したら、動作するcurlとPythonのバージョンを並べて残しておきましょう。そうすれば今後のすべてのテストは既知の動作状態から始められます。