チュートリアル
HiAPI API 経由で gpt-image-2.6-flare/image-to-image を呼び出す方法:curl と Python
参照画像のアップロード、同期・非同期リクエスト、そして動作する呼び出しのデバッグ
このページの内容
このエンドポイントが行うこと、そして image-to-image を使うべき場面
テキストから画像を生成するモデルはゼロからシーンを創り出すのが得意ですが、多くの本番タスクは既存の画像から始まります。gpt-image-2.6-flare/image-to-image はまさにこうしたタスクのために HiAPI が提供するエンドポイントです。参照画像とプロンプトを送信すると、モデルは指示に従いつつ参照画像にしっかりと基づいた変換後の画像を返します。
代表的なユースケースは以下のとおりです:
- スタイル変換と再描画——商品画像をスタイライズされたイラストに変えたり、別の視覚言語で写真を再描画したりします。
- 編集とレタッチ——再撮影せずに、既存素材のライティング、背景、構図を調整します。
- バリエーション生成——ベースデザインから複数の視覚的バリエーションを生成し、A/B テストやクリエイティブな探索に使用します。
- 素材の適応——参照画像のサイズを変更したり、主要被写体を保ちながら再構図したりして、さまざまなチャネルに対応させます。
タスクが「何かを説明して画像を得る」ことであれば、テキストから画像を生成する方が簡単な選択です。出力が特定の入力画像に明確に由来する必要がある場合にのみ image-to-image を使うべきです——その参照画像こそがこの呼び出しの存在意義そのものです。この記事の残りの部分では、実際のリクエストをエンドツーエンドで構築します:まず curl で動作を証明し、次に Python で記述してサービスに組み込めるようにします。
前提条件とリクエスト構造
このエンドポイントを呼び出す前に、以下の条件が整っていることを確認してください:
- HiAPI アカウントと API キー。 キーは bearer token として
Authorizationリクエストヘッダーで送信します。ソースリポジトリにコミットせず、環境変数(例:HIAPI_API_KEY)から読み込んでください。 - モデル id。 厳密に
gpt-image-2.6-flare/image-to-imageを使用してください——モデル id は大文字小文字を区別し、スラッシュも識別子の一部です。 - エンドポイントパス。 画像生成は HiAPI API ホスト上の画像生成ルートにあります。古いコードスニペットで見かけたホストをハードコードするのではなく、モデルページで現在のベース URL とパスを確認してください。
- 参照画像ファイル、一般的な形式(PNG または JPEG が安全なデフォルトです)を使用します。サイズは妥当な範囲に保ってください。大きすぎるファイルはアップロードを遅らせ、リクエスト制限に引っかかる可能性があります。
gpt-image-2.6-flare/image-to-image リクエストは 3 つの重要な部分で構成されます:
- モデルセレクター——リクエストをどのモデルにルーティングするかを HiAPI に伝えます。
- プロンプト(prompt)——希望する変換効果を記述するテキスト指示です。これは任意ではありません。プロンプトこそが編集を導く鍵です。
- 参照画像——モデルが処理の基にする入力画像です。これをどう渡すかはリクエスト方法によって異なります(次のセクションを参照)。
それ以外には、そのモデルが HiAPI モデルページでドキュメント化しているパラメータのみを渡すべきです。フィールド名が「正しそうに見える」からといって勝手に作っていることに気づいたら、立ち止まってドキュメントを確認してください——未知のパラメータは紛らわしい 4xx エラーのよくある原因です。
参照画像の渡し方
概念的には、参照画像はリクエストボディ内のもう 1 つの入力フィールドにすぎません——しかしその大きさが特別な存在にしています。API にバイトを渡す実用的な方法は 2 つあり、この選択は API 自体よりもクライアントコードへの影響がはるかに大きくなります。
方式 A:リクエストボディにインラインで含める
小さな画像は JSON ペイロードに直接埋め込むことができ、通常は base64 エンコードされた文字列として扱います。ファイルを読み込み、エンコードし、その文字列をリクエストの image フィールドに入れます。すべてが 1 つのリクエストに収まり、サムネイル、アイコン、テストフィクスチャに最適です。
代償は次のとおりです:base64 はペイロードを約 3 分の 1 膨らませ、JSON エンコーダーは超長文字列を処理できない可能性があり、数メガバイトのリクエストボディをログでデバッグするのは非常に苦痛です。インラインは利便性のためであり、大きな素材には向きません。
方式 B:先にアップロードし、URL で参照する
小さな画像以外のすべてについては、まずファイルを自分が管理するストレージにアップロードし、その URL を参照として渡します。リクエストボディは小さく保たれ、リトライのコストが低く、同じ画像を毎回再アップロードすることなく複数の呼び出しで再利用できます。
URL を使用する際の注意点:
- URL は API から公開アクセス可能でなければなりません——認証の背後にあってはならず、localhost でもなく、リクエスト途中で失効する期限付き署名リンクでもありません。
- モデルが受け入れるコンテンツタイプを使用してください。URL が画像ではなく HTML を返す場合、検証は失敗します。
- 安定したファイル名を優先し、ストレージと HiAPI リクエストの間でログを関連付けられるようにしてください。
どちらの方式を選んでも、参照画像とプロンプトは同じリクエストで渡されます。API は別途「先にアップロードしてから生成」というハンドシェイクを要求しません——モデル呼び出しは単一の論理操作です。
同期呼び出しと非同期呼び出し
画像生成には時間がかかるため、多くの画像 API が同期方式に加えて非同期タスク方式も提供しています。ここでも同じトレードオフが当てはまります。
同期
リクエストを送信し、画像が返るまで接続を開いたままにします。コードは一直線です:リクエストを構築し、POST し、レスポンスを読み取り、完了です。
以下の場合に同期呼び出しを使用してください:
- プロトタイピングやデバッグ中で、1 ステップで完全な結果を見たい場合。
- リクエストがしばらくブロックしても許容される環境(CLI ツール、バックグラウンドワーカー)で実行される場合。
- ポーリングロジックを必要としない、可能な限りシンプルなクライアントが欲しい場合。
欠点は、生成に時間がかかると接続を長時間保持することになり、クライアントと API の間のプロキシやロードバランサーが独自のタイムアウトを課す可能性があることです。
非同期
リクエストをタスクとして送信し、すぐにタスク識別子を取得してから、タスクが完了するまでポーリング(またはコールバックを受信)します。クライアントには小さなステートマシンが必要です:送信、待機、結果取得、失敗処理。
以下の場合に非同期呼び出しを使用してください:
- ユーザー向けのトラフィックを処理しており、リクエストスレッドをブロックする余裕がない場合。
- 多数の画像を一括生成し、並列に分散して結果を収集したい場合。
- インフラストラクチャに自分で制御できない短いリクエストタイムアウトがある場合。
選択方法:Web リクエスト内で誰かが結果を待っている場合は非同期を使用してください。スクリプトやワーカーがオフラインで待機している場合は、同期の方がシンプルで問題ありません。過剰設計は避けてください:まず同期で始め、実際のタイムアウトや同時実行制限に迫られたときに非同期へ移行してください。
この記事の残りの部分では同期方式を使用します。各ステップが明確に見えるからですが、構築するリクエストボディは両モードで同じです——異なるのは周囲のパイプラインだけです。
動作する curl リクエスト
ターミナルからこの呼び出しを構築しましょう。まずキーを設定します:
export HIAPI_API_KEY="your-api-key-here"
ステップ 1:参照画像を準備する
小さく間違いようのない画像から始めると、失敗したときに原因が曖昧になりません:
ls -lh reference.png
file reference.png
file は PNG image data または JPEG image data を報告するはずです。それ以外を報告する場合は、先に修正してから進んでください。
ステップ 2:リクエストを送信する
リクエストは画像生成エンドポイントへの POST で、JSON ボディにモデル、プロンプト、参照画像が含まれます。選択したアップロード方式に応じて、image フィールドは URL または base64 文字列のいずれかになります。
curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png"
}'
パラメータについて:
-sSはプログレスバーを非表示にしますがエラーは表示します——スクリプトに適しています。Authorization: Bearer $HIAPI_API_KEYにより、キーがコマンド自体に現れません。$HIAPI_BASE_URLはモデルページで設定します。ホストを推測しないでください。- ここの
imageフィールドは URL 方式を使用しています。インライン画像の場合は base64 文字列に置き換えてください。
ステップ 3:レスポンスを読む
-i を追加してレスポンスヘッダーを含め、-w '\nHTTP %{http_code}\n' を追加してステータスコードを出力します。成功した呼び出しは画像(またはレスポンス形式に応じて画像へのリンク)とメタデータを返します。失敗時は 4xx または 5xx ステータスコードと JSON エラーボディが返ります——他の何かを変更する前に、まず message フィールドを読んでください。
ステップ 4:出力をファイルにパイプする
クリーンなファイルを得るには、stdout をファイルにリダイレクトし、再度 file で確認します。レスポンスが URL を含む JSON の場合は、その URL を抽出し、2 つ目の curl でダウンロードします。自動化に組み込む前に、ダウンロードしたバイトが実際に画像であることを必ず検証してください。
同じリクエストの Python 版
curl のベースラインは 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-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
レスポンスの処理
レスポンス形式はさまざまで、画像を直接含む場合も URL を含む場合もあります。両方のケースを統一する小さなヘルパー関数を書けば、下流のコードはどちらであるかを気にする必要がなくなります:
def extract_image(data):
if "url" in data:
return requests.get(data["url"], timeout=60).content
if "image" in data:
import base64
return base64.b64decode(data["image"])
raise ValueError(f"Unexpected response shape: {list(data)}")
エラーの処理
raise_for_status() を唯一のエラーパスにしないでください。呼び出しをラップし、API のエラーメッセージを公開します:
try:
response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
image_bytes = extract_image(response.json())
except requests.HTTPError as e:
print("HTTP", e.response.status_code, e.response.text)
raise
except requests.Timeout:
print("Request timed out; consider the async job route instead")
raise
非同期バリアント
非同期方式では、同じペイロードでタスクを送信し、レスポンスからタスク id を読み取り、試行間に短いスリープを挟んでタスク状態エンドポイントをポーリングします。ポーリング回数に上限を設け、予算の枯渇を失敗として扱ってください——リクエストハンドラー内で無限にポーリングしては決してなりません。
よくあるエラーのトラブルシューティング
ほとんどの失敗はいくつかのカテゴリに分類されます。このチェックリストを順に確認してください。各ステップで 1 つの変数を切り分けます。
認証エラー(401 / 403)
HIAPI_API_KEYは本当にシェルやプロセスに設定されていますか?echo $HIAPI_API_KEYで出力されるはずです。- ヘッダーは正確に
Authorization: Bearer <key>ですか——大文字の A、大文字の B、スペース 1 つ? - キーは取り消しまたはローテーションされていませんか?再生成して、最小限のリクエストで再試行してください。
無効な参照画像ペイロード
これが最もよくある失敗で、通常はモデルのせいではありません:
- URL に到達できない:別のネットワークのブラウザで画像 URL を開いてください。404 になったりログインページにリダイレクトされたりする場合、API もそれにアクセスできません。
- コンテンツタイプが間違っている:HTML や JSON を返す URL は拒否されます。
curl -I <url>でレスポンスがContent-Type: image/...であることを確認してください。 - ファイルが破損しているか読み取れない:ローカルで
file reference.pngを実行してください。base64 文字列がデコード後に元ファイルと同一のバイトになることを検証してください。 - ファイルが大きすぎる:モデルページに記載されたサイズ制限を確認し、再試行前にサイズを縮小してください。
パラメータ形式のエラー
- モデル id の綴り間違い:
gpt-image-2.6-flare/image-to-imageはスラッシュを含めて完全に一致する必要があります。 - プロンプトの欠落:テキスト指示は必須で、省略できません。
- 余分なフィールド:ドキュメントで見つからないパラメータは削除してください。未知のキーはしばしば 4xx を引き起こします。
- JSON 構文:送信前に
jq . <<< "$BODY"でリクエストボディを検証してください。
タイムアウト
画像が返る前にリクエストが中断される場合、接続を保持しすぎています。プロンプトを短くし、参照画像を小さくし、クライアントのタイムアウトを延ばしてください。問題が続く場合は非同期タスク方式に切り替えてください——長時間の生成こそが非同期の出番です。
デバッグ戦略
各試行で変えるのは 1 つだけにしてください。非常に小さく間違いようのない参照画像と 1 つのプロンプトから始め、パイプラインが動作することを証明してから、実際の入力を徐々に導入します。失敗のたびにレスポンスボディ全体をログに記録してください。message フィールドは通常、リクエストのどこが間違っているかを直接示します。
パイプラインへの組み込み
ベースラインが動作したら、いくつかの習慣を身につけることで gpt-image-2.6-flare/image-to-image を本番環境で信頼性高く保てます。
呼び出し前に入力を検証する。参照画像がサポートされている形式でサイズ制限内にあるか、URL の場合は到達可能かを確認してください。失敗したラウンドトリップに料金を払うのではなく、自分の境界で不良入力を拒否してください。
呼び出し後に出力を検証する。レスポンスに本物の画像バイト(マジックナンバーを確認)が含まれており、紛れ込んだ HTML エラーページでないことを確認してください。安価なヘッダーチェックが下流の多くの紛らわしいデバッグを節約します。
バックオフ付きリトライを使うが、正しいエラーにのみ。一時的な 5xx とネットワークタイムアウトは指数バックオフとジッターでリトライする価値があります。不良パラメータによる 4xx エラーは毎回まったく同じように失敗するため、リトライするのではなくリクエストを修正してください。
ユーザー向けの作業では非同期を優先する。ページ上で誰かが待っている場合、タスクを送信してクライアントからポーリングしてください——長時間の生成のために Web リクエストを開いたままにしないでください。
モデル id を設定に保存する。モデル id は時間とともに変化します。単一の設定ポイントから読み込むことで、モデル変更がグローバル検索置換ではなく 1 行の変更で済みます。
他の HiAPI モデルと組み合わせる。このエンドポイントはテキストから画像生成と自然に組み合わせて、ハイブリッドフロー(まずベース画像を生成し、それを編集する)を構成できます。パイプラインが必要とする場合は、アップスケールや背景除去のステップとも組み合わせられます。すべてが同じ HiAPI インターフェースと認証を通るため、ステップを追加するのは同じキーで再度呼び出すだけです。
curl のベースラインから始め、Python に移植し、トラフィックが要求するときに非同期へ移行してください。モデルページには現在のリクエストパラメータと制限が記載されています——フィールド名やサイズ上限を仮定する前に、そこを確認してください。