Nano Banana Pro 生图 API

快速开始：第一次生成图片

1. 准备账户与密钥

   登录后在开发者控制台创建 API Key，并确认账户有足够积分。保存完整密钥，关闭后无法再次查看。

2. 选择模型与参数

   在侧边栏选择一个模型，复制该页的请求示例。将 YOUR_API_KEY 替换为自己的密钥，修改 prompt 为画面描述。先使用示例默认参数和一张图片。

3. 确认积分报价

   把相同请求发送到 POST /api/v1/images/quote，查看返回的 estimatedPoints。报价不生成图片，也不冻结积分。

4. 提交生成任务

   发送到 POST /api/v1/images/generations。每次新任务更换 Idempotency-Key；返回 HTTP 202 后保存 taskId，此时图片仍在生成中。

5. 查询并下载图片

   每 3–5 秒请求一次 GET /api/v1/tasks/{taskId}。将路径中的占位符替换为刚才的任务 ID。任务完成后读取 task.images[].url，拼接本站域名并携带同一密钥下载。

请求与响应示例在桌面端右侧展示，手机端位于参数说明之后。遇到报错？查看常见错误处理。

创建与使用密钥

1. 进入开发者控制台的 API 密钥页面，创建密钥并设置便于识别的名称。
2. 复制完整密钥并保存在自己的服务端环境变量中；页面只展示一次完整密钥。
3. 在每次 API 请求中携带下面的鉴权头，包括任务查询和图片下载。
4. 密钥不再使用或意外泄露时，在开发者控制台撤销，并为自己的应用更换新密钥。

所有调用使用请求头 Authorization: Bearer YOUR_API_KEY，JSON 请求还需 Content-Type: application/json。请在自己的服务端使用密钥，不要放入网页、公开代码或 URL。

API Key 只授予生图接口访问权限。撤销立即影响后续请求；同账户其他有效密钥仍可查询已提交的 API 任务。

选择模型与请求参数

侧边栏模型文档列出各模型的可用选项。modelId 使用本站业务标识，不要用展示名称替代；也可以携带密钥调用 GET /api/v1/models 获取当前账户可用模型。

以下选项由 Nano Banana Pro 的当前能力配置生成。 第一版支持文生图，暂不支持参考图、视频或回调地址。

报价与积分

向 POST /api/v1/images/quote 发送与生成接口相同的参数，获得 estimatedPoints。报价不创建任务、不冻结积分。

API 与网页共用余额、会员价格及失败退款规则。提交时冻结报价积分，结束后结算实际消耗。未结算时 chargedPoints 为 null；结算后为实际扣除的积分，失败是否收费沿用网站规则。

查询任务与下载图片

queued 表示排队，processing 表示生成中；这两种状态继续等待。succeeded 表示成功，partial 表示部分成功，failed 表示失败，进入这三种状态后停止轮询。下载前检查 task.images 是否有结果；没有图片时查看错误说明。

请求 GET /api/v1/tasks/{taskId}。任务状态可能为 queued、processing、succeeded、partial 或 failed。部分成功时仍可能返回图片，积分以 settled 和 chargedPoints 为准。

task.images[].url 是本站的相对路径，拼接本站域名后携带相同鉴权请求头下载。API 只能查询当前账户自己的 API 任务；全部创作记录和消耗可在任务日志与积分流水查看。

幂等重试与调用规则

每个新任务使用独立的 Idempotency-Key。网络超时重试时保持幂等键和参数不变，避免重复创建或冻结积分；更改参数会返回 409。幂等键为 8–128 位字母、数字或 ._:-，同账户多个密钥共用幂等范围。删除任务后不能依赖原键防止重复提交。

API Key 接入不受网页会员等级的任务并发上限限制，可同时提交多个任务；任务实际完成时间取决于排队与处理进度。

有效 API Key 的模型查询、报价、提交、任务查询和图片下载不设请求频率上限。建议每 3–5 秒查询一次生成中的任务，避免无效轮询；实际完成时间取决于排队与处理进度。无效密钥的重复认证尝试仍受防滥用保护。

错误处理

错误响应统一包含 error 与 code。遇到提交超时，先使用原幂等键重试，避免重复付费。