nanobanana-pro API

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

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

概要:

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

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-pro",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A premium product hero shot",
    "image_urls": [],
    "aspect_ratio": "1:1",
    "resolution": "2k",
    "output_format": "png",
    "enable_web_search": false
  }
}

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

Field	Type	必須	説明
`model`	string	はい	`nanobanana-pro` を指定します
`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`
`resolution`	string	いいえ	出力解像度。対応値: `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-pro",
    "input": {
      "prompt": "A luxury perfume bottle hero image on a marble surface",
      "aspect_ratio": "4:5",
      "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-pro",
    "input": {
      "prompt": "Turn this handbag photo into a premium campaign poster",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "aspect_ratio": "4:5",
      "resolution": "4k",
      "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-pro API

On this page