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