HiAPI API で Nano-Banana-2-Lite を使う方法：curl、Python、そして動作するリクエスト

Nano-Banana-2-Lite とは何か、いつ使うべきか

Nano-Banana-2-Lite は、HiAPI 上の Nano-Banana ファミリーにおける超低コスト帯のモデルです。高い並行性が求められ、コストに敏感な画像生成シーン、つまり最高の忠実度よりも予測可能なコストと高速なイテレーションを重視する場面に向けられています。機能のプロトタイプ作成、サムネイルやバリエーションの一括生成、あるいはより軽量なモデルを許容できるバックグラウンドタスクを実行しているなら、この帯域が出発点として適しています。

出力がより大きなパイプラインの一部に過ぎない場合に使用してください。たとえば、草案ビジュアル、プレースホルダー画像、一括実験、あるいは低コストで大量の候補を得る必要がある A/B テストなどです。最終的なキービジュアルや最高のディテールが求められる場面では、より大きな帯域にアップグレードしてください。API インターフェースは変わらないため、統合を書き直すことなくモデルを切り替えられます。

前提条件とリクエスト構造

Nano-Banana-2-Lite を呼び出す前に、以下を確認してください：

• HiAPI アカウントと API キー。環境変数（たとえば HIAPI_API_KEY）に保存してください。ソースコード管理にコミットしないでください。
• 初回テスト用の curl が使えるターミナル、およびスクリプト版用の Python 3.8+ と requests ライブラリ。
• 生成したい画像を説明するプロンプト。まずはシンプルに始め、後から参照入力を追加できます。

HiAPI へのすべてのリクエストは同じ構造に従います：JSON ボディを伴う POST をモデルエンドポイントに送信します。リクエストボディにはモデル名、プロンプト、および任意のパラメータを含めます。生成は非同期であるため、送信呼び出しはタスク識別子を返し、その後そのタスクをポーリングします。レスポンスは JSON で、エラーにはステータスコードと記録可能なメッセージが含まれます。

ペイロードには少なくとも model を nano-banana-2-lite に設定し、prompt を指定する必要があります。reference_images や出力設定などの任意フィールドについては、後のセクションで説明します。

動作する curl リクエスト

以下は、基本的なタスクを送信するための完全でコピー＆ペースト可能な例です。プレースホルダーのプロンプトを自分の内容に置き換えてください。

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

レスポンスにはタスク id と status フィールドが含まれます。新しく送信されたタスクは通常 queued または processing を返します。その id を保存してください。ポーリング手順で使用します。401 が返された場合は、HIAPI_API_KEY がシェルでエクスポートされているか確認してください。422 が返された場合は、エラーメッセージを確認して問題のあるフィールドを特定してください。

Python で同じリクエストを送信する

curl 呼び出しを Python に移植して、スクリプトやサービスに組み込みます。この例では requests を使用し、キーを環境変数から読み取ります。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

リクエストボディを辞書に保持しておくことで、呼び出しを書き直すことなく任意フィールドで拡張できます。送信ステップでは、重い処理は非同期で行われるため、30 秒のタイムアウトが妥当です。

任意の参照入力を追加する

参照入力を使うと、視覚的なコンテキストで生成を誘導できます。HiAPI では、それらを同じ JSON ボディ内の reference_images 配列として添付します。各エントリは公開アクセス可能な URL または base64 データ URI です。構図を維持したい、スタイルを合わせたい、あるいは商品画像を複数のバリエーション間で一貫させたい場合に参照画像を使用してください。

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

参照画像は、有効なシグナルを提供できる場合にのみ含めてください。各参照画像は転送が必要な追加データであり、単純なプロンプトを薄める可能性があります。純粋なテキストからの画像生成タスクでは、このフィールドを完全に省略してください。参照画像を実際に使用する場合は、関連性を保ち、数は少なくしてください。厳選された 1～2 枚の画像は、通常、大きなセットよりも優れています。

非同期結果をポーリングする

画像生成は非同期です：タスクを送信し、ステータスが終態になるまでタスクエンドポイントをポーリングします。curl と Python でパターンは同じです。

curl を使用する場合、タスク id でタスクを確認します：

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Python では、API を頻繁に叩きすぎないよう、遅延を伴うループでポーリングをラップします：

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

短い間隔から始め、多数のタスクをポーリングする場合は段階的にバックオフしてください。常に最大試行回数を設定し、スタックしたタスクがワーカープロセスを永久にブロックしないようにしてください。failed は終態として扱い、エラーメッセージを記録してください。

出力をダウンロードして検証する

タスクが成功すると、レスポンスには 1 つ以上の出力 URL が含まれます。そのファイルを取得してローカルに保存し、得られた内容を検証します。

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

ダウンロードした内容に対して基本的なチェックを行います：コンテンツタイプが画像であること、ファイルサイズがゼロでなく妥当であること、一度開いてプロンプトに合致していることを確認します。タスク id をローカルファイル名と一緒に記録し、あらゆる素材をそのリクエストまで追跡できるようにします。

本番投入前のコストと障害チェックリスト

Nano-Banana-2-Lite は超低コスト帯で価格設定されており、課金はプラットフォームの標準的な画像生成の計量に従います。正確な料率については、仮定をハードコードするのではなく、ウェブサイト上の現在の価格パネルを確認してください。

公開前に、以下の習慣を身につけてください：

• バックオフ付きリトライ。 一時的なエラー（タイムアウト、5xx）は遅延を増やしながら少数回リトライします。4xx の検証エラーはリトライしないでください。
• ポーリングを制限する。 固定間隔と最大試行回数を使用します。最終状態と所要時間を記録します。
• タスク id とプロンプトを記録する。 タスク id、プロンプト、モデル、および任意の参照入力を各出力と一緒に保存し、実行の再現や監査を可能にします。
• 入力を早期に検証する。 送信前にプロンプトの長さと参照 URL を確認し、無駄なタスクを避けます。

これらのチェックがあれば、Nano-Banana-2-Lite は一括およびバックグラウンド生成のための予測可能で低コストな主力ツールとなります。最新のパラメータと料率の詳細については、HiAPI 上のモデルページをご覧ください。