nanobanana-pro 接口

本平臺對外提供模型 ID 爲 nanobanana-pro 的異步圖片生成接口。

本文檔面向客戶端調用方，重點說明公開請求路徑、認證方式、請求參數，以及任務結果的返回契約。

說明：

提交任務：POST /v1/images/create
查詢任務：GET /v1/tasks/{task_id}
模型 ID：nanobanana-pro
執行方式：異步任務
典型場景：高質量文生圖、高質量圖像編輯、搜索增強生成

1. 接口概覽

請求方法：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

請求頭說明：

請求頭	必填	說明
`Authorization`	是	平臺 API Key，格式：`Bearer sk-xxxxxx`
`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 頂層參數說明

字段	類型	必填	說明
`model`	string	是	固定傳 `nanobanana-pro`
`callback_url`	string	否	任務終態回調地址，僅支持 `https`，最大長度 `2048`，本地、內網及私網目標會被拒絕
`input`	object	是	圖片生成參數

3.2 `input` 參數說明

字段	類型	必填	說明
`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 爲 best-effort 語義；如果轉碼不可用，任務仍可能成功，並返回模型原始輸出格式
平臺始終採用異步任務鏈路
任務結果主契約爲 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": []
}

字段說明：

字段	類型	說明
`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"

狀態說明：

狀態	說明
`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，任務進入終態後，網關會向該地址發送 POST 請求。回調 body 與任務查詢接口的響應結構一致。

回調約束：

僅支持 https 地址
最大長度 2048
localhost、.local 以及明顯的私網目標會被拒絕
單次投遞超時 10s
失敗後最多重試 2 次，總計最多投遞 3 次

8. 參數約束與說明

prompt 不能爲空
image_urls 最多 14 張
image_urls 必須是服務端可訪問的 https URL
單張輸入圖最大 10MB
aspect_ratio、resolution、output_format 需要嚴格使用文檔枚舉值
enable_web_search 爲可選能力，僅在確實需要外部上下文時開啓

nanobanana-pro 接口

On this page