VISIONARY
Visionary OpenAPI

API 文档

使用统一任务接口接入 Nano Banana。密钥只应保存在你的服务端，不要写入浏览器前端。

01 · 快速开始

用一个请求提交图像任务

在 Visionary 创建 API Key 后，通过 Bearer Token 从你的服务端发起请求。生产环境应为每次业务请求生成并复用稳定的 client_request_id。

POSThttps://aicat.fun/v1/images/generations
curl https://aicat.fun/v1/images/generations \
  -H "Authorization: Bearer VISIONARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "生成一张未来感品牌海报",
    "size": "16:9",
    "resolution": "1K",
    "client_request_id": "your-order-20260720-001"
  }'
服务端调用

API Key 不应出现在网页源码、浏览器请求或公开仓库中。

任务式响应

提交成功后保存 task_id，再通过任务查询接口读取最终状态。

02 · 开发指南

鉴权、幂等与结果读取

  1. 请求头使用 Authorization: Bearer VISIONARY_API_KEY。
  2. 网络重试时复用相同的 client_request_id，避免重复提交和重复扣费。
  3. 提交接口返回 task_id 后再查询状态，不要持续创建新任务。
  4. 任务成功后，从结果对象读取图片 URL，并及时保存到自己的对象存储。
{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01JZVISIONARY",
    "retry_after": 3
  }]
}
03 · 图像生成

Nano Banana 接口

Pro、Pro CL 和 2 Lite 共用同一提交接口，通过 model 选择能力与速度。

POST/v1/images/generations
字段类型必填说明
modelstring是支持 nano-banana-pro、nano-banana-pro-cl、nano-banana-2-lite。
promptstring是图像生成或编辑指令。
imagesstring[]否可传多张 HTTPS 参考图 URL。
sizestring否例如 1:1、3:2、2:3、16:9、9:16。
resolutionstring否2 Lite 固定 1K；Pro 与 Pro CL 支持 2K、4K。
 
{
  "model": "nano-banana-2-lite",
  "prompt": "快速生成一张品牌概念插画海报",
  "images": ["https://your-cdn.com/input.png"],
  "size": "16:9",
  "resolution": "1K",
  "optimizeChineseText": false
}
04 · 可靠性

高并发与安全重试

指数退避

收到 429、503 或可恢复网络错误时，按 retry_after 或指数退避重试。

限制轮询

遵循服务端建议的查询间隔，避免并发轮询放大流量。

幂等请求

相同业务订单始终复用 client_request_id，防止重复任务。

错误脱敏

不要把 API Key、原始上游响应或内部地址写入客户端日志。

05 · 价格指南

按模型与清晰度扣除积分

实际扣费以 Visionary 当前模型配置和 API Key 管理页为准。失败任务不会形成最终成功扣费；网络重试必须复用同一个业务请求 ID。

模型清晰度计费说明
Nano Banana Pro2K / 4K固定模型价格；AI 增强单独计费。
Nano Banana 2 Lite1K固定模型价格。