DEVELOPER API · v1

把图片生成接入你的应用。

通过服务端 API 调用 Nano Banana 与 GPT Image。使用独立密钥、账户积分与可查询的异步生成任务。

API 权限、积分和排队规则

月付、年付和一次性积分包都充值到同一个余额,网页与 API 生成共用。使用积分包余额不要求持有有效订阅。登录账户可创建 API 密钥,生成需要足够积分;模型和账户查询也需要密钥鉴权。匿名免费任务不通过此 API 提供。

所有网页与 API 生成均消耗账户积分,不额外增加本站等待,但供应商仍可能排队,生成也需要时间。HTTP 202 只表示受理,不代表立即完成,API 速率限制仍适用。

这是 Nano Banana 2.1 的本站 API,不是 Shyfai 直连接口。请使用本站模型 ID、本站任务 id 和端点。供应商路由、callback_url、request_id、status_url 由本站后端处理,不传供应商参数或密钥。v1 尚不对第三方开放业务回调。

比较订阅和积分包

快速开始

  1. 登录并购买积分,在开发者 API 密钥页面创建密钥。
  2. 使用唯一 Idempotency-Key 提交一次生成请求,并保存返回的本站任务 ID。
  3. 约每 5 秒查询一次任务,完成后及时保存图片。

Base URL: https://nanobanana2-1.cc/api/v1

export NANO_API_KEY='YOUR_API_KEY'

curl 'https://nanobanana2-1.cc/api/v1/images/generations' \
  -H "Authorization: Bearer $NANO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(python -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "A tiny cafe above the clouds, warm sunset light",
    "size": "16:9",
    "resolution": "2K",
    "quality": "medium"
  }'

身份鉴权

每个 v1 请求都需要 Authorization: Bearer YOUR_API_KEY。使用本站签发的密钥,而不是 EvoLink 或 Google 密钥。完整密钥仅显示一次,可随时撤销,每个账户最多保留 5 个有效密钥。

请将密钥保存在服务端。首版不支持浏览器跨域直连、移动客户端内置密钥或转发供应商凭据。GET /models 查询能力,GET /account 查询与网页共用的积分余额。

模型与积分

请通过 GET /models 获取当前能力与积分消耗。每次请求生成一张图片。Nano Banana 的上游 quality 表示分辨率;在本站统一 API 中请保留 quality: medium,通过 resolution 选择档位。GPT Image 则分别设置画质和分辨率。

Nano Banana 2.1

gemini-nano-banana-2.1

分辨率: 1K / 2K / 4K
画质: medium
参考图上限: 14
比例: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1

纯文字生成,medium 画质: 1K: 4 积分 · 2K: 8 积分 · 4K: 13 积分

Nano Banana 2 Lite

gemini-3.1-flash-lite-image

分辨率: 1K
画质: medium
参考图上限: 14
比例: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1

纯文字生成,medium 画质: 1K: 4 积分

Nano Banana 2

gemini-3.1-flash-image-preview

分辨率: 0.5K / 1K / 2K / 4K
画质: medium
参考图上限: 14
比例: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1

纯文字生成,medium 画质: 0.5K: 4 积分 · 1K: 4 积分 · 2K: 8 积分 · 4K: 13 积分

Nano Banana Pro

gemini-3-pro-image-preview

分辨率: 1K / 2K / 4K
画质: medium
参考图上限: 14
比例: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9

纯文字生成,medium 画质: 1K: 4 积分 · 2K: 8 积分 · 4K: 13 积分

GPT Image 2.5 Sunburst

gpt-image-2.5-sunburst

分辨率: 1K / 2K / 4K
画质: low / medium / high / xhigh / max
参考图上限: 16
比例: 1:1, 1:2, 2:1, 1:3, 3:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9

纯文字生成,medium 画质: 1K: 2 积分 · 2K: 3 积分 · 4K: 4 积分

GPT Image 2.5 Flare

gpt-image-2.5-flare

分辨率: 1K / 2K / 4K
画质: low / medium / high / xhigh / max
参考图上限: 16
比例: 1:1, 1:2, 2:1, 1:3, 3:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9

纯文字生成,medium 画质: 1K: 2 积分 · 2K: 3 积分 · 4K: 4 积分

Nano Banana 每张参考图增加 1 个产品积分。GPT Image 保留原有的零张或一张参考图价格,从第二张起每张增加 1 个产品积分;这是预算策略,不是供应商 token 报价。任务被接受时会以事务方式预留积分,确认失败时退还;临时查询错误不等于失败。API 不提供无限生成,也不会自动发起新的付费重试。

参考图上传

使用 multipart/form-data 向 POST /uploads 每次提交一个 file 字段。支持 JPG、PNG、WebP,每个文件最多 10 MB。逐张上传后,将返回的 URL 放入 image_urls:Nano Banana 最多 14 张,GPT Image 最多 16 张。每个 URL 都必须由同一账户上传,外部 URL 和重复参考图会被拒绝。

curl 'https://nanobanana2-1.cc/api/v1/uploads' \
  -H "Authorization: Bearer $NANO_API_KEY" \
  -F 'file=@reference.png'

创建生成任务

POST /images/generations · Content-Type: application/json

prompt
必填且非空。本站保守限制:Nano Banana 2.1 最多 4,000 个 Unicode 字符,其他 Nano 模型 2,000,GPT Image 32,000。
model
可选,默认 gemini-nano-banana-2.1。使用 /models 返回的模型 ID。
size / resolution / quality
请从 /models 的支持列表中选择。此公开 API 接受模型支持的比例(Nano 也支持 auto),不开放明确像素尺寸;Lite 仅支持 1K。
image_urls
可选的本人上传 URL 有序数组:Nano Banana 最多 14 张,GPT Image 最多 16 张。纯文字生成时省略或使用 []。完整列表按顺序提交;相同 Idempotency-Key 下更改顺序或任意 URL 会产生冲突。目前生成历史仅存储第一张参考图 URL。
Idempotency-Key
必填请求头,8–128 个安全字符。建议使用 UUID,提交前保存。请求结果不确定时,使用同一密钥与同一正文重试。

HTTP 202 返回本站任务 id、状态与 credits_used。同一逻辑请求重试时请勿更换 Idempotency-Key。相同密钥配不同正文会返回 409。如果提交状态持续不确定,请保留密钥并联系支持,而不是再次创建付费任务。

首版不支持:蒙版、透明输出、格式选择、多张输出、搜索增强和回调。不支持的字段会被拒绝,不会静默忽略。

查询任务

通过 GET /tasks/{id} 查询创建时返回的本站任务 ID,仅能查询本人任务。状态包括 processing、uncertain、completed、failed。完成后 results 包含带 url 字段的对象。uncertain 表示无法确认供应商是否接受任务,积分继续预留,需联系支持核对;请勿换一个新幂等密钥再次提交。请及时下载重要结果,供应商备用链接可能在 24 小时后失效。

curl 'https://nanobanana2-1.cc/api/v1/tasks/LOCAL_TASK_ID' \
  -H "Authorization: Bearer $NANO_API_KEY"

错误与限制

错误采用 { error: { code, message } }。400 表示参数无效,401 表示密钥无效或已撤销,402 表示积分不足,404 表示任务不可访问,409 表示幂等冲突,413 表示输入过大,429 表示限流,5xx 表示临时服务错误。

各 API 密钥共用账户限额:每分钟 60 次请求,其中生成提交最多每分钟 10 次。429 时遵守 Retry-After。建议约每 5 秒查询一次任务,请勿高速循环;创建新密钥不会重置限额。

服务端示例

Node.js

// Node.js 20+; run on your server, not in browser JavaScript.
const base = 'https://nanobanana2-1.cc/api/v1';
const headers = { Authorization: 'Bearer ' + process.env.NANO_API_KEY };
const requestKey = crypto.randomUUID(); // Persist this key before submitting.
const response = await fetch(base + '/images/generations', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'Idempotency-Key': requestKey },
  body: JSON.stringify({ model: 'gpt-image-2.5-sunburst', prompt: 'A minimal botanical illustration', size: '1:1', resolution: '1K', quality: 'medium' })
});
const task = await response.json();
if (!response.ok) throw new Error(JSON.stringify(task.error));
// Retry uncertain submissions with the SAME requestKey and SAME request body.
for (let attempt = 0; attempt < 120; attempt++) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  const status = await fetch(base + '/tasks/' + encodeURIComponent(task.id), { headers });
  if (status.status === 429 || status.status >= 500) continue;
  const result = await status.json();
  if (!status.ok) throw new Error(JSON.stringify(result.error));
  if (result.status === 'failed') throw new Error(JSON.stringify(result.error));
  if (result.status === 'completed') { console.log(result.results); break; }
  if (attempt === 119) console.log('Still processing. Keep task.id and resume polling later.');
}

Python

import os, uuid, time, json, urllib.request, urllib.error

base = 'https://nanobanana2-1.cc/api/v1'
key = os.environ['NANO_API_KEY']
request_key = str(uuid.uuid4())  # Persist before submission; reuse on uncertain retries.
body = json.dumps({'prompt': 'A cozy reading room in warm light', 'size': '4:3', 'resolution': '1K', 'quality': 'medium'}).encode()
request = urllib.request.Request(base + '/images/generations', data=body, headers={
    'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json', 'Idempotency-Key': request_key
})
with urllib.request.urlopen(request, timeout=90) as response:
    task = json.load(response)
for _ in range(120):
    time.sleep(5)
    poll = urllib.request.Request(base + '/tasks/' + task['id'], headers={'Authorization': 'Bearer ' + key})
    try:
        with urllib.request.urlopen(poll, timeout=30) as response:
            result = json.load(response)
    except urllib.error.HTTPError as error:
        if error.code == 429 or error.code >= 500:
            continue
        raise
    if result['status'] == 'failed':
        raise RuntimeError(result.get('error'))
    if result['status'] == 'completed':
        print(result['results'])
        break
else:
    print('Still processing. Save task ID and resume polling later:', task['id'])

请将请求幂等密钥和返回的任务 ID 保存在应用数据库中。示例限制了查询次数;生产客户端还应设置超时、退避与持久任务恢复。