nano banana pro api image config no size parameter ja image 0 图示

Nano Banana Proのモデル呼び出しにおける注意点：imageConfigで解像度を決定し、sizeパラメータは追加しないこと

by

多くの開発者が Nano Banana Pro API（Google gemini-3-pro-image-preview モデルに対応）を初めて呼び出す際、共通の落とし穴にはまります。それは、OpenAI / DALL-E 時代の size: "1024x1024" パラメータをそのまま流用してしまうことです。その結果、生成画像の解像度が全く変わらなかったり、400エラーが直接返されたり、あるいはサーバー側でパラメータが黙殺されたりします。

これは Nano Banana Pro API の呼び出しにおいて最も「高頻度なバグ」です。正しい方法は、解像度を imageConfig.imageSize（鮮明度 1K/2K/4K）と imageConfig.aspectRatio（サイズ比 1:1/16:9/…）という2つのパラメータで決定することであり、size フィールドは一切送信しないことです。 本記事では、この件について詳しく解説し、そのままコピー＆ペーストして実行できる curl / Python / Node.js のコードを提供します。

nano-banana-pro-api-image-config-no-size-parameter-ja 图示

Nano Banana Pro API 呼び出しの核心ポイント

コードを貼り付ける前に、以下の3つの鉄則を覚えておいてください。これらを理解すれば、本記事の90%の内容は単なる詳細に過ぎません。

  1. モデル名の対応: Nano Banana Pro = gemini-3-pro-image-preview（Gemini 3 Pro Imageとも呼ばれます）。Google Gemini 3 シリーズの画像生成/編集モデルに属します。市場では Nano Banana 2 と呼ばれることもありますが、本質的には同じものです。
  2. プロトコルは Gemini ネイティブ: OpenAI Chat Completions 互換プロトコルではありません。リクエストパスは :generateContent であり、リクエストボディのトップレベルフィールドは contents + generationConfig です。messages も OpenAI スタイルの size フィールドも存在しません。
  3. 解像度 = imageSize × aspectRatio: imageSize は鮮明度（512 / 1K / 2K / 4K）を制御し、aspectRatio は画角（1:1 / 16:9 / 9:16 / …）を制御します。この2つを組み合わせて最終的な出力ピクセル数が決まります。

📌 一言でまとめると: Gemini プロトコルで Nano Banana Pro を呼び出す際は、OpenAI 流の size: "1024x1024" という習慣を完全に忘れてください。APIYI (apiyi.com) の Nano Banana Pro エンドポイントは Gemini ネイティブプロトコルを完全に保持しており、Google 公式で有効な imageConfig の書き方はすべて APIYI でも有効です。

Nano Banana Pro 主要パラメータ一覧

パラメータ 位置 役割 設定例
imageSize generationConfig.imageConfig 鮮明度 "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig 画角 "1:1" / "16:9" / "9:16" / "4:3" など
responseModalities generationConfig 出力モダリティ ["IMAGE"]（必須）
contents[].parts[].text contents テキストプロンプト 自由テキスト
contents[].parts[].inline_data contents 入力画像(base64) mime_type と data を含む

⚠️ 表にない size フィールドについて: これは Gemini プロトコルにおいて有効なパラメータではないため、送信しないでください。

なぜ size パラメータを追加してはいけないのか？プロトコル層の理由

これは本記事で最も重要なセクションです。3つの側面からこの問題を徹底的に解説します。

プロトコル層：Gemini と OpenAI は独立した別々の仕様

OpenAI の画像生成 API（DALL-E 2/3、gpt-image-1）は、トップレベルの size: "1024x1024" という文字列パラメータを使用します。一方、Google Gemini 3 の画像 API は、ネストされた imageConfig オブジェクトを設計しており、両者の仕様は完全に独立しています。Nano Banana Pro は Gemini のネイティブプロトコルを採用しているため、以下のようになります。

  • ❌ size: "1024x1024" —— Gemini プロトコルにはこのフィールドは存在しません
  • ❌ size: "1K" —— このフィールドは存在しません
  • ❌ n: 4 —— OpenAI のような「一度に N 枚生成する」フィールドはありません
  • ✅ imageConfig.imageSize: "1K" —— 正解
  • ✅ imageConfig.aspectRatio: "16:9" —— 正解

動作層：size を余分に送るとどうなるか？

サーバー側の処理は通常3つのケースに分かれますが、どれも望ましい結果にはなりません。

  1. 黙って無視される：上位ゲートウェイが未知のフィールドを無効なものとして破棄します。あなたは設定が反映されたと思い込みますが、実際にはデフォルトの 1K 1:1 で出力されます。
  2. 400 エラーを返す：厳格なスキーマ検証を行うゲートウェイの場合、未知のフィールドがあることでリクエスト自体が拒否されます。
  3. 課金やルーティングへの影響：一部のプロキシ層が size をルーティングのシグナルと誤認し、誤ったエンドポイントバージョンに振り分けられる可能性があります。

エンジニアリング層：メンテナンスの混乱と技術的負債

多くのチームが OpenAI、Gemini、Stability などの複数の API を同一の呼び出し層にカプセル化しており、「汎用的な size フィールド」を使い回す癖がついています。これは一見エレガントに見えますが、実際にはバグの温床です。Nano Banana Pro のような Gemini ネイティブインターフェースを呼び出す際は、個別の変換リンクを設けることを推奨します。生の size をそのまま渡すのではなく、imageConfig.imageSize + imageConfig.aspectRatio に明示的にマッピングするようにしてください。

💡 アドバイス：APIYI (apiyi.com) を通じて Nano Banana Pro を呼び出す際は、小さなパラメータ変換関数を作成し、チームで慣れ親しんだ "1024x1024" のような文字列を imageSize: "1K" + aspectRatio: "1:1" に分解することで、混在によるエラーを根本から防ぎましょう。

imageSize × aspectRatio 完全対照表

nano-banana-pro-api-image-config-no-size-parameter-ja 图示

imageSize の段階と課金

imageSize およその解像度上限 出力トークン 単価(参考) 推奨シーン
"512" 512×512 程度 低め 最安 サムネイル / 下書き
"1K" 1024×1024 程度 ~1120 ≈ $0.134 標準推奨
"2K" 2048×2048 程度 ~1120 ≈ $0.134 高精細ポスター
"4K" 4096×4096 程度 ~2000 ≈ $0.24（約80%高） 印刷用

💰 コストのヒント：4K は 1K/2K よりも約 80% 高価です。無計画にすべてを 4K に設定しないようにしましょう。ほとんどの Web/App シーンでは 1K で十分であり、超高精細が必要な場合のみ 4K を使用してください。最新の単価については APIYI (apiyi.com) の公式サイトの料金表をご確認ください。

aspectRatio の完全サポートリスト

比率 用途
"1:1" アイコン / SNS用正方形
"16:9" 横長動画サムネイル / デスクトップ壁紙
"9:16" 縦長ショート動画 / スマホ壁紙
"4:3" 伝統的な横長写真
"3:4" 伝統的な縦長写真
"3:2" / "2:3" DSLR 標準比率
"4:5" / "5:4" Instagram 用画像
"21:9" 超横長シネマティック
"1:4" / "4:1" 長尺バナー
"1:8" / "8:1" 極端な長尺特殊用途

一般的な組み合わせ → 最終的なピクセルマッピング

imageSize aspectRatio およその出力ピクセル
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

注：実際のピクセル数は、モデル内部の調整ルールにより ±N ピクセルの微調整が入る場合がありますが、視覚的な鮮明度には影響しません。

Nano Banana Pro API の正しい呼び出しコード

ここでは、3つのプログラミング言語による最小限の実行可能なサンプルを紹介します。いずれのサンプルも「元画像1枚 ＋ プロンプト」を入力し、1K 1:1 の比率で画像を1枚出力する処理を行います。

curl バージョン（最も直感的で、デバッグに便利）

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer あなたの-APIYI-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(元画像のbase64)"
          }
        },
        {
          "text": "この画像をサイバーパンク風に変えて、人物のポーズは維持してください"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Python バージョン（SDKに依存せず、requestsの使用を推奨）

import base64
import requests

# 画像を読み込んでbase64エンコード
with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer あなたの-APIYI-KEY",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "この画像をサイバーパンク風に変えて、人物のポーズは維持してください"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Node.js バージョン（ネイティブ fetch を使用し、imageConfig の欠落を回避）

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer あなたの-APIYI-KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "この画像をサイバーパンク風に変えて、人物のポーズは維持してください" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 なぜネイティブ fetch / requests を強く推奨するのか：一部のSDK（初期のLiteLLMやGoogle Node SDKの特定バージョンを含む）では、imageConfig を未知のフィールドとしてフィルタリングしてしまい、imageSizeやaspectRatioが完全に無効になることが知られています。JSONリクエストボディを直接構築すれば、この問題を100%回避できます。どうしてもSDKを使用する場合は、必ず最新バージョンに更新し、リクエストインターセプターで最終的なボディを出力して確認してください。

呼び出し時の注意点：よくある6つのエラー

nano-banana-pro-api-image-config-no-size-parameter-ja 图示

落とし穴 1：OpenAI形式の size パラメータを余分に送信する

// ❌ エラー：size は Gemini プロトコルの有効なフィールドではありません
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ 正解：size を削除し、imageConfig のみ保持します
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

落とし穴 2：フィールド名の綴りミス（スネークケースの使用）

Gemini 3 画像生成インターフェースの imageConfig フィールド名は キャメルケース です：imageSize、aspectRatio、responseModalities。よくある間違い：

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

落とし穴 3：imageConfig が SDK によって黙って削除される

前述の通り、一部のSDKバージョンは未知のフィールドをフィルタリングします。トラブルシューティング方法：

  1. SDK呼び出しの前後に実際の HTTP ボディを出力する
  2. mitmproxy / Charles を使用して、実際の送信リクエストをキャプチャする
  3. imageConfig が消えている場合は、ネイティブ fetch / requests に切り替える

落とし穴 4：responseModalities の指定忘れ

// ❌ responseModalities を設定しないと、画像ではなくテキストが返される可能性があります
{ "generationConfig": { "imageConfig": {...} } }

// ✅ 返却形式に IMAGE が含まれることを明示する必要があります
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

落とし穴 5：429 レート制限に対する指数バックオフの欠如

上流の負荷が飽和している場合、以下のようなエラーが返されます：

{ "error": { "message": "現在、グループの上流負荷が飽和しています。しばらくしてから再試行してください", "type": "upstream_error", "code": 429 } }

正しい対処法は指数バックオフによる再試行（3秒 → 6秒 → 12秒）です。即座に再試行すると、かえって混雑を悪化させます：

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3秒, 6秒, 12秒

落とし穴 6：複数の参照画像の配置ミス

Nano Banana Pro はマルチ画像入力（元画像 ＋ 複数の参照画像）をサポートしています。すべての画像は parts 配列内の 複数の inline_data アイテム として配置し、テキストプロンプトは配列の最後に配置する必要があります：

// ✅ 正解：画像が先、テキストが後
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "元画像のbase64" } },
  { "inline_data": { "mime_type": "image/png", "data": "参照画像1のbase64" } },
  { "inline_data": { "mime_type": "image/png", "data": "参照画像2のbase64" } },
  { "text": "元画像のスタイルを参照画像1の色調に合わせ、構図は参照画像2を参考にしてください" }
]

🧰 まとめ：上記の6項目を社内の「Nano Banana Pro チェックリスト」として活用してください。新しい呼び出しを実装する前に確認することで、低レベルなバグの90%以上を防ぐことができます。APIYI apiyi.com の Nano Banana Pro エンドポイントは Gemini プロトコルを完全に踏襲しているため、これらのテクニックはすべて共通して使用可能です。

ユーザー呼び出しフローの分解：どこでエラーが発生しやすいか

nano-banana-pro-api-image-config-no-size-parameter-ja 图示

多くの読者から共有いただいた呼び出しログは、私たちが提示したフローとほぼ一致しています：

フロントエンド POST /api/generate
  → server.js パラメータ抽出
  → modelKey.startsWith('nano-banana') か判定
  → _generateViaGemini() リクエストボディの組み立て
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → 返却 / 再試行

各ノードで最もエラーが発生しやすい箇所を特定しました：

箇所 よくある問題 推奨事項
フロントエンドパラメータ 習慣的に size: "1024x1024" を送信 imageSize + aspectRatio の2フィールドに分けて送信
server.js ボディ組み立て size フィールドを誤ってGeminiに転送 組み立て関数内で size を明示的に削除
モデルルーティング nano-banana を 1.5 ではなく 3 Pro にルーティング モデル名を gemini-3-pro-image-preview と正確に記述
リクエスト送信 スキーマ検証付きのSDKバージョンを使用 ネイティブ fetch に変更、またはSDKを最新版に更新
エラー処理 429エラーをそのままユーザーに表示 指数バックオフで3回再試行
レスポンス解析 text で取得しようとして画像が返る 正しいパス candidates[0].content.parts[0].inline_data.data を使用

📋 一言で言うと：提示されたフロー構造は正しいです。「パラメータ抽出」段階で余計な size フィールドを取り除き、server.js がそれを generationConfig 以外に再挿入しないことを確認すれば、通信経路はクリーンになります。

FAQ よくある質問

Q1: Nano Banana Pro と Nano Banana 2 は同じものですか？
はい。コミュニティでは Gemini 3 Pro Image (gemini-3-pro-image-preview) を Nano Banana 2 / Nano Banana Pro と呼ぶことがありますが、これら3つの呼び方はすべて同じモデルを指します。APIYI (apiyi.com) 上のモデル名は公式ドキュメントに準拠してください。

Q2: imageConfig を渡さないとどうなりますか？
モデルは内部のデフォルト値（通常は 1K + 1:1）で出力します。解像度にこだわらない場合は省略可能ですが、画角を指定したい場合は imageConfig を明示的に渡す必要があります。

Q3: Gemini プロトコルを使いつつ、OpenAI のように size を渡すことはできますか？
確実ではありません。Gemini プロトコルには size フィールドが存在しないため、混在させると予期せぬ動作を引き起こします。imageConfig.imageSize + imageConfig.aspectRatio を使用するのが最も安全です。

Q4: imageSize で 4K を選べば画質は必ず良くなりますか？
画質の詳細は豊かになりますが、コストが約2倍（~$0.24 vs $0.134）になり、生成時間も長くなります。Web/App 用の画像であれば 1K または 2K で十分な場合が多いです。実際の業務画像でテストを行い、目視で比較してから決定することをお勧めします。

Q5: APIYI (apiyi.com) 経由で Nano Banana Pro を呼び出すのと、Google 公式 API を直接呼び出すのとで違いはありますか？
APIYI は、OpenAI スタイルの統一認証（Bearer Token）+ 国内からのアクセス可能なゲートウェイ + 統一課金を提供しており、呼び出しプロトコル自体は Gemini のネイティブ形式を完全に踏襲しています。つまり、Google 公式ドキュメントにある imageConfig / aspectRatio / responseModalities は、APIYI (apiyi.com) 上でも完全に同等に機能します。

Q6: imageSize: "2K" に設定したのに 1K で出力されるのはなぜですか？
よくある3つの原因：(1) 未知のフィールドを除外するSDKを使用している、(2) フィールド名が image_size になっている、(3) generationConfig のネスト階層が間違っている。実際の通信パケットをキャプチャしてボディが仕様に合致しているか確認してから、サーバーサイドを調査してください。

Q7: 上流の 429 レート制限にどう対処すればいいですか？
指数バックオフによる再試行（3秒/6秒/12秒）を行ってください。業務上遅延に敏感な場合は、APIYI (apiyi.com) のワークスペースで異なるグループに切り替えるか、個別のクォータを申請してください。無限ループで即時再試行を行うと、制限ポリシーにより継続的にブロックされるため、絶対に行わないでください。

Q8: マルチモーダル入力に枚数制限はありますか？
Gemini 3 image インターフェースでは、1回のリクエストあたりの合計画像サイズに制限があります（通常はMB単位、詳細は公式に準拠）。参照画像は4〜5枚以内とし、各画像を適切なサイズに抑える（先にリサイズしてから base64 化する）ことを推奨します。そうしないと 413 エラーやタイムアウトが発生します。

まとめ：「解像度2パラメータ法」を筋肉に刻み込む

もし一つだけ覚えて帰るなら、これです：

Nano Banana Pro の最終出力解像度 = imageConfig.imageSize × imageConfig.aspectRatio です。OpenAI スタイルの size フィールドは一切渡さないでください。

完全なチェックリスト：

  • ✅ モデル名：gemini-3-pro-image-preview
  • ✅ エンドポイント：/v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities には必ず "IMAGE" を含めること
  • ✅ 複数画像の入力は parts 配列に入れ、テキストプロンプトは最後に配置する
  • ✅ 429 エラー（レート制限）時は指数バックオフ（3秒/6秒/12秒）を実行する
  • ❌ size: "1024x1024" は渡さない
  • ❌ image_size / aspect_ratio と書かない（スネークケースは間違いです）
  • ❌ 未知のフィールドをフィルタリングしてくれる古い SDK を過信せず、まずはパケットキャプチャで確認する

📢 最後に：APIYI (apiyi.com) を通じて Nano Banana Pro に接続している場合は、本記事で提供している curl / Python / Node.js のコードテンプレートをそのままコピーしてください。すべてのパラメータは Gemini のネイティブプロトコルに厳密に準拠しています。コピー＆ペースト → キーを変更 → 実行、で完了です。

著者：APIYI Team · AI 大規模言語モデル API 呼び出しのベストプラクティスを継続的に整理中 · apiyi.com

コメントする