チュートリアル
HiAPI API で gpt-image-2.6-sunburst/text-to-image を呼び出す方法:curl と Python ガイド
認証、リクエスト構造、実行可能な curl と Python の例、そしてトラブルシューティング
このページの内容
エンドツーエンドで見た、この統合の全体像
HiAPI 上のテキストからの画像生成呼び出しは、すべて同じライフサイクルに従います。コードを書く前に、このライフサイクルを理解しておく価値があります。アプリケーションは生成したい画像を記述した JSON リクエストを構築し、API 資格情報とともに gpt-image-2.6-sunburst/text-to-image に対応する HiAPI エンドポイントへ送信し、生成された画像データまたは取得可能な URL を含むレスポンスを受け取ります。この 3 つの段階を理解すれば、本ガイドの残りは細部の補足にすぎません。
各段階は次のとおりです:
- 認証——HiAPI API キーをリクエストに付加します。通常は HTTP リクエストヘッダーの形です。呼び出しごとのトークン交渉は不要です。
- リクエスト構築——プロンプトを含み、必要に応じてサイズや画像枚数などのパラメータも含む JSON リクエストボディを組み立てます。
- 送信——リクエストボディをエンドポイントに POST します。呼び出しは同期なので、クライアントは画像生成の完了まで待機します。
- レスポンス処理——API は構造化 JSON を返します。エンドポイントの設定に応じて、画像データは URL の形、またはエンコードされた画像コンテンツの形で届き、それをデコードしてディスクに書き込む必要があります。
早い段階で注意すべき点が 1 つあります。モデル識別子 gpt-image-2.6-sunburst/text-to-image にはスラッシュが含まれています。これは不透明な文字列として扱ってください。プロバイダー名とモデル名に分割しようとしたり、独自に URL エンコードや正規化を行ったりしないでください。ドキュメントのとおりに正確にコピーし、コード内の 1 か所に配置すれば、後で探し回らずに済みます。
以下の各セクションでは、各段階を順に説明します。curl と Python のパートは意図的に同じリクエストペイロードを使っており、行ごとに比較できます。トラブルシューティングのパートでは、もっとも遭遇しやすいエラーを、修正すべき具体的なリクエストフィールドに対応づけます。
HiAPI リクエストの認証
HiAPI は API キーによる認証スキームを使用します。アカウントのダッシュボードからキーを取得し、リクエストごとに送信します。標準的な形式はリクエスト上の HTTP ヘッダーです:
Authorization: Bearer YOUR_API_KEY
クライアントによってはキーを専用ヘッダーで送る方が好ましい場合もありますが、アカウントのドキュメントに別段の記載がない限り、Authorization: Bearer 形式を使用してください。ほとんどの HTTP ツールでそのまま機能します。
キーをソースコードの外に置く
初回統合でもっともよくあるセキュリティ上の誤りは、キーをスクリプトにハードコードしてコミットしてしまうことです。初日から避けてください:
- キーは環境変数、たとえば
HIAPI_API_KEYから読み取り、変数が存在しない場合は起動時に即座に失敗させます。 - ローカルの
.envファイルを作成する前に、それを.gitignoreに追加します。 - CI や本番環境では、コミットされたファイルからではなく、プラットフォームのシークレットストアからキーを注入します。
キーを 1 回読み取り、存在しない場合に明確なエラーを投げる小さなヘルパー関数があれば、後で混乱するデバッグを 1 回回避できます:
import os
api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
raise RuntimeError("HIAPI_API_KEY is not set")
リクエスト時にもキーを機密として扱う
失敗した呼び出しを調査するときに、ヘッダーを含むリクエストオブジェクト全体を印刷したくなっても我慢してください。代わりにエンドポイント、モデル識別子、ステータスコードを記録します。デバッグのためにヘッダーを取得する必要がある場合は、まず Authorization の値をマスクしてください。ログアグリゲーターに漏れたキーは、コードリポジトリにコミットされたキーと同じくらい露出しています。
キーをローテーションすると、古いキーはローテーション完了直後に無効になります。そのため、ローテーションは緊急作業ではなく定期的な作業として計画してください。
テキストからの画像生成リクエストの構造を分解する
リクエストボディは JSON オブジェクトです。gpt-image-2.6-sunburst/text-to-image の場合、中心となるフィールドはごく少数です。だからこそ、リクエストペイロードを盲目的にコピーするのではなく、各フィールドが何をするのかを正確に理解する価値があります。
model フィールド
"model": "gpt-image-2.6-sunburst/text-to-image"
このフィールドはモデルを選択し、必須です。文字列はドキュメントの識別子とバイト単位で一致させてください。スラッシュの欠落、余分な空白、大文字小文字の変更は、いずれも未知のモデルとしてリクエストが拒否される原因になります。
prompt フィールド
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"
これは画像の自然言語による記述であり、必須です。プロンプト自体に関する実践的なアドバイス:
- まず主体、次に場面、最後にスタイルや光の手がかりを書きます。
- 抽象的な概念より具体的な名詞を優先します。「木製のテーブルの上の赤い陶器のマグカップ」は「いい感じのカップの場面」に勝ります。
- 複数の呼び出しで一貫した出力が必要な場合は、変化しない部分の言い回しを安定させ、変化する部分だけをプログラムで置き換えます。
任意パラメータ
エンドポイントによって、出力の形や数を制御するパラメータも送信できます。もっとも一般的なものは:
- size——出力サイズ。ドキュメントで規定された形式、たとえば
1024x1024で指定します。省略するとデフォルト値が適用され、サポートされていない値を送ると検証エラーが返ることが想定されます。 - n——1 つのプロンプトに対して生成する画像枚数。生成された画像ごとに個別に課金されるため、ワークフローに必要な最小値に保ってください。
本当に必要なパラメータだけを送信してください。未知のフィールドは厳格な検証エラーを引き起こす可能性があり、そのエラーは送るつもりのなかったフィールドを指し示します。
完全なリクエストボディの例
{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}
約束事はこれだけです。本ガイドのそれ以外の内容は、このペイロードを中心とした送信、エラー処理、ライフサイクル管理です。
curl で動作するリクエストを送る
Python クライアントを構築する前に、curl でエンドポイントと資格情報が機能することを確認してください。これにより認証の問題とコードの問題を切り分けられます。
呼び出しコマンド
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}'
これらのフラグに関する補足:
-sSは出力を簡潔に保ちつつ、転送エラーは表示します。-X POSTはメソッドを指定し、リクエストボディは-dで渡します。- JSON リクエストボディを囲むシングルクォートは、シェルによる破壊を防ぎます。Windows の
cmdでは JSON の引用規則が異なるため、curl.exeとダブルクォートを使い、内部の引用符をエスケープするか、シェルスクリプトや Python から呼び出してください。
アカウントのドキュメントにある正確なエンドポイントパスを使う場合はここで置き換えてください。リクエストの形は変わりません。
生のレスポンスを確認する
問題が起きたときは、ステータスコードとレスポンスボディが必要です。レスポンスヘッダーを含めるには -i を、末尾にステータスを表示するには -w "\nHTTP %{http_code}\n" を追加します:
curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json
ペイロードを payload.json に保存し、@payload.json で参照する価値はあります。シェルの引用ミスを避けられ、コマンドを書き直さずにプロンプトを編集できます。プロンプトに機密テキストが含まれる場合は、そのファイルをバージョン管理から除外してください。
Python で同じ呼び出しを行う
Python 版でも JSON リクエストボディはバイト単位で同一に保ちます。変わるのは送信方法だけです。requests を使うと依存が 1 つ増えますが、コードを読みやすく保てます。使い捨てスクリプト以上の用途なら導入する価値があります。
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1,
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)
data=json.dumps(payload) ではなく json=payload を使う理由:dict を json キーワード引数に渡すとシリアライズされ、Content-Type ヘッダーが自動的に設定されます。文字列を data に渡しても動作しますが、ヘッダーの設定を忘れやすく、後でわかりにくい検証エラーとして現れます。
標準ライブラリを使いたい場合
依存を避けるには、標準ライブラリの urllib.request を使えます。ペイロードの dict は変わりません:
import json, os, urllib.request
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}
request = urllib.request.Request(
"https://api.hiapi.ai/v1/images/generations",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
},
data=json.dumps(payload).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=120) as response:
data = json.loads(response.read().decode("utf-8"))
どちらの方法でも、画像生成は一般的な JSON API 呼び出しより遅くなります。タイムアウトは余裕をもって設定してください。そうしないと、成功間近のリクエストでタイムアウトし、リトライ時に二重に課金される可能性があります。
レスポンスを処理して画像を保存する
成功したレスポンスは JSON です。画像出力は通常、URL(別途取得する必要がある)またはペイロードにエンコードされた画像コンテンツの形で届きます。どの形が該当するかはエンドポイントのドキュメントで確認し、パラメータによって正確な形が変わり得るため、両方の形を防御的に処理してください。
レスポンス構造を読む
レスポンスは生成出力とメタデータを含む JSON オブジェクトです。解析コードを書く前に、一度対話的に確認してください:
print(json.dumps(data, indent=2)[:2000])
画像がどこにあるかを見つけてください。URL フィールドがあればダウンロードします。base64 コンテンツがあればデコードします。URL が永続的に有効だと仮定しないでください。短期的に有効なものとして扱い、すぐにバイトを自分のストレージにコピーしてください。
URL ベースの結果を保存する
image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
エンコードされた結果を保存する
import base64
encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
with open("output.png", "wb") as f:
f.write(base64.b64decode(encoded))
実際のワークロードでは、呼び出しごとに異なるファイル名を使ってください。タイムスタンプ、リクエスト ID、プロンプトから派生したスラッグなどです。後で出力を再生成したり監査したりする予定なら、プロンプトを画像と一緒にサイドカー JSON ファイルに保存してください。
成功レスポンスの処理を 1 か所にまとめる
レスポンスの解析を関数にカプセル化し、画像ごとに 1 つのバイト文字列のリストを返します。こうすれば、各呼び出し元はバイトが URL 由来かエンコードされた内容由来かを知らなくても、書き込みやアップロードだけを行えます。後でモデルを切り替えるときに、この抽象化が報われます。
よくあるエラーを診断する
初回統合の失敗のほとんどは、少数のカテゴリに収まります。他の何かを変更する前に、ステータスコードとメッセージを以下の修正方法に照らし合わせてください。
認証失敗
資格情報の欠落または無効によりリクエストが拒否された場合、Authorization ヘッダーが欠落しているか、形式が誤っているか、失効したキーを持っていることを意味します。次の順序で確認してください:
- ヘッダー名と値の形式を確認します。リテラルな
Bearerの後にスペースが 1 つあることを含みます。 - 呼び出しを実行するシェルまたはプロセスで環境変数が実際に設定されていることを確認します。あるターミナルで設定したキーは別のターミナルには存在しません。
- コピー時にキーがローテーションされたり切り詰められたりしていないことを確認します。
リクエストボディの検証エラー
API は必須フィールドが欠けているか、無効な値を含むリクエストボディを拒否します。メッセージは通常、問題のあるフィールドを指し示します:
- model または prompt の欠落——どちらも必須です。デフォルトに頼らず、毎回明示的に送信してください。
- 未知のモデル——識別子
gpt-image-2.6-sunburst/text-to-imageを、スラッシュと大文字小文字を含めて再確認してください。その周囲に空白文字を挿入しないでください。 - 無効なサイズ——ドキュメントで規定された形式のサポート対象サイズ文字列を使ってください。size を意図的に省略する場合は、
nullを送るのではなく削除してください。 - JSON の形式エラー——多くの場合、curl でのシェル引用問題か、Python での文字列エンコード問題です。送信前に
json.dumps(payload)で検証し、実際に送信されている内容を確認してください。
レート制限とクォータ
スロットリングのレスポンスを受け取った場合は、すぐにリトライするのではなく、バックオフとジッターを使ってリトライしてください。メッセージがクォータの問題を示している場合は、リクエストボディではなくアカウントのプランと使用状況パネルを確認してください。ペイロードはおそらく正しいです。
サーバーエラー
生成中の 5xx は通常一時的です。指数バックオフで 1〜2 回リトライしてください。異なるプロンプトやペイロードでも継続的に発生する場合、問題はこちら側ではありません。レスポンスボディを取得し、リクエスト時刻とモデル識別子を添えてサポートに連絡してください。
コンテンツタイプのエラー
Content-Type: application/json を設定せずにリクエストボディを送信すると、サーバーがペイロードを解析できず、わかりにくい検証エラーが発生することがあります。curl ではヘッダーを明示的に設定し、Python では json= 引数に設定を任せてください。
統合を本番運用可能にする
最初の成功した呼び出しは簡単な部分です。以下の調整により、統合は実行コストと変更コストの両方で安価に保てます。
モデル識別子を設定可能にする
モデル識別子は定数、または環境から駆動される設定値に保存し、複数の呼び出し箇所にインラインで書かないでください。後で別のモデルを評価するときは、1 つの値を変更してテストを再実行するだけです。どのモデルがどの画像を生成したかを記録するため、リクエストごとのフィールドをログに残しておけば、すべてを再実行せずにモデル切り替え時の品質を比較できます。
戦略的にリトライする
ネットワークエラー、タイムアウト、5xx レスポンスには指数バックオフとジッターを使ってリトライしてください。検証エラーや認証エラーは決してリトライしないでください。リクエストは同じように失敗し、レート制限を無駄にするだけです。試行回数を制限し、各試行の番号と最終ステータスを記録してください。
ワークロードに合ったタイムアウトを選ぶ
画像生成は遅いです。短すぎるタイムアウトは成功し得たリクエストを失敗させ、リトライするとすでに完了した生成に対して支払う可能性があります。リクエストごとのタイムアウトは余裕をもって設定し、しきい値を超えるタイムアウトは、積極的にリトライする理由ではなく、レイテンシを調査するシグナルとして扱ってください。
クライアントを層に分ける
3 つの部分を分離して保ってください。アプリの入力をリクエスト dict に変換するペイロードビルダー、HTTP 呼び出しを行う送信関数、レスポンスをバイトにデコードするハンドラーです。ビルダーはネットワーク呼び出しなしで簡単にテストでき、送信部分は mock に置き換えるのも簡単です。この階層化により、モデル変更はコードベースを探し回る作業ではなく、1 ファイルの編集になります。
インシデント時に必要になる情報を記録する
タイムスタンプ、エンドポイント、モデル識別子、HTTP ステータス、プロンプトのハッシュまたは切り詰めた形、リクエストの所要時間を記録してください。API キーや完全なヘッダーは決して記録しないでください。生成された画像を保存する場合は、サポートチケットから実際の呼び出しまで追跡できるよう、リクエスト ID ごとにストレージパスを設定してください。
認証を環境変数で処理し、ペイロードをビルダー関数に分離しておけば、gpt-image-2.6-sunburst/text-to-image で練習したパターンは、同じ HiAPI エンドポイント上の他のあらゆる画像モデルにそのまま移行できます。