チュートリアル
Nano-Banana-2 API チュートリアル:hiapi 経由で動作する curl と Python Requests を使う
このページの内容
初回呼び出し前の準備
Nano-Banana-2 にリクエストを送る前に、4 つのものを用意しておきましょう。どれもそれほど時間はかからず、4 つすべてを揃えておけば、初回リクエストは宝探しではなくコピー&ペーストの練習になります。
1. hiapi アカウントと API キー
すべてのリクエストは、あなたの hiapi アカウントに紐づく API キーで認証されます。アカウントのダッシュボードでキーを作成し、安全な場所に保管してください——パスワードマネージャー、あるいはあなたのマシン上の環境変数などです。パスワードと同じように扱いましょう:コードリポジトリにコミットしたり、共有ドキュメントに貼り付けたりしてはいけません。
あなたのマシン上で、シェルセッションごとに一度エクスポートしておけば、以下のサンプルは何もハードコードせずにそれを読み取れます:
export HIAPI_API_KEY="your_api_key_here"
2. API のベース URL
ベース URL は、すべてのリクエストの構築元となるルートアドレスです。エンドポイントを構築する際は、その後にモデルのルートを追加します。ベース URL は複数のファイルに散らばらせず、コード内の設定変数に置きましょう——そうすれば変化したときに 1 行だけ変更すれば済みます。
3. リクエストを送信するクライアント
始めるにあたって必要なのは、以下のいずれか 1 つだけです:
- curl —— ほぼ間違いなくすでにインストールされています。アプリケーションコードを書く前に、キーとリクエストボディが正しいことを確認するために使いましょう。
- Python 3 と
requestsライブラリ(pip install requests)。ほとんどの読者は本格的な統合を構築するためにこちらを使うでしょう。
両方を用意しておくと便利です:curl はリクエストをあなたのコードから切り離してくれるので、問題が起きたときに API 呼び出しの問題なのかアプリケーションの問題なのかがわかります。
4. 何を生成したいかを明確にする
Nano-Banana-2 はテキストからの画像生成と画像からの画像生成の両方をサポートしています。どちらのモードが必要かを事前に決めておきましょう。リクエストボディの構造が異なるからです(後述します)。初回の呼び出しでは、テキストからの画像生成から始めましょう——変動要素が最も少ないからです。
キーをエクスポートし、クライアントをインストールし、プロンプトも考えたところで、次はリクエストそのものを見ていきましょう。
Nano-Banana-2 リクエストの構成要素
Nano-Banana-2 の呼び出しは、JSON リクエストボディを伴う POST リクエストです。各フィールドにはそれぞれ役割があり、それらを個別に理解しておけば、問題が起きたときに一度に 1 箇所ずつ修正できます。
エンドポイント
リクエストは hiapi API のベース URL に Nano-Banana-2 のモデルルートを追加した先に送られます。メソッドは常に POST です。リソースを取得するのではなく、処理待ちのペイロードを送信するからです。
リクエストヘッダー
重要なヘッダーは 2 つあります:
Content-Type: application/json—— API にリクエストボディの解析方法を伝えます。Authorization—— API キーを運びます。以下のサンプルは、先ほどエクスポートした環境変数からこれを読み取ります。
いずれかのヘッダーが欠けていたり形式が誤っていたりすると、モデルがそれを見る前にリクエストは失敗します。これは混乱を招くエラーの最も一般的な原因です。
リクエストボディのフィールド
テキストからの画像生成リクエストは以下のフィールドを持ちます:
model—— 実行するモデルが Nano-Banana-2 であることを指定します。デフォルト値が存在する場合でも明示的に書きましょう。コードが自己説明的になり、デフォルト値が変わったときにあなたを守ってくれます。prompt—— 欲しい画像を自然言語で記述します。あなたの反復作業の大部分はここで行われます。具体的に書きましょう:被写体、構図、スタイル、光。曖昧なプロンプトは曖昧な結果を生みます。- 画像入力 —— テキストからの画像生成では省略または空になります。画像からの画像生成では参照画像を運びます(画像からの画像生成のセクションで詳しく説明します)。
- 出力とサイズのパラメータ —— 返される結果の形状や比率に影響するモデル固有のフィールドです。モデルのドキュメントがサポートを明記しているフィールドだけを設定しましょう。厳格な API では、未知のフィールドは黙って無視されるのではなく、通常はリクエストが拒否されることを意味します。
返される内容
レスポンスは JSON です。呼び出しの構成によって、生成された画像データを直接受け取るか、その参照を受け取ります。クライアントコードは、返されたボディを調べる前にまず HTTP ステータスを確認すべきです——200 形態のレスポンスが検証なしに必ず画像を含むと仮定してはいけません。
構造はこれだけです:少数の明示的な JSON リクエストボディを伴う認証済みの POST リクエスト。このチュートリアルの残りの部分は、この形態のバリエーションにすぎません。
動作する curl リクエスト
これはあなたが送れる最小限の完全な呼び出しです。API キーをエクスポート済みのターミナルで実行すれば、数秒でアカウント、キー、ネットワーク経路がすべて正常に機能しているかがわかります。
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "夜明けの岩がちな海岸線に建つ風化した小屋、低い霧、柔らかな暖かい光、ワイドな構図"
}'
シェルでキーと一緒にベース URL を一度設定します:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(hiapi ダッシュボードに表示されるベース URL を使用してください——それがあなたのアカウントの正式な値です。)
出力を読む
curl は生のレスポンスを stdout に出力します。呼び出しが成功すれば、生成された画像を含む JSON が表示されます。python -m json.tool にパイプして、出力を整形し構造を確認しましょう:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"新雪の中の赤いキツネ、横顔、くっきりとしたディテール"}' \
| python -m json.tool
目にする内容の解釈
- 成功レスポンス —— キーが有効で、エンドポイントが正しく、リクエストボディが解析できたことを確認できます。この動作するコマンドを保存しましょう——これがあなたの基準線になります。
- エラーレスポンス —— 3 行のリクエストヘッダーかリクエストボディのどこかに問題があることを意味します。エラーテキストをコピーしましょう。デバッグのセクションで、よくあるエラーを修正方法にマッピングします。
curl から始める価値は分離にあります。キー、ヘッダー、JSON がすべて 1 箇所に見えるので、失敗はリクエスト自体を指し示し、あなたのアプリケーションコードを指しません。このコマンドが動作すれば、Python への移植は機械的な作業です。
同じリクエストを Python で実装する
以下は requests を使った同じ呼び出しです。リクエストボディは curl のリクエストボディで見たのと同じ dict です——API 自体は何も変わらず、変わるのは送信方法だけです。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "夜明けの岩がちな海岸線に建つ風化した小屋、低い霧、柔らかな暖かい光、ワイドな構図",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
なぜこのように書くのか
json=payloadによりrequestsが dict をシリアライズし、Content-Typeを設定します。そのヘッダーを明示的に渡すこともできます。害はなく、リクエストが自己説明的になります。timeout=120—— 画像生成は瞬時ではありません。余裕のあるタイムアウトは、モデルがまだ動作している間にクライアントが諦めるのを防ぎます。ユースケースに合わせてこの値を調整しましょう。raise_for_status()は非 2xx レスポンスを例外に変換するので、失敗は結果処理コードに静かに流れ込むのではなく、即座に表面化します。- 環境変数はキーをソースコードから遠ざけます。本番環境では、コミットされる可能性のある
.envファイルではなく、プラットフォームのシークレットストアから注入しましょう。
画像を取り出す
レスポンスボディは JSON です。まず一度対話的に確認して正確な構造を把握し、それから画像フィールドを明示的に取り出します:
image_url = data["image_url"] # 実際のレスポンスでキー名を確認する
レスポンスが URL ではなく base64 データを運んでいる場合は、デコードして書き込みます:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
フィールド名を推測してはいけません——最初の成功した呼び出しで生のレスポンスを出力し、実際に存在する内容に基づいて値を取得しましょう。この 1 つの習慣がほとんどの統合上の欠陥を防ぎます。
テキストからの画像生成と参照画像付きの画像からの画像生成
ここまではテキストからの画像生成でした:プロンプトを入力し、画像を出力します。Nano-Banana-2 は画像からの画像生成もサポートしており、参照画像を提供するとモデルがそれをガイドとして使います。いつモードを切り替えるか、そしてリクエストボディがどう変わるかを知ることが、成功した呼び出しと拒否された呼び出しの分かれ目です。
各モードをいつ使うか
- テキストからの画像生成 —— テキストで表現できるアイデアがあり、開始画像がない場合。探索、イラスト、ゼロから生成するあらゆるコンテンツに最適です。
- 画像からの画像生成 —— 既存の画像があり、バリエーション、リスタイル、またはその構造や被写体を保った編集をしたい場合。デザインの反復、ビジュアルスタイルのマッチング、写真の変換に使うモードです。
あなたのプロンプトが「……のように見せて」や「レイアウトは保って……」であれば、画像からの画像生成が必要です。
参照画像がリクエストをどう変えるか
エンドポイントとリクエストヘッダーは変わりません。変わるのはリクエストボディです:プロンプトの隣に参照画像のフィールドを追加します。画像の提供方法に応じて、そのフィールドは URL またはエンコードされた画像データを運びます。以下のルールを覚えておきましょう:
- リンクを渡す場合は、直接公開アクセス可能な URL を使いましょう。ログインが必要なページや認証付きリダイレクトを経由するページは失敗します——API はバイトを直接取得する必要があります。
- 想定される形式に合わせましょう。 PNG や JPEG などの一般的な形式は安全です;異常なファイルや破損したファイルはリクエスト拒否のよくある原因です。
- アップロード前にサイズ制限を確認しましょう。 大きな画像はリクエストボディエラーの原因になることがよくあります。
- プロンプトを焦点を絞ったものにしましょう。 参照画像がある場合は、参照画像を再記述するのではなく、望む変換を記述しましょう。
示唆的な画像からの画像生成のリクエストボディは以下のとおりです:
payload = {
"model": "nano-banana-2",
"prompt": "同じ被写体を、軽いクロスハッチングを施したグラファイトスケッチ風にリスタイルする",
"image_url": "https://example.com/your-reference.jpg",
}
いつもどおり、正確なフィールド名は最初の成功レスポンスで確認してください。原則はシンプルです:テキストからの画像生成はプロンプトだけ、画像からの画像生成は同じリクエスト形態に検証済みの参照画像を追加するだけです。まずテキストからの画像生成でフローが機能することを証明し、それから参照画像を重ねましょう。
エラーの処理と失敗したリクエストのデバッグ
Nano-Banana-2 の呼び出しの失敗は 3 つのカテゴリに集約されます。それぞれを見分けられるようになれば、ほとんどの問題を 1 分以内に修正できます。
認証エラー
認証エラーが表示される場合、キーが API に正しく届いていないことを意味します。順番に確認しましょう:
HIAPI_API_KEYは、リクエストを実行するシェルまたは環境で実際にエクスポートされていますか?echo $HIAPI_API_KEYを実行して確認しましょう。Authorizationヘッダーは存在し、形式は正しいですか?スキームとキーの両方が重要です。- キーはダッシュボードで失効またはローテーションされていませんか?
- あなたのアカウントの正しいベース URL にアクセスしていますか?
401 または 403 は、ほぼ常にこれら 4 つのいずれかを意味します。キー自体が問題であることはまれです——その周りのパイプラインが問題であることがほとんどです。
リクエストボディの形式エラー
400 系のエラーは、通常、API があなたのリクエストボディを解析または検証できないことを意味します:
- 無効な JSON —— 余分なカンマ、二重引用符の代わりの単一引用符、エスケープされていない文字など。curl の出力を
python -m json.toolにパイプすること、そして手作業ではなくコード内でリクエストボディを構築することが助けになります。 - 必須フィールドの欠落 ——
modelとpromptは最も忘れられやすいものです;毎回両方を明示的に送りましょう。 - 未知または未サポートのフィールド —— 厳格な API は認識しないフィールドを拒否します。リクエストが通るまで余分なものをすべて取り除き、それから 1 つずつ戻しましょう。
- 誤った値の型 —— 数値を文字列で送ったり、単一の値を期待する場所に配列を渡したり。ドキュメントの型に厳密に合わせましょう。
不適切な画像入力
画像からの画像生成にのみ関係しますが、起きたとき最も苛立たしいものです:認証が必要な画像 URL、リダイレクトの後ろにある URL、画像ではなく HTML を返す URL、サイズが大きすぎる、またはサポートされていない形式。URL がログインなしでブラウザに直接読み込めることを確認し、送信前に制限に対してファイルの種類とサイズを確認しましょう。
効果的なデバッグの順序
- エラーメッセージとステータスコードを文字どおりに読みましょう——通常は問題を指し示しています。
- 最小限のフィールドで curl で失敗したリクエストを再現し、それから徐々に複雑さを戻しましょう。
- 処理する前に完全なレスポンスボディを出力しましょう;その構造についての仮定に頼ってはいけません。
最小化した curl 呼び出しが成功するのにあなたのアプリケーションが失敗するなら、欠陥はあなたのコードにあり、API にはありません。これはあなたができる最速の診断の分岐点です。
アプリケーションに接続する
動作するリクエストは良いスタートです;信頼性のある統合にはその周りにもう少し多くのものが必要です。以下は、一度きりの呼び出しから依存できるものへと移行する方法です。
呼び出しを関数にカプセル化する
リクエストを関数に隔離し、プロンプト(オプションで参照画像)を受け取り、結果を返すようにしましょう。リクエストヘッダー、ベース URL、リクエストボディの構築をすべてその関数の内部に置けば、コードベースの他の部分がそれらに触れることは決してありません。API が変わったとき、編集するのは 1 箇所だけで済みます。
意識的にリトライを処理する
生成は、あなたのリクエストボディとは無関係な理由で一時的に失敗することがあります。指数バックオフでリトライしましょう。ただしリトライ可能な失敗——タイムアウトや一部のサーバー側エラー——に限ります。認証やリクエストボディの検証エラーは決してリトライしてはいけません;それらは毎回同じように失敗し、負荷を増やすだけです。試行回数を制限し、持続する問題を表面化させ、ぶら下がったままにしないようにしましょう。
タイムアウトと同時実行
生成に十分余裕のある、しかし上限のあるタイムアウトを設定し、実際の応答時間を測定した後に調整しましょう。大量のリクエストを送る場合は、一度にすべて送るのではなく、妥当な同時実行制限を守りましょう——ワーカープールを伴うキューは、無制限の並列呼び出しよりも予測可能です。
生成したものを保存する
レスポンスは生成された画像をあなたに渡します。返された URL が無期限に有効であると頼るのではなく、速やかに自分のストレージにコピーしましょう。ファイルに決定的な名前を付け、各出力の横にプロンプトとパラメータを記録しましょう——後でプロンプトを反復するときに、この来歴情報が必要になります。
キーをコードから遠ざける
各環境で環境変数またはシークレットマネージャーから API キーを読み取りましょう。キーは定期的にローテーションしましょう。もしキーが本来あるべきでない場所に現れたら、ダッシュボードで失効させましょう。
小さく始めてから拡張する
1 つのプロンプトを curl で動作させ、Python に移植し、前のセクションのエラー処理を追加し、それから初めて周囲のキューやストレージを構築しましょう。各ステップが前のステップの証明になります。
検証済みの curl 呼び出し、それに一致する Python クライアント、そして処理済みの 3 つのエラーカテゴリがあれば、初回リクエストから本番統合までの完全な道筋を手にしたことになります。