チュートリアル
HiAPI API で claude-opus-5-5@aws を呼び出す方法:curl と Python ガイド
このページの内容
HiAPI 経由で claude-opus-5-5@aws を使うとはどういうことか
HiAPI はさまざまなモデルに対して統一された HTTP インターフェースを提供します。プロバイダーごとにアカウント、SDK、認証情報ストレージを個別に設定する必要はなく、HiAPI に対して同じリクエスト形式を使い、モデル識別子で目的のモデルを選択するだけです。本チュートリアルではその識別子は claude-opus-5-5@aws です——@aws という接尾辞はモデル名の一部であり、独立したフィールドではないため、そのまま渡す必要があります。
1 回のリクエストのライフサイクルは次のとおりです:
- 認証——
Authorizationリクエストヘッダーで bearer token として HiAPI API キーを送信します。 - チャット形式のペイロードを送信——
modelとmessages配列を含む JSON リクエストボディ。各メッセージにはrole(system、user、またはassistant)とcontentが含まれます。 - JSON レスポンスを受信——アシスタントの返答はレスポンスの
choices配列に現れ、利用量メタデータも付随します。 - 会話を継続——アシスタントのメッセージと次のユーザーメッセージを同じ
messages配列に追加し、再度送信します。この API はステートレスです。会話全体はリクエストペイロードに保持されます。
各モデルのリクエスト構造は同一であるため、claude-opus-5-5@aws 用に書いたコードは model 文字列を変更するだけで他のモデルに移行できます。このフィールドは、複数のファイルにハードコードするのではなく、コード内の 1 か所(設定値や環境変数など)にまとめてください。
命名に関する補足:プラットフォームはこのモデルを claude-opus-5-5@aws としてドキュメント化しています。この正確な文字列を使用してください。スペルミス、余分な空白、接尾辞の欠落は、有用な警告ではなくモデル未検出系のエラーを引き起こします。
認証情報を取得して認証を完了する
API を呼び出す前に、HiAPI アカウントから API キーを取得する必要があります。このキーは機密情報として扱ってください。環境変数やプラットフォームのシークレットマネージャーに保存し、ソース管理にもブラウザに送るクライアントコードにも絶対に含めないでください。
HiAPI は Authorization リクエストヘッダーの bearer token でリクエストを認証します:
export HIAPI_API_KEY="your-api-key-here"
すべてのリクエストに次を含める必要があります:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
ほとんどの認証失敗を避けるための実用的なルールをいくつか挙げます:
- リテラルの
Bearer接頭辞を保持し、その後にスペース、そしてキーを続けます。接頭辞やスペースの欠落はよくあるコピー&ペーストのミスです。 - ヘッダー値の中でキーを引用符で囲まないでください。
- キーをローテーションする場合は、環境変数を更新してプロセスを再起動してください。長時間稼働するワーカーは古い値をキャッシュしていることがよくあります。
- キーを
.envファイルに貼り付ける際は、末尾の空白や改行を確認してください。一部のローダーは自動で除去しません。
キーが欠落しているか形式が誤っている場合、モデルエラーではなく認証エラー(401 系)が返るため、後続の問題と簡単に区別できます。リクエストが認証を通過すれば、同じヘッダーをストリーミング、ツール呼び出し、および本ガイドの他のすべてのパターンに使用できます——機能ごとに異なる認証情報を使う必要はありません。
サーバー側のコードでは、起動時にキーを一度読み込み、共有クライアントまたは小さなラッパー関数に渡します。これにより機密情報を 1 か所に集中でき、開発用と本番用の認証情報の切り替えが容易になります。
curl で実行可能なリクエストを構築する
以下は完全で実行可能なリクエストです。プレースホルダーのキーを自分のキーに置き換えるか、前節の export を先に実行してシェルに置換させてください。
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5@aws",
"messages": [
{
"role": "user",
"content": "決済 API において冪等な POST エンドポイントが重要な理由を 3 文で説明してください。"
}
]
}'
項目ごとに分解します:
- エンドポイント——
POST https://api.hiapi.ai/v1/chat/completions。 - リクエストヘッダー——bearer token と JSON コンテンツタイプ。どちらも必須です。
model——正確な識別子claude-opus-5-5@aws。messages——role と content オブジェクトからなる配列。最後のユーザーメッセージがモデルが応答する内容です。- ペイロード——
-dは生の JSON を送信するため、引用符の扱いが重要です。シェルではリクエストボディ全体を一重引用符で囲み、JSON キーには二重引用符を使用します。
レスポンスは choices 配列を含む JSON です。生成されたテキストは choices[0].message.content にあり、消費量を監視できるように利用量情報(token 数)も含まれます。レスポンスの利用量は token 単位で課金され、現在の料金はウェブサイトの料金パネルに掲載されています。
よくある調整:
{
"model": "claude-opus-5-5@aws",
"max_tokens": 512,
"temperature": 0.2,
"messages": [
{"role": "system", "content": "あなたは簡潔なテクニカルエディターです。"},
{"role": "user", "content": "上記のリクエストボディを 1 行で要約してください。"}
]
}
max_tokens で暴走する生成を制限し、temperature で冗長さとばらつきを制御し、system メッセージで会話ごとに一度だけ動作を設定します。system メッセージは同じ messages 配列内で、ユーザーターンの前に配置する必要があります。
Python での同じリクエスト
Python 版は標準ライブラリの urllib を使用するため、このスニペットは何もインストールせずに実行できます。クライアントライブラリを好む場合でも、リクエスト構造はまったく同じです——トランスポートが異なるだけです。
import json
import os
import urllib.request
API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"
def ask(user_message: str, system_message: str | None = None) -> str:
messages = []
if system_message:
messages.append({"role": "system", "content": system_message})
messages.append({"role": "user", "content": user_message})
payload = json.dumps({
"model": MODEL,
"messages": messages,
}).encode("utf-8")
request = urllib.request.Request(
API_URL,
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
body = json.loads(response.read().decode("utf-8"))
return body["choices"][0]["message"]["content"]
if __name__ == "__main__":
print(ask("ちょうど 5 語で挨拶してください。"))
この構造を維持する価値がある理由:
MODELとAPI_URLはモジュールレベルの定数であるため、モデルやエンドポイントの切り替えは 1 行の変更で済みます。- キーは環境から取得され、関数は生の機密情報を引数として受け取りません。
- 解析ロジックは末尾に分離されているため、会話の構築方法を変更せずに
urllibをhttpxやrequestsに置き換えることができます。
マルチターンの会話を継続するには、再送信する前にアシスタントの返答と次のユーザーメッセージを messages に追加します。配列をコンテキスト制限に達するまで増やし続け、その後、古いターンを 1 つの system メッセージに要約して予算内に収めます。レスポンスの利用量は token ベースで、現在の料金はウェブサイトの料金パネルに掲載されています。
インタラクティブなシナリオ向けのストリーミングレスポンス
チャット UI や長時間の生成では、ストリーミングは完全なレスポンスを待つのではなく、出力が生成されると同時に部分的な内容を送信します。リクエストボディは 1 つのフィールドを除いて変わりません:
{
"model": "claude-opus-5-5@aws",
"messages": [{"role": "user", "content": "ストリーミングを採用したばかりのライブラリ向けに短い変更履歴を書いてください。"}],
"stream": true
}
stream: true の場合、エンドポイントはサーバー送信イベント(server-sent events)で応答します:各チャンクは data: を接頭辞とする 1 行で、ストリームは最終的な終了マーカーの行で終わります。ほとんどのチャンクは choices 配列内に完全なメッセージではなくテキスト断片を含む delta を持ちます。
curl を使用する場合、-sS のサイレント効果を外して、出力が段階的に到着するのを確認します:
curl -N https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"ゆっくりと 5 まで数えてください。"}]}'
-N フラグはバッファリングを無効にし、チャンクが到着するたびに確認できるようにします。Python では、レスポンスを 1 行ずつ読み取ります:
with urllib.request.urlopen(request) as response:
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line.startswith("data: "):
continue
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
print(text, end="", flush=True)
実用的なヒント:
- 常に
[DONE]終了マーカーと空行/キープアライブ行を処理してください。すべての行が JSON であると仮定しないでください。 - UI スレッドをストリーム全体でブロックしないでください——delta が到着するたびにバッファに追加します。
- クライアントが切断した場合は、上流の生成を解放できるようレスポンスを閉じてください。
- ストリーミングは利用量の計算方法を変更しません。通常、最後のチャンクが利用量メタデータを運びます。課金は出力 token 単位で計算され、現在の料金はウェブサイトの料金パネルに掲載されています。
会話にツール呼び出しを追加する
ツール使用により、モデルは単にテキストを生成するだけでなく、コードから構造化されたアクションを要求できます。リクエストには tools 配列が追加され、会話には tool_calls を運ぶアシスタントメッセージと結果を運ぶ role: "tool" メッセージが追加されます。
JSON Schema を使用してツールのパラメータを定義します:
{
"model": "claude-opus-5-5@aws",
"messages": [
{"role": "user", "content": "リスボンの現在の天気はどうですか?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "指定した都市の現在の天気を返します。",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "都市名(例:Lisbon)"}
},
"required": ["city"]
}
}
}
]
}
モデルは最終的なテキストではなく、tool_calls を含むメッセージを返す場合があります。各エントリは関数名を指定し、JSON 文字列形式の引数を運びます。あなたの仕事は、その関数を自分のシステムに対して実行し、結果を追加することです:
tool_callsを含むアシスタントメッセージをそのままmessagesに追加します。- 各呼び出しに対して、
role: "tool"、アシスタントメッセージ内の一致するtool_call_id、およびシリアライズされた結果を設定したcontentを含むメッセージを追加します。 - 同じ
tools配列を使用してリクエストを再度送信します。モデルはその後、あなたの結果に基づいて自然言語の回答を生成します。
早い段階で確立する価値のあるガードレール:
- 引数を検証する——何らかの操作を実行する前に、スキーマに従って引数を検証してください——モデル出力をシェルやデータベースクエリに直接渡さないでください。
- ループを制限する。 ツール呼び出しのターン数に上限を設定してください(通常 3〜5 ターン)。呼び出しを要求し続けるモデルが無限ループになるのを防ぎます。
- エラーをツール結果として返す。 関数が失敗した場合、一致する
tool_call_idを伴う短いエラー文字列を送信してください。モデルはその後、停止するのではなく再試行したり失敗理由を説明したりできます。 - ツールの説明を正確に保つ。 曖昧な説明は、引数エラーよりもはるかに高い頻度でツール選択の誤りを引き起こします。
ツール定義はリクエストとともに評価され、token 利用量にカウントされます。現在の料金はウェブサイトの料金パネルに掲載されています。
次に何をするか
最小限の curl 呼び出しから始め、それを Python のラッパー関数に移し、その後はユースケースに必要な場合にのみストリーミングとツールを重ねてください。モデル文字列 claude-opus-5-5@aws は常に変わりません——それ以外はすべてリクエストペイロード内のフィールドです。