チュートリアル
HiAPI API で gpt-image-2.6-sunburst/image-to-image を使う方法:curl と Python の実践
参照画像を送信し、非同期タスクをポーリングし、リクエストをエンドツーエンドでデバッグする
このページの内容
gpt-image-2.6-sunburst/image-to-image の適用シーン
テキストからの画像生成では、モデルがプロンプトに基づいて自由に結果を生成します。一方、画像からの画像生成は、すでに手元にある素材から出発します:エンドポイントに参照画像と指示を渡すと、モデルはそれを基に参照画像から派生した新しい画像を生成します。HiAPI では、gpt-image-2.6-sunburst/image-to-image がこの 2 番目のモード専用のエンドポイントです。
元の画像自体が要件の一部である場合にこれを選びます。たとえば、既存素材のスタイルを再デザインする、光量や構図を調整する、商品画像に特定の視覚処理を適用する、あるいはあるデザインの制御されたバリエーションを生成する、といったケースです。参照画像がアンカーとなります:それは被写体、カラーパレット、レイアウトを担い、プロンプトはシーンを一から説明するのではなく変換を記述します。ソース素材がなく、説明だけから 1 枚の画像を得たい場合は、テキストからの画像生成エンドポイントのほうがシンプルで、モデルにもより大きな自由度を与えられます。
2 つの実務的な影響が以下のすべてを決定づけます。第一に、リクエストはバイナリに近い入力(画像参照)を伴うため、リクエストボディの構築方法に影響します。第二に、画像生成は即時ではないため、このエンドポイントはインラインで画像を返すのではなく、非同期タスクとして動作します。「送信」と「取得」の 2 ステップを前提に設計し、1 回のブロッキング呼び出しとして扱わないでください。
前提条件と認証設定
最初のリクエストを送る前に、3 つのものが必要です:HiAPI アカウント、API キー、そしてエンドポイントが受け付ける参照元画像の指定方法です。HiAPI コンソールでキーを作成し、パスワードと同様に扱ってください——それはあなたのアカウントに課金されるすべての呼び出しを認可します。
キーは Authorization リクエストヘッダーでベアラートークンとして渡します。ソースファイル、ノートブック、コミット履歴にハードコードしないでください。シェルでのテスト用に環境変数としてエクスポートし、アプリケーションコードでは環境(またはシークレットマネージャー)から読み取ります:
export HIAPI_API_KEY="your_api_key_here"
参照画像をどう提供するかを事前に決めます。通常は、素材を一時的な場所にアップロードして URL を渡すか、リクエストボディで base64 エンコードしたデータとして画像を送信します。URL はリクエストを小さく保ち、記録しやすくします。base64 は別途ホスティングが不要ですが、リクエストボディが肥大化します。どちらを選んでも、ファイルはエンドポイントがサポートする形式に保ち、送信前にサイズ制限を確認してください。また、あなたのアカウントに対応する HiAPI API のベース URL も控えておきます——以下のすべてのパスはその前に付加されます。
curl で参照画像を送信する
まずシェルで始めれば、実際に何が送信されるかを正確に確認できます。呼び出しの形は画像からの画像生成エンドポイントへの POST で、JSON リクエストボディに参照画像と指示を含めます。
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
各フィールドの説明:model はエンドポイントを選択します。image は参照画像を運びます(ここでは URL。ファイルをホストしない場合は base64 データ文字列)。prompt は編集指示であり、被写体を再説明するのではなく変更内容を記述すべきです。n は生成したい出力数です。prompt は具体的かつ範囲を絞ってください——参照画像と矛盾する指示は混乱した結果を生みやすくなります。
リクエストを送信し、レスポンスボディを確認します。非同期エンドポイントでは完成した画像は返らず、タスク識別子またはステータスオブジェクトが返ります。続行する前にそのレスポンスを保存してください——それが以降のすべての操作のハンドルになります。curl -i で素早く確認すれば HTTP ステータスコードも見え、認証問題(送信時の 4xx)とコンテンツ問題を区別する最速の方法になります。
Python で同じ呼び出しを実行する
シェルでの呼び出しが成功したら、それを Python に移植します。標準ライブラリでも十分ですが、requests を使うとサンプルが読みやすくなります:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
curl との違いは機械的なものです:キーは os.environ から来て、リクエストボディは JSON にシリアライズされた dict であり、raise_for_status() は失敗した送信を黙殺せず例外に変えます。最後の行は重要です——デバッグの苦労の多くは、4xx レスポンスを成功とみなし、存在しなかったタスク ID をポーリングしてしまうことに起因します。
バイナリ入力の場合は、ファイルを読み込み、base64 エンコードし、その文字列を URL の代わりに image に入れます。リクエストボディの他の部分は変わらないため、リクエストロジックを変更せずに方式を切り替えられます。
非同期タスクのライフサイクルを扱う
画像生成には時間がかかるため、エンドポイントは「送信してからポーリング」というパターンに従います。3 つの状態を理解すれば、残りは記録作業です。
1. 送信してタスクを捕捉する
POST はタスク識別子を返します。それを直ちに抽出し、どこかに永続化します——データベースの行、キューメッセージ、クエリ可能なログ行などです。送信とポーリングの間でプロセスがクラッシュした場合、その識別子だけが支払い済みの作業を復元する唯一の手段です。
2. タスクが完了するまでポーリングする
タスク ID を使ってステータスエンドポイントを一定間隔でポーリングします。控えめに始め——チェックごとに数秒——長いタスクでは徐々にバックオフし、API を叩き続けないようにします。終端状態で停止します:成功、失敗、または自分で設定したタイムアウトです。タイトなループでポーリングしないでください。
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. 結果を取得して保存する
成功時、レスポンスは生成された画像を指します。URL が一時的な場合は速やかにダウンロードし、自分で管理できる名前で自身のストレージに書き込みます。そうすれば下流の利用者が一時リンクに依存することはありません。タスク ID は保存した素材と一緒に記録します——それが最も安価なデバッグ補助です。
本番環境では、ポーリングはリクエストハンドラーではなくバックグラウンドのワーカーが駆動すべきです。画像生成の全時間にわたってブロックする Web リクエストは脆弱で、接続を無駄に占有します。
よくあるエラーと修正方法
呼び出しが失敗したら、このリストを上から順に確認します。最初の項目でほとんどの問題を捕捉できます。
送信時の 401 / 403
認証の問題です。キーが Authorization リクエストヘッダーに存在するか、Bearer スキームを使用しているか、コピー&ペーストで余分な空白や改行が入っていないかを確認します。リクエストを実行するシェルやプロセスで環境変数が実際に設定されていることも確認します。
リクエストボディの 400 / 422
リクエストボディの形式が誤っているか、いずれかのフィールドが不正です。よくある原因:手書きの curl 文字列による JSON 構文エラー、image の値がアクセス可能な URL でも有効な base64 でもない、prompt の欠落、またはサポートされていない画像形式です。JSON をローカルで検証し、参照画像が実際にブラウザで読み込めることを確認します。
モデルまたはパスの 404
パスまたはモデル名の綴り誤りです。モデル識別子は正確な文字列です——gpt-image-2.6-sunburst/image-to-image はテキストからの画像生成の変種とは異なり、大文字と小文字も区別されます。
タイムアウトとポーリングのハング
遅いタスクと壊れたタスクを区別します。すべての HTTP 呼び出しに timeout を設定し、自分で全体の締め切りを設け、諦める際には最後に観測したタスク状態を記録します。タスクが締め切りを頻繁に超える場合は、タイトなリトライループに切り替えるのではなく、締め切りを延ばします。
出力が空または使えない
タスクは成功したが画像が意図したものではない場合です。これは通常プロンプトの問題です:指示が曖昧すぎるか、参照画像と矛盾しています。編集指示の中で、何を変えるべきか、何を変えてはならないかをより具体的に記述します。
画像からの画像生成パイプラインの本番環境への推奨事項
プロトタイプが動作したら、残る作業は信頼性と予測可能性です。
- リトライ可能なエラーだけをリトライする。 5xx やネットワークエラーによる送信失敗には指数バックオフでリトライします。4xx を盲目的にリトライしても再び失敗するだけです。タスクキーを自分のリクエスト ID に紐づけて冪等性を自分で追跡し、リトライが作業を重複させないようにします。
- 送信とポーリングを分離する。 送信とポーリングを別々のワーカーやステージに置きます。これにより API のレイテンシを生成時間から独立させ、ポーリングを独立してスケールできます。
- 自分のストレージを管理する。 タスク完了後すぐに結果を自分のバケットにダウンロードします。返された URL は一時的なリンクとして扱います。
- プロンプトをバージョン管理下に置く。 プロンプトは本番資産です。プロンプト、参照画像、タスク ID を各出力と一緒に保存し、数か月後に結果を再現または説明できるようにします。
- レイテンシとコストを監視する。 画像タスクは出力ごとに課金されるため、ユーザーごとの同時実行数を制限し、タスクごとに使用量を記録します。送信から素材保存までの p95 レイテンシを監視してください——それがユーザーが実際に体感する数値です。
リクエストの形とライフサイクルが確定すれば、残りは通常のエンジニアリングです。モデルの詳細は HiAPI のドキュメントで確認でき、そこからエンドポイントをあなたのパイプラインに組み込めます。