nanobanana-2 API

このプラットフォームでは、公開モデル ID nanobanana-2 向けに非同期の画像生成エンドポイントを提供しています。

このドキュメントはクライアント側で統合を行う開発者向けに、公開リクエストパス、認証方式、リクエストパラメータ、およびタスク結果の受け取り方を説明します。

概要:

タスク作成: POST /v1/images/create
タスク照会: GET /v1/tasks/{task_id}
モデル ID: nanobanana-2
実行方式: 非同期タスク
想定ユースケース: テキストから画像への生成、画像編集、検索拡張付き生成

1. API 概要

HTTP メソッド: POST
リクエストパス: /v1/images/create
Content-Type: application/json
結果受け取り方法:
- 即時レスポンスではタスク受理情報のみ返ります
- 最終結果は /v1/tasks/{task_id} のポーリング、または callback_url で取得します

2. 認証とヘッダー

ヘッダー例:

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

ヘッダー詳細:

Header	必須	説明
`Authorization`	はい	`Bearer sk-xxxxxx` 形式のプラットフォーム API キー
`Content-Type`	はい	`application/json` である必要があります

3. タスク作成

リクエストボディ例:

{
  "model": "nanobanana-2",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A cinematic street scene at dusk, realistic lighting",
    "image_urls": [],
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "output_format": "png",
    "enable_web_search": false
  }
}

3.1 トップレベルパラメータ

Field	Type	必須	説明
`model`	string	はい	`nanobanana-2` を指定します
`callback_url`	string	いいえ	タスク終端状態で呼び出す HTTPS コールバック URL。最大長は `2048`。localhost・ローカルネットワーク・プライベートネットワーク宛ては拒否されます
`input`	object	はい	画像生成パラメータ

3.2 `input` パラメータ

Field	Type	必須	説明
`prompt`	string	はい	生成プロンプト。可能であれば `2000 tokens` 以内に収めてください
`image_urls`	`array<string>`	いいえ	参照画像 URL。空または省略時はテキストから画像への生成、指定時は画像編集になります。最大 14 枚
`aspect_ratio`	string	いいえ	出力アスペクト比。対応値: `1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1`
`resolution`	string	いいえ	出力解像度。対応値: `0.5k`, `1k`, `2k`, `4k`
`output_format`	string	いいえ	希望出力形式。対応値: `png`, `jpeg`
`enable_web_search`	boolean	いいえ	検索拡張付き生成を有効化します。既定値は `false`

補足:

output_format はベストエフォートです。変換できない場合でも、モデル既定の形式で成功することがあります
プラットフォーム側では常に非同期タスクフローを使用します
主な結果取得契約は data[].url です

4. リクエスト例

4.1 テキストから画像への生成

curl -X POST "https://direct.reachapi.ai/v1/images/create"   -H "Authorization: Bearer YOUR_REACH_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "nanobanana-2",
    "input": {
      "prompt": "A futuristic city at sunset, cinematic lighting, highly detailed",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

4.2 画像編集

curl -X POST "https://direct.reachapi.ai/v1/images/create"   -H "Authorization: Bearer YOUR_REACH_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "nanobanana-2",
    "input": {
      "prompt": "Turn this sneaker photo into a premium e-commerce hero shot",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "output_format": "jpeg"
    }
  }'

4.3 検索拡張付きリクエスト

curl -X POST "https://direct.reachapi.ai/v1/images/create"   -H "Authorization: Bearer YOUR_REACH_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "nanobanana-2",
    "input": {
      "prompt": "Create a news-style illustration about global shipping trends",
      "resolution": "1k",
      "enable_web_search": true
    }
  }'

5. タスク作成レスポンス

レスポンス例:

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

レスポンスフィールド:

Field	Type	説明
`code`	integer	プラットフォームの業務ステータスコード
`msg`	string	エラーメッセージまたは状態メッセージ
`status`	string	初期タスク状態。通常は `queued`
`task_id`	string	後続照会に使う一意なタスク ID
`data`	array	送信直後は空

6. タスク状態の照会

リクエスト例:

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx"   -H "Authorization: Bearer YOUR_REACH_API_KEY"

タスク状態:

Status	説明
`queued`	受理済みで実行待ち
`generating`	生成中
`success`	正常完了
`failed`	失敗

成功レスポンス例:

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/image-1.png"
    }
  ]
}

失敗レスポンス例:

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

7. コールバック配信

タスク作成時に callback_url を指定すると、タスクが終端状態になった時点でゲートウェイがその URL に POST を送信します。コールバックボディはタスク照会レスポンスと同じ JSON 構造です。

コールバック制約:

https URL のみ利用可能
最大長: 2048
localhost、.local、明らかなプライベートネットワーク宛ては拒否
1 回あたりの配信タイムアウトは 10s
失敗時は最大 2 回再試行し、合計 3 回まで配信

8. 制約と注意点

prompt は空にできません
image_urls は最大 14 枚です
image_urls はサーバーから到達可能な https URL である必要があります
各入力画像は 10MB 以下にしてください
aspect_ratio、resolution、output_format はドキュメント記載の列挙値を使ってください
enable_web_search はリアルタイムの外部文脈が必要な場合にのみ有効化するのが推奨です

nanobanana-2 API

On this page