チュートリアル
HiAPI API を使って Nano-Banana を利用する方法:curl、Python、実行可能なリクエスト
このページの内容
API としての Nano-Banana が開発者に提供するもの
Nano-Banana は HiAPI API を通じて提供される画像生成モデルです。プロンプトを送信し——必要なら1枚または複数の参照画像を添付し——生成された画像を受け取ります。全体のメンタルモデルはこれだけです。ローカルでのモデルホスティングも、GPU の準備も、追加の SDK の学習も不要です。他の HiAPI モデルで使っている認証方式、リクエストのラッピング、非同期タスクの仕組みがここでもそのまま当てはまります。
コードを書く前に、画像生成エンドポイントが何であり、何でないかを明確にしておくと役立ちます。これはクリエイティブなエンドポイントです。同じプロンプトでも実行のたびに異なる結果を生むことがあり、パイプラインはそれを許容するよう設計すべきです。リサイズやフォーマット変換のような決定論的な変換ではありません。ピクセル単位で正確な再現性が必要なら、検収済みの出力をキャッシュしておき、再生成すれば同じ結果が得られると仮定しないでください。
典型的な統合は3つのフェーズに分かれます:
- プロンプトと任意の入力オプションを添えて生成リクエストを送信する。
- 画像生成は単純なテキスト補完より時間がかかるため、生成されたタスクの完了を待つ。
- 出力を取得して保存し、受け入れるかプロンプトを調整して再試行するかを決める。
最初に決めておくべきことが2つあり、それらは他のすべての工程に影響します:プロンプトが純粋なテキストか参照画像を使うか(これによりリクエストペイロードが変わる)、そして複数回の生成でキャラクターの一貫性を保つ必要があるか(ほぼ常に参照画像を使うことを意味する)。以下のセクションではリクエスト構造から外側へ展開していき、例を調整しながら読めるようになっています。
Nano-Banana リクエストの構造を解剖する
HiAPI を通じた Nano-Banana の各リクエストは骨格が同じです。変わるのはペイロードだけです。
エンドポイントと認証
リクエストは HiAPI のベース URL に送られ、具体的なモデルは手作業で組み立てた上流の URL ではなくリクエストペイロードで指定します。Authorization ヘッダーに API キーを載せて認証します。キーは環境変数で保持してください——ソースコードにインラインで書いたり、リポジトリにコミットしたりしないでください。
モデル名
モデル識別子は JSON リクエストボディ内のフィールドです。自分で組み立てたものではなく、モデル一覧から逐語的にコピーすべき文字列として扱ってください。そうすれば命名変更でコードが静かに壊れることはありません。
プロンプトペイロード
最低限、目標の画像を説明するテキストプロンプトを送る必要があります。ここではプロンプトの品質が他のどのフィールドよりも出力品質に大きく影響します。被写体、構図、ライティング、スタイルを具体的に指定してください。曖昧なプロンプトは曖昧な画像を生成し、どんなパラメータ設定も、本当に必要なものを説明しきれていないプロンプトを救うことはできません。
任意の参照画像
参照画像を含める場合、それらは同じリクエストボディに属します——通常は画像 URL またはエンコードされた画像データとして提供しますが、モデルが受け付ける形式によります。参照画像はキャラクターの顔、服装、全体的なアートスタイルなどをアンカーできます。純粋なテキストからの生成では省略し、出力が特定の対象に似ている必要があるときに含めてください。
出力関連のフィールド
一部のフィールドは内容ではなく結果の形式に影響します:例えば要求する出力サイズやアスペクト比です。これらは保証値ではなく要求値と考えるのが最善です——モデルが返すサイズはわずかに異なる場合があります。下流のコードは要求した値を前提にせず、実際に返されたサイズを読み取るべきです。
以下は概念的な構造で、値はプレースホルダーです:
{
"model": "<nano-banana-model-id>",
"prompt": "ゴールデンアワーの草原に座るアカギツネ、浅い被写界深度",
"reference_images": [],
"size": "1024x1024"
}
正確に受け付けられるフィールド名と形式についてはモデルのパラメータドキュメントを参照してください——上記の構造は一般的なパターンであり、規範ドキュメントの代わりにはなりません。
実行可能な curl リクエスト
キーが有効でペイロードが正しいことを確認する最速の方法は curl 呼び出しです。まず環境を設定します:
export HIAPI_API_KEY="your-api-key-here"
次に生成リクエストを送信します:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<nano-banana-model-id>",
"prompt": "ゴールデンアワーの草原に座るアカギツネ、浅い被写界深度",
"size": "1024x1024"
}'
各部分の役割:
- URL — HiAPI の画像生成パス。1つのベース URL がすべてのモデルにサービスし、モデルはリクエストボディで指定します。
Authorization— キーは環境から読み取ることで、シェル履歴やソース管理に残らないようにします。Content-Type—application/jsonでなければなりません。設定を忘れてパースエラーになるのはよくある初心者のミスです。- リクエストボディ — 前セクションの JSON ペイロードで、本当に欲しいプロンプトを含みます。
レスポンスの解釈
レスポンスは何が起きたかを教えてくれます。注目すべき結果は2種類あります:
- 同期結果 — 呼び出しによっては画像データや画像 URL を直接返します。URL が返ってきたら、長期的に利用可能だと期待せず、できるだけ早く取得して保存してください。
- タスクハンドル — 生成が非同期の場合、レスポンスにはステータスをポーリングするための識別子が含まれます。これが後述の非同期セクションの主題です。
レスポンスボディに加えて HTTP ステータス行とレスポンスヘッダーも見たい場合は、curl コマンドに -i を加えてください——エラー時に認証問題かペイロード問題かの切り分けに非常に役立ちます。
Python での同じ呼び出し
使い捨てのスクリプト以外では Python を使ってください。requests ライブラリはサンプルの依存を軽量に保ち、HTTP レイヤーを明示的に可視化します。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
payload = {
"model": "<nano-banana-model-id>",
"prompt": "ゴールデンアワーの草原に座るアカギツネ、浅い被写界深度",
"size": "1024x1024",
}
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)
最初から身につけるべきいくつかの習慣:
- タイムアウトを設定する。 画像生成は遅いため、タイムアウトがないとワーカープロセスが無期限にハングする可能性があります。同期呼び出しでは緩めのタイムアウトが妥当な出発点ですが、負荷に応じて調整してください。
raise_for_status()を使う。 4xx や 5xx レスポンスを捕捉可能な例外に変換し、エラーレスポンスボディを結果として黙ってパースしてしまうのを防ぎます。- 関数にまとめる。 上記のスニペットはスクリプトです。サービスではプロンプトを受け取って画像データまたはタスクハンドルを返す関数が必要になり、そうすれば他のコードは HTTP の詳細を気にせずに済みます。
レスポンスに画像 URL が含まれる場合は、すぐにダウンロードして保存してください:
for item in data.get("data", []):
url = item.get("url")
if url:
img = requests.get(url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
アプリケーションの真のデータソースは自前のストレージであるべきで、一時的なリモート URL ではありません。
非同期タスクの処理
画像生成は通常、1回の HTTP ラウンドトリップで接続を保持すべき時間より長くかかります。この方式を採用する HiAPI モデルは送信時にタスク識別子を返し、その後タスクステータスエンドポイントをポーリングしてジョブが完了するまで待ちます。このパターンはプラットフォーム上のすべての非同期モデルに適用されるので、一度学べば十分です。
まず送信し、次にポーリング
最初の POST はタスク ID に似たものを返します。その後、その ID でステータスエンドポイントをポーリングします。必要なロジックは次のとおりです:
import time
def poll_task(task_id, api_key, interval=2, max_wait=300):
headers = {"Authorization": f"Bearer {api_key}"}
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"https://api.hiapi.ai/v1/tasks/{task_id}",
headers=headers,
timeout=30,
)
r.raise_for_status()
body = r.json()
status = body.get("status")
if status in ("succeeded", "completed", "failed", "error"):
return body
time.sleep(interval)
raise TimeoutError(f"タスク {task_id} は {max_wait} 秒以内に完了しませんでした")
つまずきを減らす3つのルール
- 常に総待機時間を制限する。 決して完了しないジョブでワーカープロセスを詰まらせてはいけません。上記の
max_waitが脱出経路です。 - バックオフする。 固定の短い間隔はインタラクティブな用途には問題ありませんが、バッチジョブでは待機時間の増加に応じて間隔を広げ、ステータスエンドポイントを頻繁に叩かないようにします。
- 終了状態を検証する。
succeededは出力を読み取れることを意味し、failedは盲目的に再試行するのではなくエラーペイロードを読むべきことを意味します。不正な形式のペイロードを再試行しても時間を無駄にするだけです。
タスク ID は自前のジョブ記録とともに永続化してください。プロセスがポーリング中に再起動しても、再送信して重複した生成に課金されることなく、ポーリングを継続できます。
参照画像とキャラクターの一貫性
純粋なテキストプロンプトは一度きりの画像には問題ありませんが、10の異なるシーンに同じキャラクターを登場させる必要がある場合は力不足です。顔を言葉で説明し、モデルが安定的に再現してくれることを期待しても、ほとんどうまくいきません——表現の微妙な違いが別人を生成してしまいます。
参照画像がこの問題を解決します。リクエストにテキストプロンプトとともに1枚または複数の画像を含めると、モデルはそれらを視覚的なアンカーとして使います。キャラクターの一貫性が中心的なユースケースです:
- キャラクター設定シート — 1枚のクリーンな参照画像、複数のシーンプロンプトで、顔と服装を一貫させる。
- スタイルのアンカリング — 参照画像が視覚言語を設定し、プロンプトが内容を導く。
- 商品画像 — 物体の参照画像により、そのデザインが異なる背景でも安定する。
リクエストでは、空の値を送るのではなく参照画像フィールドを埋めることを意味します。画像はモデルのパラメータ仕様がサポートする形式に応じて URL またはエンコードデータとして提供し、参照画像はクリーンに保ってください。モデルは関心のある部分だけでなく画面内のすべてを捉えるため、雑然としたシーンよりも明確な被写体のほうが優れています。
パイプラインの実用的なパターン:
- 詳細なテキストプロンプトからキャラクターを一度生成する。
- それをレビューし、満足するまで受け入れるか再生成する。
- その検収済みの画像を、以降の各シーンの参照画像として使う。
これが nano banana API python ワークフローの縮図です:まずキャラクターを一度固定し、その後はプロンプトのシーン部分だけを変えます。反復を想定してください——参照画像は一貫性を高めますが完璧にはできません。すべての出力が使えると仮定せず、レビューステップを組み込んでください。
出力解像度と実際の制約
解像度は仮定によって問題が起きやすい箇所なので、慎重に扱うべきです。
要求サイズと実際のサイズ
出力サイズを要求できますが、それはヒントとして扱うべきです。特に一般的でないアスペクト比では、モデルが返すサイズが要求と異なる場合があります。堅牢な方法は、実際に受け取った画像サイズを読み取って汎用的に処理することです:ストレージ、サムネイル、レイアウトは要求値ではなく実際のファイルに基づくべきです。
品質を決めるもの
出力品質は主にプロンプトによって決まり、参照画像を使う場合はそれによっても決まります。構図が良く、被写体とライティングが明確なプロンプトは、曖昧だがより大きなサイズを要求するプロンプトよりも良い画像を生みます。説明不足のプロンプトを解像度で補おうとしないでください。
制約を踏まえた計画
- サイズをハードコードしない でください。下流コードでは返された画像から読み取ります。
- 保存前に検証する。 アプリケーションが最小サイズを要求する場合、生成後に実際のサイズを確認し、不足していれば再生成してください——要求がその要件を強制したと仮定しないでください。
- ファイルサイズに注意する。 高解像度の出力はより大きなペイロードを意味します。ループ内ですべてをメモリに読み込むのではなく、ストリーミングまたはバッファリングしてダウンロードしてください。
- バッチ処理は慎重に。 同時実行数はアカウント単位で制限されます。大量の画像を生成する場合は、無制限のループでリクエストを乱発するのではなく、バックオフ付きの再試行を備えた小さなワーカープールを追加してください。
Nano-Banana の正式な機能と許容値については、本文中のサンプルペイロードではなく、このモデルのドキュメントを参照してください。課金はプラットフォーム通常の従量制に従い、現在の料金は本チュートリアルではなく価格パネルを参照してください。
よくあるエラーのトラブルシューティング
初回統合の失敗のほとんどはいくつかのカテゴリに分類されます。以下は各カテゴリのチェックポイントです。
401 / 403 — 認証
キーが欠落しているか、形式が誤っているか、送信されていません。Authorization ヘッダーが存在し、Bearer プレフィックスが付き、環境変数が実際にコードを実行するシェルまたはプロセスにエクスポートされていることを確認してください。キーをコピーした際の末尾の余分な改行が原因となる頻度は、予想より高いです。
400 — ペイロード形式エラー
通常は次のいずれかです:無効な JSON(余分な引用符や末尾カンマ)、誤った Content-Type、必須フィールド(prompt や model など)の欠落、またはモデルが受け付けない形式で送信された参照画像フィールド。実際に送信している正確なリクエストボディを出力し、パラメータ仕様とフィールドごとに比較してください。
404 — パスまたはモデルの誤り
エンドポイントパスが誤っているか、モデル識別子がプラットフォーム上のどのモデルとも一致しません。モデル名は記憶で入力するのではなく、一覧からそのままコピーしてください。
タイムアウトとポーリングの停滞
同期呼び出しでは、短すぎるタイムアウトが本来成功したはずのジョブを中断します。非同期ジョブでは、ポーリングの停滞は通常、ポーリングロジックが早期に終了したか、終了状態のチェックが API が実際に返すステータス文字列と一致していないことを意味します——生のステータス値を記録して確認してください。常に最大待機時間を設け、詰まったジョブがハングするのではなく明示的に失敗するようにしてください。
空の結果
200 が返るのに画像がない場合は、ほぼ常にバグではなくコンテンツの問題です:プロンプトが曖昧すぎるか、フィルタリングされた可能性があります。API の誤りだと判断する前に、レスポンスボディのエラーまたは理由フィールドを確認し、プロンプトをより厳密かつ明確にしてください。
再試行時の失敗
同じペイロードが成功したり失敗したりする場合、レート制限に達したか、一時的なサーバーエラーに遭遇している可能性が高いです。送信とポーリングの周囲に指数バックオフを追加し、400 は再試行しないでください——ペイロードを修正すべきです。
迷ったときの最速の診断方法は、シンプルなプロンプトで最小限の curl 呼び出しを行うことです。それが動作すれば、問題は認証情報ではなくペイロードかコードにあります。