Gemini画像生成APIプロキシの使い方

Gemini画像生成APIプロキシは、アプリケーションとGeminiの画像モデルの間に入るAPIゲートウェイです。 利用には、画像を出力できるモデルID、プロキシのリクエスト形式、生成画像の取得方法を確認する必要があります。テキスト用クライアントのベースURLを変更しただけでは、画像生成への対応は確認できません。

OmniaKeyの公開仕様では、POST /v1/media/tasks でタスクを作成 → 状態をポーリング → 画像をダウンロードします。この手順を実装しながら、GoogleのネイティブAPIやOpenAI互換APIとの違いを整理します。

必要なのはどの種類のプロキシですか？

ここで扱うのは、モデルへのリクエスト、認証、レスポンスを処理するAPIサービスです。ネットワークプロキシは通信を中継しますが、それだけで画像APIの形式を変換するわけではありません。接続先が公開している仕様で判断してください。

Googleの現在の画像生成ガイドは Interactions API の例を掲載しています。GenerateContentリファレンスは別の仕様です。入力フィールドやレスポンスの読み取り方法を混在させたり、プロキシが両方に対応すると決めつけたりしないでください。

画像認識と画像生成も別です。画像を読み取って説明できるモデルでも、出力はテキストだけの場合があります。テキストの呼び出し成功は、画像生成・編集の動作確認にはなりません。「OpenAI互換」という表記だけで、すべてのSDKメソッドが使えるとも判断できません。

画像モデルのIDを指定する

Googleのモデル案内では、次のモデルを区別しています。

• Nano Banana 2.1： gemini-nano-banana-2.1。新しい汎用画像ワークフローでGoogleが推奨する出発点です。
• Nano Banana Pro： gemini-3-pro-image。より複雑な視覚タスクを検討するための別モデルです。
• Nano Banana 2： gemini-3.1-flash-image。前世代であり、2.1の別名ではありません。

呼び出すサービスから正確なIDをコピーし、権限、生成・編集への対応、サイズ、課金単位を確認します。OmniaKeyの2.1では parameters.aspect_ratio と parameters.image_size を使い、1K、2K、4K を指定できます。Googleの imageConfig やGPT Imageの size、quality をそのまま流用することはできません。

現在の掲載情報は Nano Banana 2.1のモデルページ、モデル選びは 2.1とProの比較で確認できます。

OmniaKeyで画像を生成する

Bash、cURL、jqを用意し、OmniaKeyのキーをローカルの OMNIAKEY_API_KEY 環境変数に設定します。バックエンドか開発用端末で実行し、キーをブラウザーのコードに含めないでください。サンプルの英語プロンプトは、まずAPIの動作を確認できるよう単純にしています。

1. タスクを作成して保存する

画像リクエストごとに固有の Idempotency-Key を決めます。例の値はデモ用です。新しいタスクを作る際に変更し、同じタスクの再試行ではキーと本文を変えません。送信前に両方をアプリケーションで保存してください。

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

cURLが成功し、task.json に id があることを確認してから進みます。新規作成は 202 Accepted、同じキーと本文の再送は元のタスクを 200 で返します。受付完了と画像生成完了は別です。詳細はタスクのライフサイクル（英語）を参照してください。

2. 保存したIDをポーリングする

次のBash例は確認回数に上限を設けています。上限に達してもIDは残るため、後で同じタスクを確認できます。タスクのキャンセルや再作成は行いません。

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

作成時にタイムアウトしてIDを受け取れなかった場合は、同じ本文と冪等性キーで再送します。IDがあれば、そのタスクを取得してください。新しいキーを使うと別の課金対象タスクができる可能性があります。復旧には保存期間の制約があり、タスク記録は作成から24時間保持されます。

3. 成功した結果だけをダウンロードする

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

アセットの mime_type に合わせて拡張子を付け、画像が開けることと実際のサイズを確認します。署名付きURLには期限があります。タスクとアセットが有効な間は、再取得で新しいURLを得られます。長期保存が必要な画像はダウンロードしてください。

参照画像を使って編集する

operation: "edit" を指定し、input.image にBase64形式の画像を渡します。複数の参照画像に対応するモデルでは input.images を使います。編集指示は input.prompt に入れます。完全な形式は画像APIドキュメント（英語）にあります。

タスクAPIの上限は、Base64を含むリクエスト本文全体で1 MiBです。必要に応じて参照画像を圧縮・縮小します。Googleの直接接続用アップロード上限を、プロキシにも適用できるとは限りません。まず小さな画像1枚で変更を試し、残すべき部分が保たれているか確認してください。

プロンプト、画像、モデル、パラメータの変更は新しいリクエストです。新しい冪等性キーを使います。同じキーで本文を変えると 409 idempotency_key_reused になります。

エラーが発生した層を切り分ける

GoogleのトラブルシューティングはGoogle側の動作を説明しています。プロキシには独自の層があるため、HTTPステータス、エラーコード、タスクID、所要時間を機密情報を除いて記録します。キーや非公開の参照画像はログに残しません。200 のJSONだけでは画像の成功を判定できません。

コストと動作を確認する

Googleの直接課金とプロキシの料金は別です。大量に実行する前に OmniaKeyの最新料金とモデルの課金単位を確認します。画像出力にテキストのトークン単価を当てはめたり、個人向けGeminiサブスクリプションでプロキシ利用料が賄えると考えたりしないでください。

比較には 課金総額 ÷ 採用できた画像数を使います。課金された再試行や、生成後の確認で不採用になった画像も含めます。これは計画用の式であり、実測値や最安値の保証ではありません。

利用量を増やす前に、次の5項目を小規模に検証します。

1. テキストから画像を生成し、形式・サイズ・表示を確認する。
2. 参照画像の編集が指示を反映し、必要な細部を保つか確認する。
3. 同じキーと本文の再送で、同じタスクIDが返るか確認する。
4. ローカルの待機終了後も、同じIDで再開できるか確認する。
5. 無効なパラメータや利用できないモデルが、明確なエラーになるか確認する。

モデルID、パラメータ、所要時間、最終状態、課金、採否を記録してください。実務の素材を送る前に、プロンプトと参照画像の取り扱い条件も確認します。

よくある質問

既存SDKのベースURLだけ変えれば使えますか？

SDKが必要とするエンドポイント、フィールド、画像レスポンスをプロキシが明示的にサポートする場合に限ります。テキストだけでなく、画像操作そのものを確認してください。

プロキシを使えばGeminiの制限はなくなりますか？

なくなりません。提供元、モデル、プロキシ、アカウントそれぞれの制約が適用される場合があります。無制限の生成や地域での利用を保証するものではありません。

最初にどのモデルを使うべきですか？

現在のカタログで対応モデルを確認し、小さなタスクで評価します。モデルの変更点は Nano Banana 2.1ガイドにまとめています。本記事は接続と動作確認が中心です。

参考資料と次のステップ

主な資料はGoogleの画像生成ガイド、GenerateContentリファレンス、エラー対策、および本文のOmniaKeyドキュメントです。これらのリンク先は英語です。仕様確認日は 2026年10月14日です。実行前にモデル権限を確認してください。