Nano-Banana 2.1
目录路径:图像系列 / Nano-Banana 2.1
文档 slug:m-nano-banana-2-1
支持文生图与参考图编辑,可选择 1K、2K、4K 分辨率。图片通过平台转存策略保存后交付,默认按次计费,三档参考价格均为 6 点/次。
<details>
<summary>基本信息</summary>
| 字段 | 内容 |
|---|---|
| 类型 | 模型 API |
| 模型名称 | Nano-Banana 2.1 |
| 模型编码 | nano-banana-2.1 |
| 模型类型 | 图片生成(image) |
| 调用方式 | POST /api/v1/tasks |
| 调用模式 | 异步 |
| 结果交付 | 图片完成转存后返回结果地址 |
</details>
鉴权
在请求头携带所属租户分配的 API Key,使用 JSON 请求体。密钥需要关联有效用户,并满足账号认证、接口权限、余额和密钥额度要求。
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
请求路径
POST /api/v1/tasks
提交成功后读取 data.task_id,使用同一用户所属租户的有效 API Key 查询任务。服务域名使用当前租户的 API 域名。
业务参数
| 参数 | 类型 | 必填 | 默认值 | 可选值 / 范围 | 示例 | 说明 |
|---|---|---|---|---|---|---|
model | string | 是 | — | nano-banana-2.1 | nano-banana-2.1 | 选择图片模型,每次提交都应填写该公开编码,决定本次任务能力和计费规则。 |
prompt | string | 否,文生图应填写 | — | 文本字符串 | 窗边的橘猫,清晨阳光,写实摄影 | 描述图片内容、风格或编辑目标。文生图时提供具体描述,参考图编辑时结合 urls 描述希望修改的内容。不改变分辨率档位或默认按次价格。 |
urls | array | 否 | 不提供参考图 | 图片地址字符串数组 | ["https://example.com/reference.jpg"] | 图生图或参考图编辑时填写,与 prompt 一起描述编辑目标。每项应为平台可访问的 HTTP(S) 图片地址,省略或传空数组表示不使用参考图。不改变默认按次价格。 |
urls[] | string | 提供参考图时是 | — | 有效 HTTP(S) 图片 URL | https://example.com/reference.jpg | 一张参考图片的地址,作为 urls 数组中的元素。请确保任务处理期间仍可读取图片内容。 |
aspect_ratio | string | 否 | auto | 见下方比例表 | 1:1 | 选择输出画幅,适合按展示位置确定横图或竖图。与 image_size 共同决定输出尺寸,实际像素尺寸以生成结果为准,不改变默认按次价格。 |
image_size | string | 否 | 1K | 1K / 2K / 4K | 2K | 选择分辨率规格。需要更清晰的图片时选择 2K 或 4K,生成耗时和文件大小可能增加,三档默认按次价格相同。 |
callback_url | string | 否 | 不发送回调 | 可接收 POST 的 HTTP(S) URL | https://example.com/callback | 需要异步通知时填写,平台在任务进入终态后通知该地址。成功任务完成图片转存后才交付结果。不传时通过任务查询获取结果,不改变默认按次价格。 |
urls[] 表示数组元素,不是独立的请求字段。基础字段类型与已有 Nano-Banana 图片接口一致,示例采用完整的图片描述,避免提交空内容。
可选值说明
| image_size 值 | 含义 / 适用场景 / 限制 |
|---|---|
1K | 默认分辨率,适合预览和一般展示。1:1 测试输出为 1024×1024。 |
2K | 更清晰的分辨率,适合细节展示。1:1 测试输出为 2048×2048。 |
4K | 高分辨率,适合高清素材。1:1 测试输出为 4096×4096,文件通常更大。 |
以上像素尺寸是 1:1 画幅的已验证示例,其它画幅的宽高以实际结果为准。请求示例使用大写的分辨率值。
| aspect_ratio 值 | 含义 / 适用场景 / 限制 |
|---|---|
auto | 默认值,由内容和参考图决定画幅,不保证固定宽高比。 |
1:1 | 正方形,适合头像、商品图和方形配图。 |
16:9 | 宽屏横图,适合横向封面和展示屏。 |
9:16 | 长竖图,适合手机竖屏和竖版封面。 |
4:3 | 常规横图,适合文章和产品展示。 |
3:4 | 常规竖图,适合人像和竖版配图。 |
3:2 | 摄影横图,适合风景和摄影构图。 |
2:3 | 摄影竖图,适合人像和海报。 |
5:4 | 接近方形的横图,适合商品与静物构图。 |
4:5 | 接近方形的竖图,适合人物和信息流配图。 |
21:9 | 超宽横图,适合全景和横向背景。 |
请求示例
文生图
{
"model": "nano-banana-2.1",
"prompt": "窗边的橘猫,清晨阳光,写实摄影",
"aspect_ratio": "1:1",
"image_size": "1K",
"urls": []
}
参考图编辑与完成回调
{
"model": "nano-banana-2.1",
"prompt": "保留参考图中的杯子,将背景改为浅蓝色,柔和自然光",
"aspect_ratio": "4:3",
"image_size": "2K",
"urls": [
"https://example.com/reference.jpg"
],
"callback_url": "https://example.com/callback"
}
需要 4K 时,将 image_size 改为 4K,其余请求结构不变。
成功响应
以下展示创建任务响应中的主要业务字段。成功标识为 code=1,任务 ID 在 data 中。
{
"code": 1,
"msg": "success",
"data": {
"task_id": "task_xxxxxxxxxxxx",
"status": "processing",
"model": "nano-banana-2.1",
"frozen_points": 6,
"created_at": "2026-10-08T02:00:00Z"
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 1 表示请求成功,0 表示请求失败。 |
msg | string | 请求结果说明。 |
data.task_id | string | 平台任务 ID,查询和回调去重均使用该字段。 |
data.status | string | 任务当前状态,提交后一般为 processing。 |
data.model | string | 本次请求使用的公开模型编码。 |
data.frozen_points | number | 本次任务预占点数,示例采用默认 6 点价格。 |
data.created_at | string | 创建时间,ISO 8601 格式。 |
提交成功只表示任务已受理,不表示图片已生成或转存完成。
异步任务查询
GET /api/v1/tasks/{task_id}
Authorization: Bearer <YOUR_API_KEY>
建议提交后每隔 2 至 5 秒查询一次。生成和转存阶段保持等待,直到 status 进入 completed、failed 或 cancelled。
已完成示例
{
"code": 1,
"msg": "success",
"data": {
"task_id": "task_xxxxxxxxxxxx",
"model": "nano-banana-2.1",
"type": "image",
"call_type": "async",
"status": "completed",
"created_at": "2026-10-08T10:00:00+08:00",
"completed_at": "2026-10-08T10:01:00+08:00",
"response_time_ms": 60000,
"result": {
"results": [
{
"url": "https://example.com/stored-result.png",
"transfer_status": "success"
}
]
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"total_tokens": 0,
"points_cost": 6
}
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
data.status | string | pending 待处理,processing 处理中,completed 已完成,failed 失败,cancelled 已取消。 |
data.result.results | array | 完成后的图片结果列表。 |
data.result.results[].url | string | 转存后可访问的图片地址。 |
data.result.results[].transfer_status | string | 图片转存状态,成功为 success。 |
data.usage.points_cost | number | 实际扣点,示例为 6 点,以本次任务生效价格为准。 |
data.error.code | string | 失败任务的错误标识,出现错误时读取。 |
data.error.message | string | 失败原因和处理提示,出现错误时读取。 |
回调行为与幂等提示
填写 callback_url 时,平台向该地址发送 POST 终态通知。成功通知在图片转存和交付完成后发送,失败任务也可发送通知。接收服务应按 task_id 去重,并保留任务查询作为通知未收到时的补偿方式。
创建任务接口未提供提交幂等键保证。重复 POST 会创建新的独立任务并按各次任务计费,不应将重复提交作为轮询方式。提交超时后先确认已有任务,再决定是否重试。GET 查询不会创建任务或新增生成费用。
失败响应与错误码
创建或鉴权失败时,响应使用 code、msg、data 结构。部分业务失败仍使用 HTTP 200,因此必须同时判断 JSON 中的 code。
{
"code": 0,
"msg": "点数不足,无法提交任务",
"data": null
}
任务查询请求本身成功、任务执行失败时,返回 code=1,错误在 data.error 中:
{
"code": 1,
"msg": "success",
"data": {
"task_id": "task_xxxxxxxxxxxx",
"model": "nano-banana-2.1",
"type": "image",
"call_type": "async",
"status": "failed",
"created_at": "2026-10-08T10:00:00+08:00",
"error": {
"code": "transfer_failed",
"message": "图片结果转存失败,请稍后重试或联系管理员"
}
}
}
| HTTP / 响应位置 | 标识或情形 | 处理建议 |
|---|---|---|
| HTTP 401,code=0 | API Key 缺失、无效或过期 | 检查 Bearer 请求头与密钥状态。 |
| HTTP 403,data.error_code | api_realname_required | 按当前租户要求完成账号认证后调用。 |
| HTTP 403,msg | pc_agreement_required | 在用户中心阅读并同意当前协议后调用。 |
| HTTP 429,code=0 | 请求过于频繁 | 降低频率,延迟后重试。 |
| code=0,msg | 参数类型错误、模型不可用或无调用权限 | 检查本页参数表、模型开通状态和密钥权限。 |
| code=0,msg | 余额、密钥额度不足或排队上限 | 处理余额与额度,或等待已有任务结束。 |
| data.error.code | transfer_failed | 转存未完成,不应读取图片为已交付结果,联系管理员检查存储配置。 |
| data.status=failed,data.error | 其它任务执行失败 | 根据 message 检查参数或联系管理员,避免盲目重复提交。 |
计费说明
| 规格 | 默认价格 | 计费单位 |
|---|---|---|
1K | 6 点 | 每次图片生成 |
2K | 6 点 | 每次图片生成 |
4K | 6 点 | 每次图片生成 |
以上为平台配置的默认价格。租户售价、用户专属价格、折扣或活动可能影响当前账号的实际价格,实际扣费以调用时生效配置为准。
调用前使用以下接口查询当前租户和用户的有效价格:
GET /api/v1/pricing?type=model&model=nano-banana-2.1
Authorization: Bearer <YOUR_API_KEY>
读取响应 data 中的 pricing、price_view 和可用规格信息,以返回的有效价格为准。提交时预占点数,任务成功交付后结算,失败或取消按平台规则释放或返还预占点数。最终扣点读取任务查询中的 data.usage.points_cost。