nanobanana 接口

本平台对外提供模型 ID 为 nanobanana 的异步图片生成接口。

本文档面向客户端调用方，重点说明公开请求路径、认证方式、请求参数，以及任务结果的返回契约。

说明：

提交任务：POST /v1/images/create
查询任务：GET /v1/tasks/{task_id}
模型 ID：nanobanana
执行方式：异步任务
典型场景：文生图、图像编辑

当前范围：

仅覆盖 nanobanana 的任务提交与任务查询
不提供同步图片直返模式
不支持 input.resolution
不支持 input.enable_web_search

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",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A modern editorial illustration",
    "image_urls": [],
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}

3.1 顶层参数说明

字段	类型	必填	说明
`model`	string	是	固定传 `nanobanana`
`callback_url`	string	否	任务终态回调地址，仅支持 `https`，最大长度 `2048`，本地、内网及私网目标会被拒绝
`input`	object	是	图片生成参数

3.2 `input` 参数说明

字段	类型	必填	说明
`prompt`	string	是	生成提示词，建议尽量控制在 `2000 tokens` 以内
`image_urls`	`array<string>`	否	参考图 URL 列表。不传或传空数组表示文生图，非空表示图像编辑，最多 5 张
`aspect_ratio`	string	否	输出比例，可选值：`1:1`、`3:2`、`2:3`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`
`output_format`	string	否	输出格式偏好，可选值：`png`、`jpeg`

不支持的字段：

input.resolution
input.enable_web_search

说明：

output_format 为 best-effort 语义；如果转码不可用，任务仍可能成功，并返回模型原始输出格式
该模型更适合少量参考图场景

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",
    "input": {
      "prompt": "A playful landing page illustration for a fintech startup",
      "aspect_ratio": "16:9",
      "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",
    "input": {
      "prompt": "Transform this food photo into a stylized poster",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "aspect_ratio": "4:3",
      "output_format": "jpeg"
    }
  }'

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 最多 5 张
image_urls 必须是服务端可访问的 https URL
单张输入图最大 10MB
aspect_ratio 与 output_format 需要严格使用文档枚举值
图像编辑场景下，建议尽量减少参考图数量

nanobanana 接口

On this page