13参考手册
模型与参数
有哪些模型、它们能生成哪些分辨率和宽高比,以及一张图片的价格。你的账号的确切列表由 GET /models 返回。
模型目录
价格按每张图片标注,并取决于分辨率。金额在接收请求时扣除,请求失败不收费:金额会立即退回余额。
nano-banana-pro根据参考图生成图片并编辑场景,支持 1K、2K 和 4K。宽高比可按第一张参考图自动选择。
nano-banana-2插画、产品图以及基于参考图的构图:支持标准、全景和细长的宽高比,分辨率为 1K、2K 和 4K。
nano-banana-2.1Google 推出的最新 Nano Banana 系列模型:画面逼真,严格遵循提示词,角色稳定,文字清晰,支持 1K、2K 和 4K。单个请求最多 14 张参考图。
nano-banana-flash固定 1K 分辨率的图片生成与编辑。支持标准宽高比,也可自动选择宽高比,适合不需要更高分辨率的场景。
nano-banana-2-lite固定 1K 分辨率的图片生成与编辑,提供十种可明确指定的宽高比。适合宽高比已预先选定、只需要 1K 结果的场景。
gpt-image-21K 分辨率的图片生成与编辑,提供十种标准宽高比。需要 2K 或 4K 时,请使用 GPT Image 2 HD。
gpt-image-2.51K 分辨率的图片生成与编辑,提供十三种宽高比,包括 9:21、7:5 和 5:7。需要 2K 或 4K 时,请使用 GPT Image 2.5 Sunburst 或 GPT Image 2.5 Flare。
模型名称就是 model 字段所用的 id。你的账号实际可用的模型和你的价格由 GET /models 返回:账号可能有专属价格,或者模型列表更短。
分辨率和宽高比
resolution取1K、2K或4K,不区分大小写。可用的值取决于模型:Nano Banana Flash、Nano Banana 2 Lite、GPT Image 2 和 GPT Image 2.5 只支持1K。- 如果未指定
resolution,图片会按默认分辨率生成:Nano Banana Pro、Nano Banana 2 和 Nano Banana 2.1 为2K,Nano Banana Flash、Nano Banana 2 Lite 和所有 GPT Image 模型为1K。 aspect_ratio是形如16:9的精确值,不能有空格,也不能调换数字顺序。可用的宽高比取决于模型。- 如果未指定
aspect_ratio,则为1:1。缺少该字段并不意味着auto。 - 分辨率是模型的尺寸档位,而不是像素数。不接受
width和height字段;如果设计稿需要精确尺寸,请检查所得文件的尺寸。
auto 是什么意思
Nano Banana Pro、Nano Banana 2、Nano Banana 2.1 和 Nano Banana Flash 可以自己选择宽高比:传入 "aspect_ratio": "auto" 即可。有参考图时,宽高比通常与第一张参考图一致。没有参考图时,不保证宽高比:如果你的版面取决于它,请明确指定 aspect_ratio。Nano Banana 2 Lite 和 GPT Image 模型没有 auto 这个值:宽高比由你指定。
选择不支持的选项 会怎样
如果模型不支持所请求的分辨率或宽高比,会在扣费前返回 400。error.details.supported 中会返回可用值的列表,也不会扣费。
HTTP/1.1 400 Bad Request { "error": { "code": "ERR_INVALID_REQUEST", "message": "Unsupported resolution: 4K. Supported: 1K (case-insensitive) (omit resolution to render 1K).", "details": { "resolution": "4K", "supported": ["1K"] } } }
请求为 "model": "gpt-image-2" 和 "resolution": "4K"。需要 2K 或 4K 时,请使用 GPT Image 2 HD、GPT Image 2.5 Sunburst 或 GPT Image 2.5 Flare。
HTTP/1.1 400 Bad Request { "error": { "code": "ERR_INVALID_REQUEST", "message": "Unsupported aspect_ratio: 5:4. Supported: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 21:9 (omit aspect_ratio to render 1:1).", "details": { "aspect_ratio": "5:4", "supported": [ "1:1", "16:9", "9:16", "4:3", "3:4", "2:3", "3:2", "21:9" ] } } }
请求为 "model": "gpt-image-2.5-sunburst" 和 "aspect_ratio": "5:4"。这款模型不支持 5:4 和 4:5 宽高比。
亲自试试:打开请求构建器,灰色选项会显示同样的拒绝响应。
通过 API 获取模型目录
/models该端点不会扣费,也不占用生成名额。它计入账号共用的请求速率限制(限额)。参数 category 是可选的:图片请传 image。
curl --fail-with-body --max-time 20 \ "https://api.rendergrid.io/ api/ public/ v1/ models?category=image" \ -H "Authorization: Bearer $RENDERGRID_API_KEY"
import os from decimal import Decimal import requests key = os.environ["RENDERGRID_API_KEY"] response = requests.get( "https://api.rendergrid.io/ api/ public/ v1/ models", params={"category": "image"}, headers={"Authorization": f"Bearer {key}"}, timeout=(5, 20), ) response.raise_for_status() for model in response.json()["models"]: # 分辨率对应的价格请取自 variants,而不是根层级的 price prices = { v["variant_key"]: Decimal(v["price"]) for v in model.get("variants", []) } print(model["id"], prices)
// Node.js 22+,文件扩展名为 .mjs const base = "https://api.rendergrid.io/ api/ public/ v1"; const url = new URL(`${base}/models`); url.searchParams.set("category", "image"); const key = process.env.RENDERGRID_API_KEY; const response = await fetch(url, { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(20_000), }); if (!response.ok) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } for (const model of (await response.json()).models) { // 分辨率对应的价格请取自 variants,而不是根层级的 price const prices = Object.fromEntries((model.variants ?? []).map((v) => [v.variant_key, v.price])); console.log(model.id, prices); }
{
"currency": "USD",
"models": [
{
"id": "nano-banana-2",
"category": "image",
"display_name": "Nano Banana 2",
"price": "0.0250",
"unit": "per_image",
"variants": [
{ "variant_key": "1k", "price": "0.0250" },
{ "variant_key": "2k", "price": "0.0400" },
{ "variant_key": "4k", "price": "0.0600" }
]
},
{
"id": "gpt-image-2.5",
"category": "image",
"display_name": "GPT Image 2.5",
"price": "0.0250",
"unit": "per_image",
"variants": [{ "variant_key": "1k", "price": "0.0250" }]
}
]
}- currency
- 响应中所有金额的货币:
USD。 - id
- 生成请求中
model字段所用的模型 id。 - price
- 该模型最便宜的分辨率的价格,以美元计的字符串。它不是你这张图片的价格:价格取决于
resolution。 - unit
- 价格的单位:
per_image表示每张图片。 - variants
- 按分辨率给出的价格:
variant_key(1k、2k、4k)和price;完整响应中每个档位还有display_name和unit。所选分辨率的价格请从这里获取。
目录中的价格是你的账号的价格,已考虑相关约定。示例中的金额仅为示意。
价格与扣费
图片的价格取决于模型和分辨率。例如,Nano Banana 2.1 在 1K 下为 $0.02,在 2K 下为 $0.03,在 4K 下为 $0.04,GPT Image 2 在 1K 下为 $0.02。最低价格是 Nano Banana Flash 和 Nano Banana 2 Lite 的 1K 图片,每张 $0.015。
如果未指定 resolution,图片会按默认分辨率生成并计费——Nano Banana Pro、Nano Banana 2 和 Nano Banana 2.1 的默认分辨率是 2K,尽管目录中根层级的 price 显示的是 1K。金额会出现在 202 响应的 cost 字段中。
请求失败不收费:金额会立即退回余额。
常见问题
为什么目录中的 price 是 1K 的价格,而不带 resolution 的请求却按 2K 生成?
price 显示的是该模型最便宜的分辨率。不带 resolution 的请求会按默认分辨率生成:Nano Banana Pro、Nano Banana 2 和 Nano Banana 2.1 的默认分辨率是 2K。所需分辨率的价格请从 variants 中获取。如何知道我的账号可以使用哪些模型?
GET /models:响应中只有你的账号可用的模型和你的价格。请求你没有的模型会收到 404 ERR_MODEL_NOT_FOUND。可以指定精确的像素尺寸吗?
width 和 height。请选择分辨率和宽高比,下载后再检查成品文件的尺寸。如果模型不支持所需的宽高比怎么办?
400,error.details.supported 中列出了可用的值。请选择其他宽高比或其他模型。