HiAPI API 経由で gpt-5.6-terra@azure を呼び出す方法：curl と Python ガイド

gpt-5.6-terra@azure が HiAPI リクエストで意味するもの

HiAPI リクエストにおいて、gpt-5.6-terra@azure はモデル識別子です。チャットリクエストボディの model フィールドにこれを設定します。これがあなた側の唯一の取り決めです。プロバイダー固有の URL を構築する必要も、SDK を変更する必要も、リクエストボディの構造を変える必要もありません。

@azure サフィックスはルーティングメタデータであり、このモデルのこのバリアントのリクエストをどのバックエンドが処理すべきかを HiAPI に伝えます。リクエストボディの他の内容——messages、temperature、max_tokens、stream、tools——はすべて、使い慣れた標準の chat-completions 構造のままです。これは実践上重要です。HiAPI 上で他のモデルを呼び出す動作するリクエストが既にあるなら、gpt-5.6-terra@azure への移行は通常 1 行の変更で済みます。

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

2 つの習慣を身につければ、モデル ID 関連のバグはほとんど発生しなくなります：

• ID を不透明な文字列として扱う。 @ と小文字のサフィックスを含め、そのままコピーします。スペースを入れず、大文字小文字を変えないこと。
• 設定に置き、コード全体に散らばめない。 定数や環境変数を使えば、異なるモデル ID 間の A/B テストはリファクタリングではなく設定変更になります。

サフィックスがルーティングを担うため、ID だけから基盤となるサービススタックについて何かを推測すべきではありません。レイテンシ、制限、サポートされるパラメータは HiAPI がそのモデルを公開する際に有する属性です。したがって、小さなリクエストで実際に動作を検証してから、仮定をアプリケーションに組み込んでください。

前提条件とキーの準備

最初の呼び出しの前に、3 つのことを確認します：

1. HiAPI アカウント。 ログインして認証情報を作成し、コンソールで現在のモデルと価格情報を確認する必要があります。
2. API キー。 コンソールで生成し、安全な場所に保管します——パスワードのように扱ってください。本ガイドは特定のキー形式を前提としません。コンソールが提供する文字列が、そのまま Authorization ヘッダーに入れる値です。
3. HTTP クライアント。 迅速な検証には curl、アプリケーションコードには Python 3 と requests または OpenAI 互換 SDK を使用します。

キーをソースファイルから遠ざける

環境変数を使用します。このパターンはどのプラットフォームでも同じです：

export HIAPI_API_KEY="your-key-here"

そして実行時に参照します。シェルでは："$HIAPI_API_KEY"。Python では：os.environ["HIAPI_API_KEY"]。CI では、.env ファイルをコミットするのではなく、プロバイダーが提供するシークレットストアを使用します。

デバッグのためにキーをターミナルに貼り付けた場合、それがシェル履歴に残る可能性があることを覚えておいてください——実際の認証情報であれば、後でローテーションしてください。ローカル開発では、テスト専用の使い捨てキーを使用する方が、本番認証情報を再利用するよりも管理が容易です。

Base URL とエンドポイントを確認する

HiAPI は OpenAI 互換の chat completions エンドポイントを提供します。コンソールのドキュメントから base URL とパスを取得し、curl と Python で一致させてください——「curl は動くが Python は動かない」という報告のほとんどは、結局のところ末尾のスラッシュやパスセグメントの欠落に行き着きます。

動作する curl リクエスト

以下は最小限の正しい呼び出しです。base URL をコンソールに表示されているものに置き換え、HIAPI_API_KEY がエクスポートされていることを確認してください。

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

フィールドごとの説明：

• -sS はプログレスバーを非表示にしますが、エラーは表示します。レスポンスヘッダーをレスポンスボディと一緒に表示したい場合は -i を追加します。
• Authorization: Bearer $HIAPI_API_KEY はリクエストを認証します。Bearer プレフィックスとスペースの両方が必要です。
• Content-Type: application/json——省略すると、多くのサーバーはボディを解析する前にリクエストを拒否します。
• model——正確な ID gpt-5.6-terra@azure。
• messages——順序付き配列。system は動作を設定し、user はプロンプトを運びます。マルチターン会話では assistant と user のターンを順に追加します。
• max_tokens——レスポンス長の上限。迅速な検証では小さく保ち、失敗のコストを低く、速度を速くします。

成功したレスポンスは choices 配列を含む JSON です。必要なテキストは choices[0].message.content にあります。最初の数回は出力を JSON フォーマッターに通すと、長い 1 行を凝視するのではなく構造を確認できます。

このリクエストが動作したら、環境変数からキーを読み取るシェルスクリプトとして保存します。そうすれば、モデル ID やパラメータを変更するたびに実行できる再現可能なヘルスチェックが得られます。

同等の Python リクエスト

リクエストボディはまったく同じです——変わるのは転送方法だけです。requests を使用します：

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

保持すべき 3 つの詳細：手動でシリアライズするのではなく json=payload を使用する（ヘッダーとエンコーディングを設定してくれます）、常に timeout を設定する、そして raise_for_status() を呼び出して 4xx や 5xx がエラーレスポンスボディをインデックスする際の IndexError ではなく例外として表面化するようにする。

プロバイダー SDK スタイル

エンドポイントが OpenAI 互換であるため、カスタム base URL を設定した SDK は同じリクエストを生成します：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

両方の方法を示す意味は：モデル ID が、どのモデルがあなたにサービスを提供するかを識別する唯一の変数であるということです。残りは通常の chat-completions パイプラインであるため、ロジックを書き直すことなく生の HTTP と SDK を切り替えられます。

ストリーミングとツール呼び出しの追加

これらの機能はどちらもインクリメンタルです。基本リクエストを書き直すのではなく、フィールドを追加し、レスポンスの消費方法を変更します。

ストリーミング

リクエストボディで "stream": true を設定します：

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

レスポンスは単一の JSON オブジェクトではなく、一連のサーバー送信イベントになります。各チャンクはコンテンツの断片を含む delta を運びます。最初と最後のチャンクでは delta.content が None になる可能性があるため、連結する前に判定を行います。生の HTTP を使用する場合も同様です——レスポンスボディを行ごとに読み、data: プレフィックスを削除し、[DONE] をスキップし、各行の JSON を解析します。

ツール呼び出し

リクエストでツールを記述し、モデルにいつ呼び出すかを決定させます：

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

モデルがツールを呼び出したいとき、choices[0].message はプレーンテキストではなく tool_calls 配列を含みます。各エントリには id と function があり、後者には name と arguments（あなたが解析しなければならない JSON 文字列）が含まれます。関数を実行し、結果を一致する tool_call_id とシリアライズされた出力を伴う role: "tool" のメッセージとして返送し、最終的な回答を得るために再度リクエストを行います。

tool_choice は "auto"（モデルが決定）、"none"（テキストのみ）、または指定した関数を受け入れます。ストリーミングとツールは組み合わせて使用できますが、ツール呼び出しの引数はチャンクをまたいで断片として到着するため、蓄積してから解析する必要があります——まず非ストリーミングのツール呼び出しを動作させてください。

一般的なリクエストエラーの診断

以下の順序でデバッグします。各ステップで 1 つのレイヤーを分離し、2 つの問題を同時に追わないようにします。

1. 認証（401 / 403）

最も可能性の高い原因：キーの欠落、Bearer プレフィックスの脱落、または環境変数が空文字列に展開されている。完全なキーを印刷せずにヘッダーの構築方法をエコーし、変数がリクエストを実行する同じシェルまたはプロセスに設定されていることを確認します。

2. エンドポイントとパス（404）

404 は通常、パスの誤りを意味します——タイプミス、/v1 の欠落、または本来ない場所の末尾スラッシュ。コンソールから正確な URL をコピーし、再入力しないでください。

3. モデル ID（400、モデル関連のメッセージ付き）

ID は完全に一致する必要があります：gpt-5.6-terra@azure。よくある失敗には、大文字小文字の変更、@azure の欠落、コピー＆ペーストによる余分なスペースが含まれます。メッセージがモデル不明と言っている場合、サービス障害を疑う前に、設定された文字列をコンソールのリストと 1 文字ずつ比較してください。

4. リクエストボディの形式エラー（400 / 422）

エラーがリクエストボディに言及している場合、まず JSON の有効性を確認します——末尾のカンマやエスケープされていない引用符がよくある原因です。次にフィールド名（message ではなく messages）とロール（system、user、assistant、tool）を確認します。max_tokens は数値でなければならず、tools は正しく構造化されたオブジェクトの配列でなければなりません。

5. ストリーミングレスポンスを通常の JSON として処理する

出力が空、文字化け、または解析エラーをスローする場合、stream: true をリクエストしたにもかかわらず、レスポンスを単一の JSON ドキュメントとして解析している可能性が高いです。イベントストリームとして読み取り、[DONE] をスキップし、None の delta に対する保護を行ってください。

6. クライアントのタイムアウト

長時間の生成はデフォルトの HTTP タイムアウトを超える可能性があります。クライアント側で明示的に引き上げるか、ストリーミングに切り替えてバイトがすぐに到着し始めるようにします。

迅速な再現チェックリスト

• 最小限の curl 呼び出しを実行します。成功した場合、問題はあなたのコードにあります。
• 失敗した場合、新しいシェルでキーとモデル ID を使用して再試行します。
• HTTP ステータスコードとレスポンスボディの両方を記録します——エラーレスポンスボディには診断の詳細が含まれています。
• これらのチェックがすべて通過した後に初めて、サーバー側の問題をエスカレーションする価値があると疑うべきです。

動作するリクエスト、ストリーミングループ、そしてこのチェックリストがあれば、gpt-5.6-terra@azure は他のチャットモデルと同じようにあなたのスタックで動作します——そしてモデルの切り替えは設定の 1 行の変更になります。