チュートリアル
HiAPI API で gpt-image-2.6-flare/text-to-image を呼び出す方法:curl、Python、実行可能なリクエスト
このページの内容
本チュートリアルで構築するもの
多くのテキストから画像生成のチュートリアルは、成功レスポンスのスクリーンショット一枚で終わってしまいます。それでは何も本番環境に投入できません。このチュートリアルでは、ゼロから始めて、HiAPI の統一 API と gpt-image-2.6-flare/text-to-image モデルを使って、再利用可能で動作する統合を構築します。
終了時点で、あなたは三つのものを手にしています:
- 動作が確認されたリクエスト。まず
curlコマンドとして提示され、次に等価な Python スクリプトとして提示されます。 - HiAPI がテキストから画像生成の呼び出しをどのように構成するかについての明確なメンタルモデル——エンドポイントパス、認証ヘッダー、プロンプトペイロード、レスポンスボディ——これにより、例を丸暗記するのではなく、自分のプロンプトに合わせて適応させることができます。
- この単発呼び出しをバッチ処理に拡張するパターン、およびどの失敗を再試行すべきか、どれを修正すべきかを見極める方法。
コードは簡潔に、依存関係は最小限に保ちます。Python の例は標準ライブラリのみを使うため、Python がインストールされている任意の環境で実行できます。リクエスト構造に慣れたら、requests や非同期クライアントに適応させてください。実行可能な呼び出しに直接飛びたい場合は、curl セクションまで飛ばし、あとで説明を読みに戻ってきてください。
前提条件と認証情報
最初の呼び出しの前に、以下が揃っていることを確認してください:
- HiAPI アカウント。 ダッシュボードにログインして、認証情報を生成・管理します。
- API キー。 ダッシュボードの API キーセクションで作成します。パスワードと同様に扱ってください。これはあなたのアカウントに課金されるすべてのリクエストを認証するものです。
- HTTP リクエストを送信する手段。
curlがインストールされたシェル、または標準ライブラリ付きの Python 3(urllibとjsonは Python に同梱されています)。
環境変数によるキーの管理
キーをコミットされるソースファイルに直接貼り付けないでください。代わりにシェルでエクスポートします:
export HIAPI_API_KEY="your-api-key-here"
Windows PowerShell では、$env:HIAPI_API_KEY = "your-api-key-here" を使用します。CI では、シークレットとして注入します。長時間実行するサービスでは、起動時にシークレットマネージャーから読み込みます。
ベース URL の所在を把握する
HiAPI は単一の統一 API サーフェスを提供するため、ベース URL はモデル間で安定しています。コード全体に散らばせるのではなく、設定値として保持してください——環境変数が適しています。これにより、ステージングと本番の切り替えや、テストをモックサーバーに向けることが一行の変更で済みます。
呼び出すモデル識別子は gpt-image-2.6-flare/text-to-image です。スラッシュが含まれていることに注意してください。識別子は完全なままにし、以下の例に示すとおり、リクエストビルダーが期待するパス位置に置いてください。
キーがエクスポートされ、ベース URL が記録されたので、リクエスト自体を見ていきましょう。
テキストから画像生成リクエストの解剖
すべての HiAPI テキストから画像生成呼び出しには、同じ四つの構成要素があります。一度理解すれば、モデルやプロンプトの切り替えは機械的な作業になります。
1. エンドポイントパス
リクエストはモデル識別子をパスの一部として使用します:gpt-image-2.6-flare/text-to-image をベース URL の後に付加します。これが、統一インターフェースの背後で正しいモデルに呼び出しをルーティングするアドレスです。
2. 認証ヘッダー
認証は Authorization ヘッダー内の bearer トークンです:
Authorization: Bearer $HIAPI_API_KEY
すべてのリクエストにこのヘッダーを含める必要があります。欠落や形式の誤りは、初回呼び出しが失敗する最も一般的な原因です。
3. リクエストボディ
テキストから画像生成の呼び出しは、JSON ボディを持つ POST です。中心はプロンプト——生成したい画像の自然言語による説明です。リクエストボディは生成設定も運びます。HiAPI はモデル間でリクエスト構造を正規化するため、リクエストビルダーを再利用し、出力を比較したいときにはモデル識別子を変更するだけで済みます。
4. レスポンスボディ
成功したレスポンスは、生成された画像(またはその参照)と生成に関するメタデータを返します。クライアントは画像を解析しようとする前に HTTP ステータスを確認すべきです。レスポンスは目視するものではなくデータとして扱ってください——自動化のためには、画像のバイト列または URL が必要であり、ファイルをそれを生成した呼び出しに紐付けるために、リクエスト識別子をそれらと一緒に保存する必要があります。
これがモデルの全体像です。以降のすべては、これら四つの部分の具体的なインスタンス化です。
curl で実行可能なリクエストを送信する
これが完全な呼び出しです。プロンプトを自分のテキストに置き換えて実行してください:
curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
}' \
--output response.json
行ごとの解説:
-X POST——生成は状態を変更する呼び出しなので、POST を使用します。- URL——環境変数からのベース URL に、モデル識別子と
/text-to-imageを続けたもの。引用符で囲むことで、シェルが特殊文字を誤って解釈するのを防ぎます。 Authorization: Bearer ...——認証情報。$HIAPI_API_KEYの形式により、リテラルのキーがシェル履歴に残りません。Content-Type: application/json——サーバーにボディを JSON として解析するよう伝えます。これを省略することは、紛らわしい 4xx エラーのよくある原因です。-d '{...}'——JSON ペイロード。promptフィールドは最も頻繁に変更するフィールドです。出力を調整する際には、ここに生成設定を追加します。--output response.json——レスポンスボディをファイルに書き出すので、バイナリの画像ペイロードがターミナルを埋め尽くすことはありません。ファイルを開くか、レスポンスが JSON エンコードされている場合はjqにパイプします。
簡単な健全性チェック
コマンドが迅速に戻り、response.json が空でなければ、動作する統合が手に入ったことになります。代わりに 4xx が返ってきた場合は、レスポンスボディを確認してください——HiAPI は説明的なエラーを返します。以下のエラー処理セクションでは、よくある容疑者を扱います。
これが動作したら、コマンドをプロジェクトの隣のシェルスクリプトに保存してください。認証情報の変更をテストしたり、障害が自分の側にあるかどうかを確認する最速の方法です。
Python で同じリクエストを送信する
curl の呼び出しは Python に直接変換できます。このスクリプトは標準ライブラリのみを使用し、環境変数からキーを読み込み、画像レスポンスをディスクに書き出します:
import json
import os
import urllib.error
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"
def generate_image(prompt: str, settings: dict | None = None) -> bytes:
payload = {"prompt": prompt}
if settings:
payload.update(settings)
request = urllib.request.Request(
f"{BASE_URL}/{MODEL}",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return response.read()
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
if __name__ == "__main__":
body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
with open("output.bin", "wb") as f:
f.write(body)
print(f"wrote {len(body)} bytes")
意図的な選択がいくつかあります:
- タイムアウトはゆとりを持たせています。 画像生成はテキスト補完より遅いため、120 秒の上限は永久にハングするのを避けつつ、遅いが成功する呼び出しにも耐えられます。
- 関数はパスではなくバイト列を返します。 これにより再利用可能になります——バイト列をオブジェクトストレージにアップロードしたり、Web ハンドラーから返したりできます。
- エラーはレスポンスボディ付きでラップされます。 失敗時、メッセージはステータスコードだけでなく、サーバーが何を言ったかを伝えます。
- ペイロードビルダーはオプションの設定を受け付けます。 生成パラメータを追加するときは、関数にハードコードするのではなく
settings辞書を拡張します。
二つの環境変数をエクスポートしたら、python generate.py で実行します。requests を好む場合は、リクエスト構築を requests.post(url, json=payload, headers=headers) に置き換えてください。構造はまったく同じです。
バッチ処理と並行処理のパターン
一つのプロンプトはデモであり、多くのプロンプトは仕事です。この移行は二つの問題を持ち込みます:スループットとデバッグ性です。
ファイルからプロンプトを反復処理する
プロンプトを改行区切りのファイルまたは JSON 配列に入れます。各プロンプトに ID(スラッグ、インデックス、ハッシュ)を割り当て、その ID で出力ファイルに名前を付けます。数百枚の画像のバッチが完了したとき、推測することなく各ファイルをそのプロンプトにマッピングできます。
prompts = [
("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
body = generate_image(text)
with open(f"out/{prompt_id}.bin", "wb") as f:
f.write(body)
並行処理を明示的に制御する
生成呼び出しは I/O 集約型なので、並行処理はスループットに役立ちます——しかし無制限の並行処理はレート制限を引き起こし、エラーの泥沼に陥ります。まず直列で実行し、単一呼び出しの所要時間を測定してから、有界のワーカープールで並行処理を増やします。少数の固定ワーカースレッド(最初は四から八)を使う単純なスレッドプールで通常は十分です。
より大きなジョブでは、非同期クライアントやワーカーキュー付きのキューを使用します。重要な規律は同じです:有界の並列度、プロンプト ID ごとに一つの出力ファイル、リクエストごとに ID、ステータス、所要時間を一行でログに記録。
マニフェストを保持する
バッチ実行中に小さな JSON マニフェストを書き、各プロンプト ID とその結果を記録します。プロセスが途中で死んだ場合、マニフェストはバッチ全体を再課金するのではなく、どこから再開するかを教えてくれます。この実践は、どんな賢い最適化よりも多くの時間を節約します。
エラーと再試行の処理
失敗は二つのカテゴリに分かれます:あなたが修正するものと、再試行するものです。それらを混同すると時間を無駄にし、再試行の嵐の中ではお金も無駄にします。
これらを修正する
- 401 / 403——認証。 キーの欠落、期限切れ、またはアクセス権限の不足。コマンドを実行するシェルで
HIAPI_API_KEYが実際にエクスポートされているか確認してください——あるターミナルでエクスポートし、別のターミナルでスクリプトを実行するのがよくある落とし穴です。 - 400——ペイロードの形式エラー。 無効な JSON、
promptの欠落、または予期しないフィールド型。エラーボディは通常、問題のあるフィールドを指摘します。curl 呼び出しでは JSON の引用に注意してください。 - 404——パスの誤り。 モデル識別子のスペルがドキュメントと完全に一致していること、ベース URL に重複や欠落したパスセグメントがないことを確認してください。
これらをバックオフ付きで再試行する
- 429——レート制限。 速度を落とします。レスポンスに retry-after のヒントがあれば尊重し、ジッター付きの指数バックオフを使用します。長期的には並行度を制限してください。
- 5xx——サーバーエラー。 通常は一時的です。限られた回数(三回が妥当なデフォルト)再試行し、遅延を増やし、それでも失敗したら大きく失敗させます。
最小限の再試行ラッパー
import random, time
def with_retries(fn, attempts=3):
for i in range(attempts):
try:
return fn()
except RuntimeError as exc:
if i == attempts - 1:
raise
time.sleep((2 ** i) + random.uniform(0, 0.5))
これで generate_image をラップします。鍵となるのは、あなたの側で操作を冪等にすることです:出力ファイルはプロンプト ID をキーとしているため、再試行は重複ではなく上書きになります。すべての失敗をプロンプト ID とサーバーメッセージとともに記録してください——実際にエスカレーションが必要なとき、そのログこそがサポートチームが問題を再現するのに必要なものです。
次のステップ
これで、動作するリクエスト、保持する価値のある Python 関数、そして大規模に実行するためのパターンが手に入りました。本番向けに強化するには、リクエスト ID 付きの構造化ログを追加し、マニフェストを永続ストレージに保存してバッチジョブがクラッシュ後に回復できるようにし、送信前にプロンプトを検証して形式の誤った入力が迅速かつ安価に失敗するようにします。
最も有用な次のステップは、HiAPI API 上の他のモデルでこのまったく同じクライアントを再利用することです。エンドポイントパス、認証ヘッダー、ペイロード構造が共有されているため、スクリプトを新しいモデルに適応させることは通常、モデル識別子の変更、時には一、二の設定の変更を意味します——小さなコード変更が意味のある異なる出力をもたらします。
一つのプロンプトから始め、ファイル生成を確認し、残りはバッチランナーに任せてください。