Nano Banana API ガイド：TokenLab での画像生成および編集

Nano Banana APIには、TokenLab上で3つの有料モデルIDがあり、最も安価なモデルは中間のモデルの約半分のコストで画像生成が可能です。高額なミスは、モデルの選択ミスではなく、間違ったエンドポイントへ編集リクエストを送信したり、すでにタスクが作成されているのにcreateコールを再試行したりすることによって発生します。本ガイドでは、正確なID、動作するテキストから画像への変換（text-to-image）コール、参照画像（reference-image）コール、非同期ポーリング、予期されるエラー、および課金の仕組みについて解説します。価格とフィールドリストは2026年10月3日時点のものです。実装前に必ず再度確認してください。

重要なポイント

• 正確なID（nano-banana-2、nano-banana-2-lite、または nano-banana-pro）を送信してください。表示名はリクエストのエイリアスではありません。
• Nano Bananaの参照画像処理は、operation: "image-to-image" および image_urls を指定して POST /v1/images/generations へ送信します。/v1/images/edits や /v1/chat/completions ではありません。
• 2026年10月3日時点で確認した基本価格は、lite、standard、proの各IDに対して画像1枚あたり$0.0168、$0.0335、$0.067です。各モデルには価格帯があるため、Usage（利用状況）で正確なティアを確認してください。
• task_id、status: "pending"、または poll_url を含むcreateレスポンスが返された場合は、completed または failed になるまで GET /v1/tasks/{id} をポーリングする必要があります。
• ステータスの読み取りは、タスクが失敗した場合でもHTTP 200を返します。HTTPコードではなく、タスクの status フィールドに基づいて分岐処理を行ってください。
• 最終的な請求額は、コピーされた価格表ではなく、Usageおよび billing_transaction_id に記載されます。

Nano Banana APIモデル、価格単位、および各モデルの用途

本ガイドの初期ドラフトを現在のドキュメントと照らし合わせた結果、3つの問題が見つかりました。価格なしでモデルがリストされていたこと、Nano Bananaの編集リクエストをchat completions経由で送信していたこと、画像ガイドで使用されていないフィルターでカタログをクエリしていたことです。以下の表は最初の問題を修正し、後のセクションで他の2つを修正します。

モデルID	最適用途	価格単位	TokenLab価格 (USD)	ソース、観測日
nano-banana-2	aspect_ratio および resolution (1k, 2k, 4k) を使用したtext-to-imageおよびimage-to-image。2026年2月26日リリース。	per_image	リクエストあたり$0.0335。範囲$0.0225〜$0.0755。	ライブモデルAPI, 2026-10-03
nano-banana-2-lite	最も安価なtext-to-imageおよびimage-to-image。確認した価格エントリは1kティアを対象としています。	per_image	リクエストあたり$0.0168。最小・最大ともに$0.0168。	ライブモデルAPI, 2026-10-03
nano-banana-pro	aspect_ratio および resolution を使用したtext-to-image、image-to-image、および画像編集。	per_image	リクエストあたり$0.067。範囲$0.067〜$0.12。	ライブモデルAPI, 2026-10-03
nano-banana	aspect_ratio のみを使用したtext-to-image。公開されている resolution 選択肢なし。	証拠なし	モデルページまたは価格エンドポイントを確認	カタログ, 2026-10-02; Create Imageドキュメント, 2026-10-03

上記のすべての価格には is_lock_price: true が適用されており、2026-10-02T16:53:30.068Zに更新されました。選択前に以下の3点に注意してください：

• 解像度ティアによって価格が変動します。 ライブAPIでは nano-banana-2 と nano-banana-pro の範囲が表示されますが、どのティアがどの解像度に対応しているかは証拠に含まれていません。1k が基本価格であると想定しないでください。モデルの価格エントリを読み取ってください。
• テキスト出力には独自のトークン価格があります。 nano-banana-2 と nano-banana-pro の両方に native-gemini-text-output エントリがあります。これは outputModality が text の場合に適用されます。nano-banana-2 では入力0.25、出力1.5と記載されています。nano-banana-pro では入力1、出力6と記載されています。単位は per_token です。予算を立てる前に GET /v1/models/:model/pricing でスケールを確認してください。
• Liteには受け入れ可能なリクエスト形式が記載されていません。 nano-banana-2-lite のライブレコードには「記載なし」とあります。構築前に詳細を確認してください。

大まかな予算として、基本価格にボリュームを掛け合わせます。これらは見積もりであり、確定価格ではありません：

• nano-banana-2-lite で100枚：100 × $0.0168 = $1.68
• nano-banana-2 で100枚：100 × $0.0335 = $3.35
• nano-banana-pro で100枚：100 × $0.067 = $6.70

高解像度ティアではこれらの数値が上昇します。

現在の画像モデルを自身でリストするには、画像生成ガイドで使用されているエンドポイントを呼び出してください。以前のドラフトでは category=image を使用していましたが、ガイドにはその記載がありません。

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

特定のモデルの操作、価格、ライフサイクルについては、Get a Modelを使用してください。また、TokenLab Modelsディレクトリも参照できます。

Nano Banana APIでtext-to-imageリクエストを送信する

TokenLabダッシュボードでAPIキーを作成し、エクスポートします：

export TOKENLAB_API_KEY="your-tokenlab-api-key"

必ず model を送信してください。Create Imageリファレンスによると、画像APIにはデフォルトの選択肢はありません。モデルが欠落していると、param: "model" を含む 400 エラーが返されます。

このリクエストでは、Google画像ファミリーのドキュメントに記載されているフィールドのみを使用します。nano-banana-2 が 1k、2k、4k をドキュメント化しているため、resolution を 1k に設定しています。

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

--max-time 120 フラグはドキュメントに準拠しています。高解像度のリクエストは1分以上かかる場合があるため、クライアントのタイムアウトは少なくとも120秒に設定してください。ドキュメントによると、size はGoogle画像ファミリーとの互換性エイリアスですが、直接 aspect_ratio を使用することが推奨されています。

同期的な成功時には、完成した画像がインラインで返されます。以下のプレースホルダー値は、ドキュメント化された形状のみを示しています：

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

以下の順序で読み取ってください：

1. ボディに task_id、status: "pending"、または poll_url が含まれている場合は、画像ではなくタスクです。ポーリングセクションに進んでください。
2. それ以外の場合は data[0].url を読み取ります。response_format: "b64_json" の場合は、代わりに data[0].b64_json を読み取ります。
3. created はUnixタイムスタンプです。revised_prompt はモデルが返した場合のみ表示されるため、必須としないでください。
4. 画像URL、独自のジョブID、モデル、およびレスポンスヘッダーの request_id を保存してください。

生成された画像URLは、メディアコピーとして30日間保持される場合があります。各アイテムのステータスと expires_at については media_retention.items を確認してください。保留中または失敗したコピーは保証されないため、より長く必要な場合はファイルを自身のストレージにコピーしてください。データ保持ガイドに詳細が記載されています。

参照URLを使用して画像を編集する

クリーンなスタジオ背景で同じ製品ショットを撮影したいカタログチームを想像してください。/v1/images/edits を使いたくなりますが、ドキュメントではそれが否定されています。Nano Bananaの参照画像リクエストは、operation: "image-to-image" を指定して /v1/images/generations で公開されています。/v1/images/edits はそれらの正しいパスではありません。

このリクエストは画像生成ガイドからのもので、モデルとして nano-banana-2 を使用しています：

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

この形式で従うルール：

• ドキュメント化された参照フィールドを正確に送信する。 JSONでは image_url、image_urls、または reference_image_urls を使用してください。最上位レベルの images[] や file_id は送信しないでください。これらは編集フローに属しており、このエンドポイントでは拒否されます。
• 公開URLを使用する。 埋め込み認証情報、フラグメント、プライベートネットワークホストを含まない http または https である必要があります。処理開始前に期限切れになる可能性のある署名付きURLは避けてください。
• プライベートソースにはマルチパートを使用する。 ドキュメントでは、プライベートまたはヘッダー保護されたソースに対してマルチパートの image ファイルを提供しています。
• resolution をモデルに合わせる。 ドキュメントによると、nano-banana-pro には含まれる可能性があり、nano-banana-edit は省略すべきです。また、ドキュメントでは nano-banana-edit が参照画像モデルとして名前が挙がっていますが、そのIDは2026年10月2日に取得したカタログには含まれていません。使用前に /v1/models でIDを検証してください。

ソース記事のchat-completions編集例は削除されました。ライブレコードには、nano-banana-2 および nano-banana-pro で受け入れられる形式として gemini_generate_content がリストされています。証拠にはchat-completionsの画像編集パスはドキュメント化されていません。

マスクベースのインペインティングや strength などのパラメータは、Nano Bananaについては証拠にドキュメント化されていません。送信前に GET /v1/models/{model} を確認してください。

画像リクエストがタスクになる場合とポーリング方法

画像作成コールは同期または非同期であり、レスポンスによってどちらであるかがわかります。非同期ジョブガイドには、トリガーフィールドとして task_id、status: "pending"、または poll_url がリストされています。これらが出現した場合、data[] 配列は空であり、処理は進行中です。

証拠には、async: true リクエストフラグは gpt-image-2 および公式のFLUX/BFL画像モデルに対してのみドキュメント化されています。Nano Banana IDに対してはドキュメント化されていません。Nano Bananaリクエストに追加しないでください。タスクレスポンスが返された場合はそれを処理し、非同期動作が必要な場合はモデル詳細を確認してください。

レスポンスが遅いためにブラウザを更新してcreateコールを再送信する状況を想像してください。これで2回分の生成料金を支払うことになります。ドキュメントによると、重複生成のほとんどは、この再試行から発生します。以下の順序に従ってください：

1. IDを即座に保存する。 id または task_id、poll_url、モデル、エンドポイント、および独自のジョブIDを保存します。id と task_id は同じ値です。
2. URLをポーリングする。 poll_url が存在する場合はそれを使用します。それ以外の場合は固定ルートを呼び出します：

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. 5〜10秒ごとにポーリングする。 ガイドによると、これは長いメディアジョブには通常十分です。
2. ステータスを把握する。 pending、processing、completed、failed があります。キャンセルされたタスクは failed となり、cancelled: true が含まれます。
3. 終了ステータスで停止する。 completed の場合、data[].url を読み取ります。非同期画像の戻り値はURLのみであり、b64_json にはなりません。failed の場合、error と error_details を読み取ります。
4. タイムアウトを安全に処理する。 レスポンスを確認する前にcreateコールがタイムアウトした場合は、request_id を確認し、再試行する前にタスクを探してください。タスクIDを保存した場合は、ポーリングを再開します。ステータスポーリングが失敗した場合は、バックオフを伴ってそのポーリングを再試行し、再作成はしないでください。

ステータスの読み取りは、失敗したタスクであってもHTTP 200を返します。失敗したタスクには、status、type、code、message、param、retryable を含む error_details が含まれる場合があります。例えば、param: "size" を伴う error_details.status: 400 は、リクエストの修正が必要であることを意味します。ポーリング自体が失敗したわけではありません。失敗した生成を再試行すると新しいタスクが作成され、新しい料金が発生する可能性があります。

予期されるエラーと対処法

エラーはHTTPステータスと code で処理し、message で処理しないでください。エラーハンドリングガイドによると、メッセージは予告なく変更される可能性があります。Chat CompletionsとResponsesはOpenAIスタイルの error オブジェクトを使用しますが、GeminiとAnthropicの形式は独自の形状を維持します。すべてのTokenLab APIで1つのパーサーを共有しないでください。

ステータス / コード	主な原因	対処法
400, param: "model"	モデルの指定なし	model を送信。/v1/models?recommended_for=image でIDをリスト。
400 unsupported field, or unsupported_parameter	モデルがドキュメント化していないフィールド（例：対応していないモデルでの resolution）	フィールドを削除するかモデルを切り替える。変更せずに繰り返さない。
400 on a reference image	間違ったエンドポイント、またはプライベート/期限切れのURL	image_urls を指定して /v1/images/generations を使用。公開された安定したURLを使用。
401 invalid_api_key or expired_api_key	キーの欠落、取り消し、または期限切れ	キーを置き換える。
402 insufficient_balance or quota_exceeded	残高不足、またはキーの制限到達	資金を追加、キーの制限を引き上げ、または安価なモデルを選択。
403 model_not_allowed	キーがそのモデルを使用できない	キーのモデルリストを更新。
404 model_not_found	不明または利用不可のID	/v1/models を読み取り、現在のIDを使用。
413 payload_too_large	リクエストまたはファイルが大きすぎる	入力を削減。
429 rate_limit_exceeded	ウィンドウ内のリクエスト過多	Retry-After を待ってから再試行。
500–504, all_channels_failed	サービスまたは供給の問題	retryable が true の場合のみ再試行。retry_after を尊重し、試行回数を制限。

503 all_channels_failed は必ずしも障害を意味しません。retryable が false で retry_after が欠落している場合、選択したDeliveryティアに供給がありません。リクエストを繰り返しても無駄なため、まず GET /v1/models を確認してください。

タスクポーリングには独自の失敗があります：

• 404 async_task_not_found: タスクが期限切れか存在しません。保存された task_id と poll_url を確認してください。
• 403 task_not_owned: タスクが別のワークスペースに属しています。APIキーがどのワークスペースに属しているかを確認してください。
• メディアURLのない完了タスク: 失敗として扱ってください。IDを保持し、サポートに連絡してください。

サポートに連絡する際は、request_id、task_id、存在する場合は billing_transaction_id、エンドポイント、モデル、時間、フィールド名を送信してください。キー、プライベートメディア、署名付きURLは決して送信しないでください。

画像リクエストの課金決定方法

3つの有料Nano Banana IDはすべて per_image 単位を使用するため、主な料金はモデルの per_request 価格です。課金ガイドには、その周辺のルールが追加されています：

• 1結果につき1課金。 各完了リクエストは、それを生成した配信オプションに対して1回課金されます。TokenLab Verified はTokenLabの公開価格を使用します。Official は公式価格レイヤーを使用します。 Auto はまずVerifiedを試し、次にOfficialを試します。
• ティアが最終数値を設定。 ライブ価格範囲（nano-banana-2 は$0.0225〜$0.0755、nano-banana-pro は$0.067〜$0.12）は、1つの固定価格ですべてのリクエストをカバーできないことを示しています。解像度ティアが主な要因ですが、モデルの価格エントリで確認してください。
• タスクが先に予約。 非同期タスクは、受け入れ時に推定コストを予約する場合があります。完了したタスクは1回課金され、失敗したタスクは保留中の金額を解放または返金します。課金ガイドによると、失敗したタスクは課金されません。
• ダッシュは無料ではない。 Modelsページにおいて、TokenLab価格列のダッシュは、現在Verifiedオファーが利用できないことを意味します。

課金を確認するには、以下の場所を使用してください：

1. GET /v1/models/:model/pricing または Pricing API（現在の価格）。
2. コンソール（有料生成を確定する前の最大見積もりを表示）。
3. Usage（モデルごとの最終請求額）。
4. レスポンスやタスク内の billing_transaction_id、および X-Billing-Transaction-ID ヘッダー。ストリーミングや一部のネイティブ形式では、ヘッダーにのみ表示される場合があります。

タスク終了後にUsageに最終請求額や解放額が表示されない場合は、Request IDとタスクIDを support@tokenlab.sh まで送信してください。本記事の価格をコードにコピーしないでください。課金ガイドでは、アプリケーションがコストを表示または比較する必要があるときに現在の価格を読み取るよう指示しています。

FAQ

image-to-imageリクエストにはどのNano BananaモデルIDを送信すべきですか？

ライブレコードには nano-banana-2、nano-banana-2-lite、nano-banana-pro の image-to-image がリストされています。ドキュメントには nano-banana-edit も記載されていますが、2026年10月2日に取得したカタログには含まれていません。operation: "image-to-image" および image_urls を指定して /v1/images/generations にIDを送信してください。証拠には品質比較がないため、自身の画像で小規模なテストを実行してください。

なぜ画像リクエストが画像ではなくtask_idを返したのですか？

createコールが非同期タスクとして実行されました。レスポンス内の task_id、status: "pending"、または poll_url を探してください。それらのフィールドを保存し、ステータスが completed または failed になるまで、5〜10秒ごとに poll_url または GET /v1/tasks/{id} をポーリングしてください。待機中に2回目のcreateリクエストを送信しないでください。

Nano Bananaモデルからbase64出力を取得できますか？

response_format フィールドは url または b64_json を受け入れ、同期リクエストは data[].b64_json を返すことができます。非同期画像の戻り値は、どのような形式を要求したかに関わらずURLのみです。フィールドはモデルによって異なるため、選択したモデルの詳細を確認して b64_json を受け入れるか確認してください。

失敗した画像タスクは課金されますか？

課金ガイドによると、失敗したタスクは課金されず、保留中の予約は解放または返金されます。失敗した生成を再試行すると新しいタスクが作成され、新しい料金が発生する可能性があります。billing_transaction_id と task_id を使用してUsageで結果を確認してください。

TokenLabダッシュボードでキーを作成し、上記のtext-to-imageリクエストを nano-banana-2-lite で送信し、Usageで料金を確認してください。