HiAPI API で gpt-image-2.5-sunburst/text-to-image を呼び出す方法：curl と Python

このモデルエンドポイントが提供するもの

gpt-image-2.5-sunburst/text-to-image は、HiAPI の統合 API を通じて公開されている画像生成モデルです。モデル ID で呼び出し、テキストモデルと同じ chat-completions 形式のリクエストボディでプロンプトを送信し、レスポンスで生成された画像データを取得します。

実務上の意味はこうです。既存のコードベースがすでに HiAPI でテキストを扱っているなら、2 つ目の SDK も、別個の認証方式も、新しいエンドポイント群を学ぶ必要もありません。変わるのはモデル ID だけです。

タスクがプロンプトから画像への生成——テキスト記述から新しい画像を生成し、必要に応じてリクエストで提供した参照画像に導かれる——である場合はこのエンドポイントを選んでください。既存画像を生成ではなく分析・説明する必要がある場合は、視覚能力を備えたチャットモデルの方が適しています。画像の生成はこのエンドポイントに、画像の理解は別の場所に任せましょう。

あらかじめ一つの前提を設定しておきましょう。画像呼び出しはテキスト補完より遅いです。レスポンス時間が一桁秒に達するのは正常であり、クライアントのタイムアウトは純粋なテキスト設定から引き継ぐのではなく、この現実に合わせて調整する必要があります。

最初のリクエストを送る前に

三つのものを準備する必要があります。

API キー

HiAPI アカウントでキーを作成し、ソースコードに書くのではなく環境変数として保存します：

export HIAPI_API_KEY="your-key-here"

正確なモデル ID

文字列は gpt-image-2.5-sunburst/text-to-image です。不透明な識別子として扱ってください。コピーし、記憶で打ち直さないこと。スラッシュは ID の一部です。ここでのタイプミスは初回呼び出しが失敗する最も一般的な原因であり、ペイロードの問題ではなくモデルが見つからないといったエラーとして現れます。

HTTPS リクエストを送信できるクライアント

最初の検証には curl だけで十分で、ほとんどのシステムにプリインストールされています。アプリケーションコードには、requests ライブラリを使った Python（または任意の HTTP クライアント）で十分です。このエンドポイントはクライアントに専用の画像ライブラリを要求しません。JSON を送って JSON を読み返すだけです。

最初の純粋なテキスト呼び出しの前に、画像を事前アップロードしたりストレージを設定したりする必要はありません。以下の最小リクエストから始め、基本的な往復が機能してから参照画像を追加してください。

curl を使った最小限の動作リクエスト

これが最小の正しい呼び出しです：

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

フィールドごとの説明：

• URL——標準の HiAPI chat-completions パス。画像モデルはテキストモデルと同じルーティングを使用します。
• Authorization——API キーを持つ bearer トークン。このヘッダーの形式が誤っていると、モデルを呼び出す前に 401 を受け取ります。
• Content-Type——application/json である必要があります。
• model——前節の正確なモデル ID。
• messages——標準的な role/content オブジェクトの配列。プロンプトは user メッセージの content です。

成功すると、生成された画像データと通常の補完メタデータを含む JSON レスポンスを受け取ります。まず生のレスポンスをファイルに保存し、確認してから解析ロジックをスクリプトに組み込みます：

curl -sS ... -o response.json

これが画像を返した時点で、認証情報とペイロード形状は正しいです。以降の問題はすべてアプリケーションロジックであり、設定ではありません。

同じリクエストを Python で書く

リクエストの約束事は変わりません。変わるのはクライアント設定、タイムアウト、レスポンス処理だけです。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

注目すべき三つの詳細：

タイムアウトは明示的かつ非対称

タプル (10, 180) は短い接続タイムアウトと寛容な読み取りタイムアウトを設定します。画像生成は本来時間がかかります。テキストクライアントからコピーした単一のフラットなタイムアウトは誤った失敗を生みます。接続タイムアウトは短く保ち、ネットワーク問題を素早く失敗させます。

data= ではなく json=payload を使う

json= で辞書を渡すと、シリアライズを処理しコンテンツタイプを設定してくれます。data= で事前シリアライズした文字列を渡す場合は、ヘッダーを手動で設定してください。

防御的な解析

レスポンスは JSON です。インデックスを付ける前に、予期しない形状の場合はレスポンスボディ全体をログに記録します。実際のレスポンスを見る前に固定のネスト深度を仮定しないでください。また、2xx 以外のステータスに対して成功形状を仮定しないでください。

HiAPI 用に設定されたクライアントライブラリを好む場合でも、送信されるペイロードは完全に同じです。呼び出し箇所が変わるだけです。

参照画像を正しく渡す

参照画像はメッセージコンテンツの内部で提供する必要があり、トップレベルの一時フィールドとして渡してはいけません。これは統合で微妙に間違えやすい部分です。なぜなら、形式が誤った参照は通常エラーにならず、リクエストは成功するのに出力が画像を無視するだけだからです。

言語をまたいでペイロード構造を一貫させてください。user メッセージがコンテンツ配列を持ち、その中のテキスト部分がプロンプトを保持し、画像部分が参照データを保持します。Python で構築したのと同じ JSON リクエストボディが、curl でもバイト単位で表現できなければなりません。Python ペイロードの curl 等価物が書けないなら、構造がずれています。

結果が参照画像を無視しているように見える場合は、次の順序で確認してください：

1. 位置。画像部分は messages[].content の内部にありますか、それともリクエストボディのトップレベルに漏れていませんか？モデルはメッセージ内の内容しか見えません。
2. エンコード。参照画像はエンコードされたデータとしてリクエストで転送されます。データが完全かつ正しい形式であり、手動の連結やずさんなコピー＆ペーストで切り詰められていないことを確認してください。
3. プロンプトとの結合。参照画像は生成を導きますが、指示を置き換えるものではありません。画像の役割——スタイル、構図、被写体——を明示し、モデルが推測できると仮定しないでください。
4. サイズ。非常に大きな参照はリクエストを膨らませ、往復を遅くします。エンコード前にタスクが実際に必要とするサイズに縮小してください。

実用的なデバッグ習慣

参照画像ペイロードを一度構築し、動作する正確な JSON リクエストボディを保存して固定サンプルとして再利用します。その後呼び出しが異常になったら、現在のリクエストボディを固定サンプルと差分比較します。参照画像の回帰のほとんどは構造的なもので、差分比較で数秒で見つかります。

エラー、タイムアウト、リトライの処理

画像エンドポイントはテキストエンドポイントとは異なる失敗の仕方をします。より遅いため、より多くの呼び出しがタイムアウト発動の窓に落ち、作業が重いため盲目的なリトライのコストが高くなります。

クライアントエラーと一時的失敗を区別する

• 4xx（429 を除く）——ペイロード形式の誤り、モデル ID の誤り、認証の欠如。同じリクエストを再試行しても同じように失敗します。リクエストを修正してください。
• 401/403——認証情報の問題。キーと Authorization ヘッダーの形式を確認してください。
• 429——レート制限。リトライしますが、即時再試行ではなくバックオフとジッターを使ってください。
• 5xx と接続エラー——一時的。リトライしてください。
• 読み取りタイムアウト——曖昧です。生成はサーバー側で完了している可能性があります。ワークフローが起こり得る重複を許容できる場合にのみ、タイムアウトをリトライ可能として扱ってください。

安全な内容だけをリトライする

ジッター付きの指数バックオフを使い、試行回数に小さな上限を設けます。通常は 3 回で十分です。簡単なパターン：

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

このループ内で 4xx ペイロードエラーをリトライしないでください。試行回数を無駄にするのではなく、直ちに表面化させ、誤ったリクエストを大声で失敗させましょう。

モデルに合わせてタイムアウトを調整する

画像呼び出しに設定する読み取りタイムアウトはテキストのデフォルトの数倍にし、テキストトラフィックが罰を受けないようにグローバルではなく呼び出しごとに設定してください。プラットフォームに厳格なリクエスト上限がある場合は、生成プロンプトと参照画像を実際に完了できる予算内に収めてください。

リリース前の本番チェックリスト

ほとんどの事故を防ぐ簡単なチェックリスト：

• モデル ID は一箇所に。gpt-image-2.5-sunburst/text-to-image を散在する文字列リテラルではなく、定数または設定値として定義してください。
• キーは環境変数から、決してコミットしない。他のあらゆる機密と同様にローテーションしてください。
• 明示的なタイムアウト、寛容な読み取り窓を持ち、セッションのデフォルトではなくリクエストに設定。
• 429/5xx/タイムアウト時のみリトライ、バックオフとジッターを使い、試行回数を制限。
• 失敗時に完全なレスポンスを記録——解析前にステータス、レスポンスボディ、リクエスト ID を記録し、サポートとの会話が証拠から始められるようにする。
• 動作するペイロードの固定サンプルを保存、通常ケースと参照画像ケースをカバーし、動作変化時に差分比較に使う。
• 参照画像はメッセージコンテンツの内部、タスクに合わせて縮小し、プロンプトでその役割を説明する。
• CI でのスモークテスト、モデル ID に対して実際の呼び出しを行い、リネームや廃止されたモデルをユーザーが発見する前に表面化させる。

これらの習慣はいずれも画像生成に固有のものではありませんが、その一つひとつがテキスト呼び出しより画像呼び出しでよく遭遇する失敗モードに対処しています。一度きちんと設定すれば、エンドポイントはスタックの他の部分と同じように動作します。モデルの現在のパラメータと制限については、設定を最終決定する前に HiAPI のモデルページを確認してください。