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 域名。

业务参数

参数类型必填默认值可选值 / 范围示例说明
modelstring是—nano-banana-2.1nano-banana-2.1选择图片模型,每次提交都应填写该公开编码,决定本次任务能力和计费规则。
promptstring否,文生图应填写—文本字符串窗边的橘猫,清晨阳光,写实摄影描述图片内容、风格或编辑目标。文生图时提供具体描述,参考图编辑时结合 urls 描述希望修改的内容。不改变分辨率档位或默认按次价格。
urlsarray否不提供参考图图片地址字符串数组["https://example.com/reference.jpg"]图生图或参考图编辑时填写,与 prompt 一起描述编辑目标。每项应为平台可访问的 HTTP(S) 图片地址,省略或传空数组表示不使用参考图。不改变默认按次价格。
urls[]string提供参考图时是—有效 HTTP(S) 图片 URLhttps://example.com/reference.jpg一张参考图片的地址,作为 urls 数组中的元素。请确保任务处理期间仍可读取图片内容。
aspect_ratiostring否auto见下方比例表1:1选择输出画幅,适合按展示位置确定横图或竖图。与 image_size 共同决定输出尺寸,实际像素尺寸以生成结果为准,不改变默认按次价格。
image_sizestring否1K1K / 2K / 4K2K选择分辨率规格。需要更清晰的图片时选择 2K 或 4K,生成耗时和文件大小可能增加,三档默认按次价格相同。
callback_urlstring否不发送回调可接收 POST 的 HTTP(S) URLhttps://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"
  }
}
字段类型说明
codenumber1 表示请求成功,0 表示请求失败。
msgstring请求结果说明。
data.task_idstring平台任务 ID,查询和回调去重均使用该字段。
data.statusstring任务当前状态,提交后一般为 processing。
data.modelstring本次请求使用的公开模型编码。
data.frozen_pointsnumber本次任务预占点数,示例采用默认 6 点价格。
data.created_atstring创建时间,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.statusstringpending 待处理,processing 处理中,completed 已完成,failed 失败,cancelled 已取消。
data.result.resultsarray完成后的图片结果列表。
data.result.results[].urlstring转存后可访问的图片地址。
data.result.results[].transfer_statusstring图片转存状态,成功为 success。
data.usage.points_costnumber实际扣点,示例为 6 点,以本次任务生效价格为准。
data.error.codestring失败任务的错误标识,出现错误时读取。
data.error.messagestring失败原因和处理提示,出现错误时读取。

回调行为与幂等提示

填写 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=0API Key 缺失、无效或过期检查 Bearer 请求头与密钥状态。
HTTP 403,data.error_codeapi_realname_required按当前租户要求完成账号认证后调用。
HTTP 403,msgpc_agreement_required在用户中心阅读并同意当前协议后调用。
HTTP 429,code=0请求过于频繁降低频率,延迟后重试。
code=0,msg参数类型错误、模型不可用或无调用权限检查本页参数表、模型开通状态和密钥权限。
code=0,msg余额、密钥额度不足或排队上限处理余额与额度,或等待已有任务结束。
data.error.codetransfer_failed转存未完成,不应读取图片为已交付结果,联系管理员检查存储配置。
data.status=failed,data.error其它任务执行失败根据 message 检查参数或联系管理员,避免盲目重复提交。

计费说明

规格默认价格计费单位
1K6 点每次图片生成
2K6 点每次图片生成
4K6 点每次图片生成

以上为平台配置的默认价格。租户售价、用户专属价格、折扣或活动可能影响当前账号的实际价格,实际扣费以调用时生效配置为准。

调用前使用以下接口查询当前租户和用户的有效价格:

GET /api/v1/pricing?type=model&model=nano-banana-2.1
Authorization: Bearer <YOUR_API_KEY>

读取响应 data 中的 pricing、price_view 和可用规格信息,以返回的有效价格为准。提交时预占点数,任务成功交付后结算,失败或取消按平台规则释放或返还预占点数。最终扣点读取任务查询中的 data.usage.points_cost。

同类文章