チュートリアル
HiAPI API で nano-banana-2 を使う方法:実際に動く curl と Python Requests の例
nano-banana-2 を画像生成パイプラインに組み込むための開発者ガイド
このページの内容
nano-banana-2 でできること、そして使うべきタイミング
nano-banana-2 は HTTP API 経由で呼び出す画像生成モデルです。プロンプトを送信し、必要に応じてソース画像を添付すると、生成された画像が返ってきます。コードを書く前に必要なメンタルモデルはこれだけです。
nano-banana-2 を使うべきなのは、チャットウィンドウ経由ではなく、既存の製品やパイプラインの中でプログラム的に画像を生成する必要がある場合です。マーケティング素材の生成、サムネイルやカバーの作成、ベース画像に基づく反復的な修正、あるいは画像の数が自分のデータによって決まるバッチ処理などが該当します。インターフェースが普通のリクエスト/レスポンス型 API なので、言語ごとに新しい SDK を導入することなく、キューワーカー、バックエンドエンドポイント、CLI ツールの背後に置くことができます。
2 つのモードがほとんどのユースケースをカバーします:
- テキストから画像生成——プロンプトで欲しい内容を記述すると、画像が得られます。
- 画像から画像生成——ソース画像と変換内容を記述したプロンプトを提供すると、修正された画像が返ってきます。
どちらのモードもリクエストの形は同じなので、1 つのクライアントラッパー(本記事の後半で構築します)で両方を扱えます。パイプラインがテキストからのレンダリングのみであれば、image フィールドは無視して構いません。パイプラインが既存素材の編集に関するものであれば、画像から画像生成が入り口になります。
nano-banana-2 がやらないこと:リトライ、タイムアウト、ストレージ、冪等性の管理は行いません。これらは呼び出しを囲むあなたの側で構築する部分です——そしてこれこそが本チュートリアルの残りの大部分の焦点です。なぜなら、ループの中で素朴に requests.post を呼ぶことは、「デモは動くが本番では動かない」最も一般的な原因だからです。
最初のリクエストを送る前に
最初の呼び出しの前に、3 つの準備が必要です。
1. プラットフォームの認証情報
HiAPI プラットフォームから API アクセス権と、アカウントに割り当てられた認証情報を取得する必要があります。これは機密情報として扱ってください:環境変数またはシークレットマネージャーから読み込み、コードリポジトリにコミットしたり、クライアントのビルド成果物に貼り付けたりしないでください。以下のすべてのリクエストは環境変数からキーを読み込むため、ソースコードに機密情報が現れることはありません。
export HIAPI_API_KEY="your-key-here"
2. クライアント環境
curl を使う場合、必要なのは curl を実行できるシェルだけです——サンプルは標準ビルドに含まれる引数を使用しています。Python を使う場合、Python 3 と requests ライブラリが必要です:
python3 -m venv .venv
source .venv/bin/activate
pip install requests
3. 出力の保存先
画像生成は画像データを返します——レスポンスにインラインで含まれるか、後で取得できる参照として返されるかは、アカウントで返されるレスポンスの形によって異なります。バイト列をディスクに保存するのか、オブジェクトストレージにアップロードするのか、それとも呼び出し元に URL を返すのかを前もって決めてください。今のうちに考えておけば、「シェルでは動くけれど、ファイルを置く場所がない」という古典的な気まずい瞬間を避けられます。
始めるのにクォータや料金の見積もりは必要ありません。初回統合の一般的な原則は:最小限の有効なリクエストを送り、有効なレスポンスが得られることを確認してから、パラメータを追加する、というものです。次のセクションでまさにそれを行います。
動作する最小限の curl リクエスト
以下は完全なテキストから画像生成の呼び出しです。エンドポイント、ヘッダー、ボディが唯一の可変部分です:エンドポイントは HiAPI プラットフォーム上のモデルと操作を識別し、ヘッダーは認証情報を運び、JSON ボディはペイロードを運びます。
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"prompt": "a minimalist isometric workspace, soft daylight, muted palette",
"n": 1
}'
HIAPI_BASE_URL は HiAPI アカウントのダッシュボードに表示される API ベースアドレスに設定してください。そうすればホスト名をスクリプトにハードコードする必要がありません。リクエストボディには 3 つのフィールドがあり、いずれも重要です:
modelはプラットフォームにどのモデルを実行するかを伝えます。たとえ他所でデフォルト値を使っていても、明示的に残してください。ログ自体が意味を持つようになります。promptは自然言語です。被写体、構図、スタイルを具体的に記述してください。曖昧なプロンプトは曖昧な画像を生みます。nはこのプロンプトに対して要求する画像の数です。接続が通っているかを検証する際は、まず1から始めてください。
成功したレスポンスはレスポンスボディに画像データを返します。パーサーを書く前にまずそれを確認してください:出力を jq にパイプするか、ファイルにリダイレクトして、トップレベルのキーを確認します。確認すべきは 2 点——リクエストが受け入れられたこと、そして画像ペイロードがレスポンスのどこに実際にあるか、です。
最初の呼び出しで慌ててパラメータを追加しないでください。自分が理解している動作するベースラインは、コピーしてきた巨大なリクエストボディよりも価値があります。この呼び出しが画像を返すようになれば、以降の各セクションはそのバリエーションにすぎません。
同じリクエストを Python で書く
curl 呼び出しをペイロードを変えずに Python に移植します。単一の真実の源(1 つの dict)を保つということは、シェルで検証したリクエストボディが、そのまま本番に出すリクエストボディになることを意味します。
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
timeout: float = 60.0) -> dict:
"""テキストから画像生成のリクエストを 1 回送信し、パース済みの JSON レスポンスを返します。"""
payload = {"model": model, "prompt": prompt, "n": n}
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"a minimalist isometric workspace, soft daylight, muted palette"
)
print(result.keys())
強調すべき細部が 3 つあります。コードスニペットをコピーする際に最も見落とされやすい部分だからです。
常に timeout を設定する。 設定しないと、スタックした接続がワーカーを無期限にブロックします。上記の値は出発点にすぎず、鉄則ではありません——実際に観測されるレイテンシに合わせて調整してください。
data= ではなく json= を使う。 dict を json に渡すとコンテンツタイプが正しく設定されシリアライズされます。生の文字列を data に渡すことが、モデルの障害に見えるリクエストボディのフォーマットエラーの原因です。
パース前に raise_for_status() を呼ぶ。 4xx レスポンスに対して .json() で画像フィールドをパースしようとすると、紛らわしい下流のエラーが発生します。まず HTTP ステータスコードを明らかにしてください。
この関数が前述の再利用可能なラッパーです。次のセクションではそのペイロードを置き換えるのではなく拡張します。
テキストから画像生成と画像から画像生成のペイロード
2 つのモードの違いは 1 点だけです:リクエストボディにソース画像が含まれるかどうか。それ以外——エンドポイント、認証ヘッダー、モデル名——はすべて変わりません。
テキストから画像生成
{
"model": "nano-banana-2",
"prompt": "a minimalist isometric workspace, soft daylight",
"n": 1
}
画像から画像生成
{
"model": "nano-banana-2",
"prompt": "same scene, but converted to a warm evening palette",
"image": "<base64-encoded source image>",
"n": 1
}
内面化すべき概念:画像から画像生成モードでは、プロンプトは変換を記述するものであり、完成したシーンをゼロから記述するものではありません。「ウォームな夕方の色調に変換する」は、画像全体を再記述するよりも優れています。ソース画像がすでに内容を提供しているからです。
image フィールドに関する実用的な注意点が 2 つあります:
- API がそのフィールドに対してドキュメントで規定する形式に従ってソース画像をエンコードし、エンコード後のペイロードをリクエストサイズの予算を大きく下回るようにしてください。過大な入力はリクエストが拒否される主な原因の 1 つです。
- ユーザーアップロードを受け付ける予定なら、エンコード前にサイズと形式を検証してください。手元で素早く失敗する方が、4xx で終わる往復よりもはるかに安く済みます。
Python ラッパーにオプションの image パラメータを追加すれば、1 つの関数で両方のモードに対応できます:
def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
if image is not None:
payload["image"] = image
# ... 以前と同じリクエスト呼び出し
分岐が単なる if 1 つなので、呼び出しコードがモードを決め、転送層はそのまま変わりません。これが単一ラッパーを保つことの見返りです。
非同期タスクとリトライの処理
画像生成は典型的な JSON API 呼び出しよりも時間がかかる場合があります。レスポンスによっては完成した画像を即座に返すものもあれば、結果を得るためにポーリングが必要なタスクを返すものもあります。最初に成功した呼び出しが即時返却だったとしても、ポーリングのシナリオを想定して設計してください——そうしないと、ある生成に時間がかかりすぎたときにパイプラインが崩壊します。
堅牢なパターンは 3 つの部分から成ります:バックオフ付きのポーリングループ、ハードな締め切り、そして「まだ準備できていない」と「失敗」を区別するリトライ戦略です。
import time
import requests
def poll_job(job_id: str, base_url: str, api_key: str,
initial_wait: float = 2.0, max_wait: float = 30.0,
deadline: float = 300.0) -> dict:
start = time.monotonic()
wait = initial_wait
while True:
if time.monotonic() - start > deadline:
raise TimeoutError(f"job {job_id} exceeded deadline")
response = requests.get(
f"{base_url}/v1/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30.0,
)
response.raise_for_status()
body = response.json()
status = body.get("status")
if status == "succeeded":
return body
if status == "failed":
raise RuntimeError(f"job {job_id} failed: {body}")
time.sleep(wait)
wait = min(wait * 2, max_wait)
ジョブのパスとステータスの語彙は、HiAPI アカウントの API リファレンスで規定されているものに合わせてください——上記のキーを対応する形に調整しつつ、構造は保ってください。
本番環境で健全に保つためのルール:
- 上限付きの指数バックオフ。 200 ミリ秒ごとにポーリングするとクォータを浪費し、エンドポイントに負荷をかけます。待機時間を倍にしつつ上限を設けることで、実際の完了時間付近で安定します。
- 総試行回数と総時間を制限する。
deadlineは交渉の余地がありません。無制限のループは、遅い日が来るのを待っているだけの障害です。 - リトライ可能なエラーのみリトライする。 一時的なネットワークエラーや 5xx レスポンスはジッター付きで再試行に値しますが、4xx レスポンスは違います——不正なペイロードを再送しても時間を浪費するだけです。小さく上限のあるリトライ回数(2〜3 回)を使い、毎回ログに記録してください。
- リトライを安全にする。 タスク作成エンドポイントが冪等キーを受け付けるなら、論理リクエストごとに安定したキーを送ることで、リトライ送信が重複生成を起こさなくなります。
締め切り、バックオフ、上限付きリトライ回数があれば、遅い生成はワーカーがハングする事象ではなく、記録され処理されるイベントになります。
実際に遭遇するエラーのデバッグ
呼び出しが失敗したら、モデルパラメータをいじる前に、まず生のステータスコードとレスポンスボディ全体を読んでください。レスポンスボディが通常問題を指し示します。推測はログ記録よりも遅いのです。
認証の失敗
401 または 403 は、ほぼ常に次のいずれかを意味します:環境変数にキーがない、ヘッダーの形式が間違っている、あるいはこの環境で認証情報が有効化されていない。実際に送信しているヘッダーのリテラル値を確認してください——Bearer プレフィックスの欠落や、コピーしたキーに余分な改行が混入するのはよくある原因です。
ペイロードの誤り
リクエストボディに関するメッセージを伴う 400 は、JSON 自体に誤りがあることを意味します:prompt の欠落、余分なカンマ、Python で json= ではなく data= を使っている、あるいは image フィールドのエンコードが正しくない、などです。送信している正確なバイト列を一度出力して確認し、その後出力を削除してください。
入力の拒否
検証に通らない画像から画像生成リクエストは、通常ソース画像に関係します:大きすぎる、形式が誤っている、デコードできない。送信前に手元でサイズとエンコードを検証し、画像を提供した人にリトライではなく明確なエラーを返してください。
タイムアウトと 5xx
これらはリトライ可能なカテゴリに属します。ログで接続タイムアウトとサーバーエラーを区別し、リトライに上限があることを確認してください——そうしないと持続する 5xx が無限ループになります。
効果的な調査手順
- 失敗ごとに HTTP ステータスコードと生のレスポンステキストを記録する。
- 何よりもまず認証情報の経路を検証する。
- 失敗したペイロードを curl で再送し、クライアントコードを方程式から外す。
- それが済んでから初めて、
prompt、image、その他のモデルパラメータを調整する。
4 つの手順すべてを経ても失敗が残る場合は、レスポンスからリクエスト ID(または同等の相関フィールド)を取得し、サポートへの連絡時に添付してください——曖昧な報告を追跡可能なものに変えられます。
本番対応にする
本番に出る前に、このチェックリストを一通り確認してください。
- 機密情報: API キーは環境変数またはシークレットマネージャーから読み込まれ、いかなるログ、エラーメッセージ、クライアントのビルド成果物にも現れない。
- タイムアウト: すべての HTTP 呼び出し——作成、ポーリング、結果画像の取得——に明示的なタイムアウトがある。
- 境界: ポーリングには締め切りがあり、リトライには最大試行回数があり、コードがリトライ可能な失敗とリトライ不可の失敗を区別している。
- 可観測性: 呼び出しごとにリクエストの形(プロンプトにユーザーデータが含まれうる場合は省略またはハッシュ化)、ステータスコード、レイテンシ、相関 ID を記録している。
- コスト意識: 課金は HiAPI アカウントで定義された次元に従うため、リクエストごとに何回の生成とどれだけの出力を生むかを追跡し、自分の使用量カウンターに計測を仕込み、暴走ループが請求書より先に見えるようにする。
- ストレージ: 生成された画像は永続的な場所——オブジェクトストレージやデータベース——に書き込まれ、コンテナとともに消える一時ディレクトリに残されていない。
これらの項目に nano-banana-2 固有のものは 1 つもありません。それこそが要点です:モデル呼び出しは簡単な部分であり、その周りにあるすべては普通の分散システムの衛生管理です。ラッパーを 1 度構築し、ペイロードを 1 つの dict に保てば、テキストから画像生成も画像から画像生成も無料で手に入ります。
curl 呼び出しから始め、それを Python ラッパーに移植し、ポーリングループを追加し、チェックリストを実行してください。モデルの詳細と最新の API リファレンスについては、HiAPI プラットフォームの nano-banana-2 ドキュメントを参照してください。