Nano Banana API ガイド：HiAPI で nano-banana、nano-banana-2、nano-banana-pro を呼び出す

Nano Banana モデルファミリーが提供できるもの

画像生成がひとつの設定だけで完結することはほとんどありません。プロジェクトの初期にはアイデアを探るための素早いドラフトが必要で、後期には納品のための精巧なレンダリングが必要になります。HiAPI 上の Nano Banana ファミリーは、まさにこの現実を中心に構築されています。ひとつのインターフェース、三つのバリアント、それぞれが品質と速度の曲線上の異なる位置に最適化されています。

命名は意図的なものです。nano-banana は基本オプションです——プロンプトやレイアウトを形作っている段階で、まだ素早い視覚的フィードバックが必要なときに使います。nano-banana-2 は忠実度とプロンプトへの追従性をさらに一歩進めたもので、出力がほぼ最終に近いものの、まだ反復を続けたいときの選択肢となることが多いです。nano-banana-pro はこのファミリーの中で最も忠実度が高いバリアントで、細部と構図が最も重要な最終レンダリングに適しています。

共有している部分は、異なる部分と同じくらい重要です。三つとも同じ HiAPI エンドポイントを通じて呼び出されます。認証は一度だけ、リクエストの構築も一度だけで済み、切り替え時にはモデル識別子を変えるだけです。つまり、アプリケーションは基本モデルでリクエストを開始し、その後により強力なバリアントで同じプロンプトを再実行できますが、トランスポート層のコードを変更する必要はありません。

このようなファミリー構成はアーキテクチャもシンプルに保ちます。品質階層ごとに個別のプロバイダーを接続するのではなく、単一のクライアント、単一のエラーハンドリング経路、単一の使用量観測点を保てばよいのです。モデルの選択はパラメータのひとつとなり、統合作業ではなくなります。

なぜ単一モデルではなくファミリーなのか

ワークフロー内の各ステップには異なる要件があります。プロンプトの探索、レイアウトのドラフト、クライアントプレビューは速度を重視し、キービジュアルやマーケティング素材は忠実度を重視します。モデル選択を実行時の判断とみなすことで、パイプラインを再構築することなく、各ステップに適切なバリアントを割り当てられます。

nano-banana、nano-banana-2、nano-banana-pro の選択

バリアントを選ぶには二つの質問をします。この出力は最終版にどれだけ近いか、そこに到達するまで何回の試行が必要か。残りの問題はこれによって決まります。

nano-banana：バッチ処理と探索向け

画像がどうあるべきかをまだ決めかねているときに基本モデルを使います。プロンプトの書き換え、スタイルのテスト、レイアウトのサムネイルは素早いターンアラウンドの恩恵を受け、粗いレンダリングでも説明文よりもあなたの疑問に答えてくれることがよくあります。開発期間中はこれをデフォルトとしておきましょう。

nano-banana-2：最終に近い反復向け

構図が固まり、細部——間隔、被写体の忠実度、出力がプロンプトにどれだけ厳密に従うか——を微調整しているときは nano-banana-2 に切り替えます。これは実用的な中間の選択肢です。プレビューのたびに最高忠実度の経路を通すことなく、追従性が明らかに強くなります。

nano-banana-pro：最終レンダリング向け

nano-banana-pro は納品する出力のために取っておきます。キービジュアル、製品画像、クライアントが注意深く確認するあらゆるコンテンツは、より強力なバリアントを使う価値があります。これをデフォルトにしないでください——最後のステップのために残し、探索的な反復を低コストに保ちましょう。

実用的なルーティングルール

シンプルなエスカレーション戦略がほとんどのチームに当てはまります：

• すべての新しいプロンプトはデフォルトで nano-banana を使う。
• 構造は正しいが品質が足りない場合、プロンプトを nano-banana-2 にエスカレーションする。
• プロンプトが確定したら、最終版を nano-banana-pro で一度だけ実行する。

これにより反復が速く予測可能になり、使用量のパターンも把握しやすくなります。課金は使用量に連動し、バリアントによって異なるため、いかなる数値もコードにハードコードするのではなく、リアルタイムのモデルドキュメントで現在の料金と制限を確認してください。

バリアント間で共通のプロンプトパターン

最も高くつく行為は、ひとつのモデルでしか通用しないプロンプトを書くことです。一行の変更で切り替えられる構造にしましょう。

四ブロック式プロンプト

すべてのプロンプトを、次の順序で四つのラベル付きセクションとして書きます：

1. 主体——画像に何があるか、簡潔に述べる。
2. スタイル——写真、イラスト、水彩、3D レンダリングなどの視覚的処理方法。
3. 構図——フレーミング、カメラアングル、配置、ネガティブスペース。
4. 制約——避けるべきもの、およびあらゆる厳格な要件。

記入済みの例：

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

各ブロックが独立しているため、プロンプト全体を書き直すことなくスタイルを強化したり構図を緩めたりできます。しかも同じ構造はこのファミリーのどのバリアントにも理解されやすいものです。

プロンプトをモデル非依存にする

特定のモデルの特性を前提とした言い回しは避けましょう。具体的なモデルが取るべき手順ではなく、望む結果を記述します。バリアントを比較する必要があるときは、モデル ID だけを変え、プロンプトはバイト単位で同一に保つことで、比較が意味を持ちます。

コードのようにプロンプトをバージョン管理する

プロンプトは設定ファイルや小さなプロンプトライブラリに文字列として保存し、名前とバージョンで索引付けします。あるバリアントで微調整により良い出力が得られたら、その変更を記録します。これこそが、プロンプトが納品時に nano-banana から nano-banana-pro へと事故なく移行できる理由です。

ネガティブ制約が重要

あるプロンプトが文字、ロゴ、不要なオブジェクトを繰り返し生成する場合は、それらを制約ブロックに明示的に加えます。バリアント間では、明確なネガティブ制約の方が巧妙な言い回しよりも信頼できることがよくあります。

HiAPI 上で動作するリクエストを構築する

すべてのバリアントは同じ HiAPI エンドポイントを通じて呼び出されます。リクエストには四つの可変部分があります：ベース URL、認証ヘッダー、モデルフィールド、ペイロードです。

リクエストの形

最小限の画像生成呼び出しは次のようになります：

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

API キーは環境変数またはシークレットマネージャーに保管してください——決してソースコードに置かないでください。model フィールドはバリアントを切り替えるときに変更する唯一のもので、prompt フィールドは前節の四ブロック構造を担います。

Python では、同じ呼び出しは数行で済みます：

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

レスポンスに含まれるもの

レスポンスには画像の結果——通常は URL またはエンコードされたペイロード——と、そのリクエストを処理したモデルを識別するメタデータが含まれます。モデルフィールドを読み戻して記録してください。これは、ある特定のアセットをどのバリアントが生成したかを事後に判断する最も安価な方法です。

納品前にパラメータを確認する

オプションパラメータの正確な集合はバリアントによって異なり、時間とともに進化します。model と prompt 以外の何かをハードコードする前に、リアルタイムのモデルドキュメントで現在のフィールド名と許容値を確認してください。文書化されていないものは推測せず、サポート外として扱いましょう。

レスポンス、失敗、リトライの処理

画像生成は背後にモデルを伴うネットワーク呼び出しであるため、失敗する部分を想定して計画しましょう。

信頼する前に検証する

各レスポンスの後、三つのことを確認します：HTTP ステータス、画像ペイロードの有無、そして返されたモデルが要求したものと一致するか。不一致があれば明示的に失敗させ、壊れたアセットを下流に流さないようにします。

リトライに値する失敗だけをリトライする

すべてのエラーがリトライに値するわけではありません。不正な形式のプロンプトや無効なモデル名は毎回同じように失敗します——リクエストを修正すべきです。タイムアウト、接続リセット、レート制限のレスポンスといった一時的な失敗はリトライに値します。

ジッター付きの上限付き指数バックオフを使います：

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

総試行回数を制限して、壊れたリクエストが無限にループしないようにし、各試行のモデルとプロンプトハッシュを記録して、特定のバリアントが不安定かどうかを見分けられるようにします。

意図的にフォールバックする

あるバリアントが継続的に失敗する場合、ファミリー内の別のメンバーにフォールバックすることでパイプラインを維持できます。三つとも同じリクエスト形式を共有しているため、フォールバックはリトライ時に異なる model 値を使うだけです。順序を事前に決めておきましょう——例えば、高忠実度の呼び出しが繰り返し失敗したときに nano-banana-pro から nano-banana-2 へフォールバックする——そしてフォールバックがいつ発動したかを記録し、パターンに気づけるようにします。

失敗を可視化する

返されたペイロードを保存する前に検証し、リトライとフォールバックにメトリクスを出します。エラー率が上昇したときには、一連のタスクが静かに空の結果を生み出す前に気づきたいものです。

納品前の強化

画像生成をユーザーに公開する前に、このチェックリストを確認してください。

ID とパラメータを確認する

モデル識別子は変化します。Nano Banana ファミリーの現在のモデル名を再確認し、各オプションパラメータをリアルタイムのドキュメントと照合してください。古い例にしか存在しない値を納品しないようにしましょう。

設定を一元化する

モデル ID、プロンプトテンプレート、リトライ制限をひとつの設定モジュールに置きます。プロンプトを nano-banana から nano-banana-pro にアップグレードするとき、それは複数のファイルに散らばったコードの変更ではなく、一度の設定変更であるべきです。

重要な情報を記録する

各呼び出しについて、モデル、プロンプトバージョン、レスポンスステータス、レイテンシ、そしてリトライやフォールバックが発生したかどうかを記録します。長いプロンプトはハッシュ化してログを読みやすく保ちます。これこそが「なぜこの画像は昨日と違って見えるのか？」に答えられる理由です。

スケール時に使用量を監視する

課金は使用量に連動するため、呼び出し回数とバリアントの組み合わせに注意を払います。すべてのリクエストが静かに nano-banana-pro にエスカレーションされると、探索ツールがコスト問題に変わりかねません。意図的にルーティングしましょう：反復には安価なバリアント、最終出力にはより強力なバリアントを使います。

エンドポイントをテストする

固定プロンプトで各バリアントを一度ずつ呼び出し、レスポンスが有効であることをアサートする小さなスモークテストを書きましょう。リリース前に毎回、現在のドキュメントに対してこれを実行すれば、モデルの変更が本番環境で不意打ちになることはありません。

単一のクライアント、共有のプロンプトライブラリ、意図的なルーティング戦略で納品すれば、HiAPI 上の Nano Banana ファミリーは、統合を書き直すことなくドラフトから最終レンダリングまで拡張するための唯一の依存先となります。