Nano Banana 2 Lite API の使い方：curl、Python、そして実行可能なリクエスト

Nano-Banana-2-Lite は hiapi 上の Nano-Banana 画像モデルファミリーにおけるエコノミー版です。上位モデルと同じタスクベースのワークフローを採用しながら、1 枚あたりの価格がより低く、テキストからの画像生成と参照画像による編集の両方をサポートします。このガイドでは、タスクの作成、タスクのポーリング、結果のダウンロードという一連の完全かつ実行可能な統合フローを、curl と Python の両方で示し、Nano-Banana-2 や Nano-Banana-Pro とは異なるスキーマの詳細についても説明します。

構築するものと準備するもの

目標：Nano-Banana-2-Lite にプロンプトを送信し、画像生成を待ち、ディスクに保存します。

必要なものは 1 つだけです：hiapi の API キー（sk-...）。hiapi ダッシュボードから取得してください。1 枚あたりの費用は 料金ページ と Nano Banana 2 Lite モデルページ に記載されています。

hiapi 上のすべての画像モデルは統一された async task API で動作します：POST /v1/tasks でタスクを作成し、その後 GET /v1/tasks/{id} をポーリングするか、タスク完了時に webhook を受け取ります。

最小限の実行可能なリクエスト（curl）

タスクを作成します：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "夜明けの灯台の水彩イラスト、柔らかなパステルカラーの配色",
      "aspect_ratio": "3:2"
    }
  }'

レスポンスに含まれるタスク id は data.taskId にあります。それをポーリングします：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status が "success" のとき、画像 URL は data.output[0].url にあります。すぐにダウンロードしてください——出力 URL は署名付きで有効期限（expireAt）があるため、リンクではなくバイト列を保存します。

API 自体の検証に由来する、つまずきやすいスキーマのルールが 2 つあります：

• モデル id は大文字小文字を区別します。 "model": "nano-banana-2-lite" は 400 MODEL_UNAVAILABLE（"model not available via /v1/tasks"）を返します。正確な id Nano-Banana-2-Lite を使用してください。
• prompt と aspect_ratio はどちらも必須です。 いずれかを省略すると 400 INVALID_REQUEST と missing required field メッセージを受け取ります。有効な aspect_ratio の値：auto、1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:4、4:1、1:8、8:1。

Python での同じフロー

SDK は不要です——タスク API は HTTPS 上の純粋な JSON です：

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Create the task
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

参照画像による編集：image_input ではなく image_urls

Nano-Banana-2-Lite は画像編集をサポートしますが、その参照画像フィールドは image_urls です——最大 10 個の公開アクセス可能な URL を含む配列です：

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "背景を清潔な白いスタジオ背景に置き換え、商品は変更しないでください",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

これはこのファミリーで最もつまずきやすい点です：Nano-Banana-2 と Nano-Banana-Pro は同じ目的で image_input を使用しますが、Lite はそのフィールドを拒否します（additional properties 'image_input' not allowed）。input_urls、images、reference_images といったフィールド名は 3 つのモデルすべてで拒否されます。階層間でコードを移行する場合、通常必要となる唯一の変更はこのフィールド名の変更です。

Lite vs. Nano-Banana-2 vs. Pro：重要なスキーマの違い

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
必須入力	prompt、aspect_ratio	prompt	prompt
参照画像	image_urls（≤10）	image_input	image_input
resolution 制御	受け付けない	受け付ける	受け付ける

Lite はインターフェースを極めてシンプルに保ちます：prompt、アスペクト比、任意の参照画像。 resolution、seed、n、negative_prompt はありません——いずれかを送信すると additional properties ... not allowed の検証エラーになります。明示的な解像度制御（1K/2K/4K）やより高い忠実度の階層が必要な場合は、Nano-Banana-2 または Nano-Banana-Pro にアップグレードしてください。バッチ生成——サムネイル、下書き、反復ループ、バッチバリエーション——を行う場合、Lite の低い 1 枚あたりのコストこそがその存在意義です。

本番環境向けの堅牢化

可能な限りポーリングではなく webhook を使用してください。 タスク作成時に callback ブロックを追加すると、hiapi は最終結果をあなたのエンドポイントに POST します：

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when は "final" のみを受け付けます——成功または失敗にかかわらず、callback は 1 回だけ届きます。ポーリングはスクリプトや notebook に適しています。callbacks はポーリングループやタイムアウトを管理する必要がないため、サーバーに適しています。どうしてもポーリングする場合は、2〜5 秒の間隔と（Python の例のように）ハードな締め切りを設ければ十分です。

2 層のエラーを処理してください。 リクエストレベルの失敗は HTTP エラーとして返されます——無効または未認証のキーは 401 と {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} を返し、スキーマエラーは 400 INVALID_REQUEST と正確な検証メッセージを返します。タスクレベルの失敗は status: "fail" とタスク自身の error オブジェクトとして届きます。コード内で両方のパスを処理してください。

リトライを冪等にしてください。 タスク作成は冪等ではありません——タイムアウトした作成リクエストをリトライすると、2 つのタスク（および 2 回の課金）が発生する可能性があります。taskId を受け取ったらすぐに永続化し、再起動後は既存の id をポーリングし続け、盲目的に再作成しないようにしてください。

URL ではなくバイト列を保存してください。 出力 URL は期限切れになります。画像に対して他のことを行う前に、必ずダウンロードして自分のストレージに保管してください。

関連記事

• Nano Banana 2 Lite モデルページ — パラメータ、リアルタイム価格、playground
• GPT Image 2 vs Nano Banana 2：同じ prompt を使った並列比較
• hiapi 上で Nano-Banana を使ってキャラクターの一貫性を保つ
• hiapi ドキュメント と 料金

FAQ

なぜ "model not available via /v1/tasks" が返ってくるのですか？ モデル id は大文字小文字を区別します。正確に Nano-Banana-2-Lite を使用してください。小文字の変種は拒否され、400 MODEL_UNAVAILABLE が返されます。

Nano-Banana-2-Lite は画像から画像への編集をサポートしていますか？ はい。参照画像を image_urls 配列に渡してください（最大 10 個の URL）。背景の置き換え、スタイル転送、および prompt 駆動の指示ベースの編集ワークフローを処理できます。

なぜ私の Nano-Banana-2 コードが Lite 上で "additional properties 'image_input' not allowed" エラーで失敗するのですか？ 階層によって参照画像のフィールド名が異なります：Lite は image_urls を期待し、Nano-Banana-2 と Pro は image_input を期待します。階層を切り替える際はフィールド名を変更してください。

resolution、seed、画像枚数を設定できますか？ Lite ではできません——その入力スキーマは prompt、aspect_ratio、image_urls のみを受け付けます。1K/2K/4K の resolution 制御が必要な場合は、Nano-Banana-2 または Nano-Banana-Pro を使用してください。

出力画像 URL の有効期間はどれくらいですか？ これらは有効期限タイムスタンプ付きの署名 URL です（出力オブジェクト内の expireAt）。すぐにバイト列をダウンロードして自分のストレージに保存してください。タスク出力へのホットリンクは決して行わないでください。

401 permission_denied はどういう意味ですか？ API キーが無効であるか、このモデルの使用が許可されていません。ダッシュボードでキーを確認し、Authorization: Bearer sk-... の形式で送信されていることを確認してください。

Nano-Banana-2-Lite は 1 枚あたりいくらですか？ 従量課金で、画像ごとに課金され、Nano-Banana ファミリーの中で最も低コストの階層として位置付けられています。現在の料金は 料金ページ を参照してください。