原生nano-banana格式(同步) - apimax · AI 大模型 API 聚合平台

文档 / 图像系列 / Nano Banana / 同步-原生格式

Nano Banana 是 Google Gemini 的原生图像生成能力,当前提供 gemini-3.1-flash-image-preview(Nano Banana 2)/ gemini-3-pro-image-preview(Nano Banana Pro)/ gemini-3.1-flash-lite-image(Nano Banana 2 Lite),以及 gemini-2.5-flash-image(初代 Nano Banana)。本接口走 Gemini 原生 `generateContent` 格式,同步调用、同步返回结果(base64 内联在响应中),无需轮询任务。

- 本接口为 Gemini 原生格式(/v1beta/models/<model>:generateContent),与 OpenAI 兼容格式不同;如需 OpenAI 风格异步任务(/v1/images/async-generations 返回 task_id 轮询),见 Nano Banana 2 异步生成。 - 生成图像以 inline_data(base64)直接内联在响应 parts 中,请及时解码保存。 - 该模型单次仅生成 1 张图。

鉴权#

所有接口均需通过 Bearer Token 认证(网关兼容 x-goog-api-key 与 Authorization: Bearer)。请在 API Key 管理页面创建你的 Key,并在请求头中添加:

text

Authorization: Bearer YOUR_API_KEY

创建任务#

POST /v1beta/models/{model}:generateContent

{model} 填以下任一模型;同一模型的 gemini-* 命名与 nano-banana-* 别名等价,任选其一:
gemini-3.1-flash-image-preview / nano-banana-2(Nano Banana 2)
gemini-3-pro-image-preview / nano-banana-pro(Nano Banana Pro)
gemini-3.1-flash-lite-image / nano-banana-2-lite(Nano Banana 2 Lite)
gemini-2.5-flash-image(初代 Nano Banana)
请求体为 application/json,与 Gemini generateContent 完全同构。

最简文生图只需 contents 里的文本 parts,并在 generationConfig.responseModalities 中声明输出图像:

json

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "一只猫在草地上玩耍" }]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"]
  }
}

指定宽高比与清晰度(image_config 用 snake_case,网关自动转 camelCase 传上游):

json

{
  "contents": [
    { "role": "user", "parts": [{ "text": "黄昏时分未来都市天际线的电影级广角镜头" }] }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "image_config": {
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }
}

图生图 / 图像编辑(在 parts 中传入参考图 inline_data):

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "在她旁边加一只可爱的小猫" },
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "<BASE64_IMAGE_DATA>"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"]
  }
}

请求参数#

请求体顶层为 contents(对话内容)与 generationConfig(生成配置)。

contents#

字段	类型	必填	说明
`contents`	array	是	对话内容数组,每项含 `role` 与 `parts`
`contents[].role`	string	否	`user` / `model`
`contents[].parts[]`	array	是	内容块,可为 `text` 或 `inline_data`

parts(内容块)#

字段	类型	说明
`text`	string	文本提示词,描述要生成或编辑的图像
`inline_data`	object	参考图(图生图/编辑),含 `mime_type` 与 `data`(base64)
`inline_data.mime_type`	string	图片 MIME 类型:`image/png`、`image/jpeg`、`image/webp`
`inline_data.data`	string	图片 base64 编码(不含 `data:` 前缀)

generationConfig#

字段	类型	必填	默认	说明
`responseModalities`	array	是	—	输出模态,图像生成填 `["IMAGE"]` 或 `["TEXT","IMAGE"]`
`image_config`	object	否	—	图像配置(snake_case,网关自动转 camelCase)
`image_config.aspect_ratio`	string	否	`1:1`	宽高比,见下方取值
`image_config.image_size`	string	否	`1K`	清晰度 `1K`/`2K`/`4K`(3.1 Flash Image 还支持 `512`)

字段命名:Gemini 原生 REST 用 snake_case(inline_data、mime_type、image_config、aspect_ratio、image_size);网关接受 snake_case 并自动转 camelCase 传上游。请勿混用 imageConfig/aspectRatio(camelCase)否则报错。

aspect_ratio 宽高比#

取值	说明
`1:1`	正方形(默认)
`16:9`、`9:16`	横版 / 竖版
`21:9`、`9:21`	超宽 / 超高
`4:3`、`3:4`、`3:2`、`2:3`	常见比例
`4:5`、`5:4`	竖版 / 横版(社交)
`1:4`、`4:1`、`1:8`、`8:1`	超扁比例(仅 3.1 Flash Image)

请求示例#

文生图:

bash

curl -s -X POST   "https://api.apimax.ai/v1beta/models/gemini-3.1-flash-image-preview:generateContent"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "一只猫在草地上玩耍" }] }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "image_config": { "aspect_ratio": "1:1", "image_size": "2K" }
    }
  }'

图生图(Python requests,本地图片转 base64 传入):

python

import requests, base64

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode("utf-8")

url = "https://api.apimax.ai/v1beta/models/gemini-3.1-flash-image-preview:generateContent"
headers = {"Authorization": "Bearer <token>", "Content-Type": "application/json"}
payload = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "在她旁边加一只可爱的小猫"},
            {"inline_data": {"mime_type": "image/png", "data": img_b64}},
        ],
    }],
    "generationConfig": {"responseModalities": ["IMAGE"]},
}
resp = requests.post(url, headers=headers, json=payload)
print(resp.json())

响应示例#

同步返回 Gemini GenerateContentResponse 结构,生成图像以 inline_data 内联在 candidates[].content.parts[] 中:

json

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inline_data": {
              "mime_type": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 4160,
    "totalTokenCount": 4172
  }
}

将 candidates[0].content.parts[].inline_data.data 做 base64 解码即可得到图像二进制。若 parts 中同时含 text,则为模型返回的说明文字。

错误码#

状态码	含义
400	请求参数无效(缺少 `responseModalities`、`inline_data` 不可达、MIME 不支持、误用 camelCase 字段名等)
401	身份验证失败,请检查 API 密钥
402	账户余额不足,请充值后再试
403	Token 无该模型访问权限
429	请求过于频繁,请稍后重试
500	服务器内部错误,请稍后重试

常见报错:

extra_body.google.imageConfig is not supported, use extra_body.google.image_config instead:字段误用 camelCase,改用 snake_case image_config。
imageConfig.aspectRatio is not supported:同上,改用 aspect_ratio。

鉴权#

创建任务#

请求参数#

contents#

parts(内容块)#

generationConfig#

aspect_ratio 宽高比#

请求示例#

响应示例#

错误码#

下一步