Skip to content

Nano Banana 图片 API ​

Nano Banana 是 1XM.AI 支持的 Gemini 图像生成能力,适合文本生图、图片编辑、多参考图融合、商品图、海报图、角色一致性和营销素材生成。

本文覆盖两个常用模型:

模型模型 ID推荐场景接入方式
Nano Banana 2gemini-3.1-flash-image-preview快速生图、高并发、轻量商品图和素材生成同步 /chat/completions、Gemini 原生 /v1beta/models/{model_id}:generateContent 或异步 /images/tasks
Nano Banana Progemini-3-pro-image-preview高质量海报、复杂构图、多参考图融合Google GenAI SDK、Gemini 原生 /v1beta/models/{model_id}:generateContent 或异步 /images/tasks

提示

如果你只是内部脚本调用,可以继续使用同步接口。面向下游客户、网页产品、批量任务、2K / 4K 或多参考图场景,建议统一接入 POST https://api.1xm.ai/v1/images/tasks 异步任务接口,两个 Nano Banana 模型都支持。

接入信息 ​

Nano Banana 2 ​

项目值
Base URLhttps://api.1xm.ai/v1
EndpointPOST /chat/completions
Gemini 原生 EndpointPOST https://api.1xm.ai/v1beta/models/gemini-3.1-flash-image-preview:generateContent
模型名gemini-3.1-flash-image-preview
认证方式Authorization: Bearer sk-你的Key
输入图片messages[].content[].image_url.url,使用 data URL
输出图片模型消息中返回图片 data URL 或图片 URL

Nano Banana Pro ​

项目值
推荐 SDKgoogle-genai
模型名gemini-3-pro-image-preview
API KeyGEMINI_API_KEY
自定义 EndpointGEMINI_API_URL,按你的 1XM 接入配置填写
Gemini 原生 EndpointPOST https://api.1xm.ai/v1beta/models/gemini-3-pro-image-preview:generateContent
输入图片PIL Image / 本地图片对象
输出图片inline_data 图片数据

模型怎么选 ​

场景推荐模型
批量生成配图、商品图、社媒素材gemini-3.1-flash-image-preview
高质量广告海报、复杂构图、角色一致性gemini-3-pro-image-preview
单图编辑、背景替换、风格改写两者都可,优先按质量要求选择
多参考图融合、品牌视觉一致性gemini-3-pro-image-preview
成本敏感、高并发调用gemini-3.1-flash-image-preview

Nano Banana 2 入参示例 ​

Nano Banana 2 使用 OpenAI-compatible chat/completions 请求体。文本生图只传 text 内容块;图片编辑或多图融合时,额外传入一个或多个 image_url 内容块。

json
{
  "model": "gemini-3.1-flash-image-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,..."
          }
        },
        {
          "type": "text",
          "text": "保持主体不变,替换成高级摄影棚背景。Generate image only. Resolution target: 2K."
        }
      ]
    }
  ],
  "max_tokens": 2000
}

顶层参数 ​

参数类型必填示例说明
modelstring✅gemini-3.1-flash-image-previewNano Banana 2 模型 ID
messagesarray✅见上方示例OpenAI-compatible 消息数组
max_tokensinteger❌2000给图片响应保留足够输出空间,建议 2000
temperaturenumber❌0.7可选;需要更稳定输出时可降低

messages[].content[] 参数 ​

参数类型必填示例说明
typestring✅text / image_url内容块类型
textstring文本块必填生成一张电商海报...生图或编辑指令;建议写明“只返回图片”
image_url.urlstring图片块必填data:image/png;base64,...参考图 data URL;支持多张图重复传入

Prompt 写法建议 ​

需求推荐写法
只返回图片Generate image only. Do not return explanation text.
1K 输出Resolution target: 1K
2K 输出Resolution target: 2K
4K 输出Resolution target: 4K
保持参考图主体Keep the subject unchanged / 保持主体不变
多图融合Combine these references into one coherent scene

参考图建议 ​

项目建议
图片格式png / jpeg / webp
传输方式服务端转成 data URL 后放入 image_url.url
单次图片数建议 1-10 张,复杂融合不要一次传太多
图片大小建议先压缩到合理尺寸,避免请求体过大
远程 URL建议服务端先下载并转 data URL,不要依赖模型侧抓取

Gemini 原生 generateContent 接入 ​

如果你的系统已经按 Gemini 原生协议实现,或客户希望兼容 Google Gemini SDK / REST 请求格式,可以直接调用:

text
POST https://api.1xm.ai/v1beta/models/{model_id}:generateContent

{model_id} 可填写:

模型{model_id}
Nano Banana 2gemini-3.1-flash-image-preview
Nano Banana Progemini-3-pro-image-preview

认证方式仍然使用 1XM API Key:

bash
Authorization: Bearer sk-你的Key

文本生图 ​

bash
curl -X POST "https://api.1xm.ai/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "生成一张高级龙虾餐厅宣传海报,真实摄影风格。只返回图片,不要解释文字。"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

参考图编辑 ​

参考图使用 Gemini 原生 inlineData,data 只放纯 base64,不要带 data:image/png;base64, 前缀。

bash
IMAGE_BASE64="$(base64 -i input.png | tr -d '\n')"

curl -X POST "https://api.1xm.ai/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [
      {
        \"role\": \"user\",
        \"parts\": [
          {
            \"inlineData\": {
              \"mimeType\": \"image/png\",
              \"data\": \"${IMAGE_BASE64}\"
            }
          },
          {
            \"text\": \"保持主体不变,把背景换成高级商业摄影棚,输出一张电商海报。只返回图片。\"
          }
        ]
      }
    ],
    \"generationConfig\": {
      \"responseModalities\": [\"TEXT\", \"IMAGE\"],
      \"imageConfig\": {
        \"aspectRatio\": \"16:9\",
        \"imageSize\": \"2K\"
      }
    }
  }"

多参考图时,在 parts 中重复传入多个 inlineData 块即可。接口也兼容 snake_case 字段:inline_data.mime_type、generation_config.response_modalities、image_config.image_size。

原生字段说明 ​

字段必填说明
contents[].role✅固定传 user
contents[].parts[].text文本生图必填生图或编辑指令
contents[].parts[].inlineData.mimeType参考图必填图片 MIME 类型,例如 image/png、image/jpeg
contents[].parts[].inlineData.data参考图必填图片纯 base64 内容
generationConfig.responseModalities建议传必须包含 IMAGE 才会返回图片
generationConfig.imageConfig.aspectRatio可选比例,例如 1:1、16:9、9:16
generationConfig.imageConfig.imageSize可选1K、2K、4K

返回结果遵循 Gemini generateContent 结构。图片通常在:

text
candidates[].content.parts[].inlineData.data

如果返回 snake_case,图片字段可能是:

text
candidates[].content.parts[].inline_data.data

长耗时、批量任务或面向下游客户的产品仍建议使用 POST /v1/images/tasks 异步接口,避免同步请求被网关、Cloudflare 或客户端 SDK 超时打断。

Nano Banana 2 文本生图 ​

cURL ​

bash
curl -X POST "https://api.1xm.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "生成一张高级电商产品海报,白色背景,真实摄影风格。只返回图片,不要解释文字。Resolution target: 1K"
          }
        ]
      }
    ],
    "max_tokens": 2000
  }'

返回结果通常在 choices[0].message.content 中包含图片 data URL 或图片 URL。你的服务端需要从文本中解析图片并保存。

Nano Banana 2 图片编辑 ​

图片编辑时,把本地图片转成 data URL,放入 image_url.url。

bash
IMAGE_DATA_URL="data:image/png;base64,$(base64 -i input.png | tr -d '\n')"

curl -X POST "https://api.1xm.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gemini-3.1-flash-image-preview\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": [
          {
            \"type\": \"image_url\",
            \"image_url\": { \"url\": \"${IMAGE_DATA_URL}\" }
          },
          {
            \"type\": \"text\",
            \"text\": \"保持产品主体不变,把背景替换成高级摄影棚白底场景。只返回图片,不要解释文字。Resolution target: 2K\"
          }
        ]
      }
    ],
    \"max_tokens\": 2000
  }"

Nano Banana 2 多图融合 ​

多参考图时,重复传入多个 image_url 内容块。

json
{
  "model": "gemini-3.1-flash-image-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,..." }
        },
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,..." }
        },
        {
          "type": "text",
          "text": "融合这些参考图,生成一张统一风格的电商主视觉。只返回图片。Resolution target: 2K"
        }
      ]
    }
  ],
  "max_tokens": 2000
}

Node.js 示例 ​

javascript
import fs from 'node:fs/promises';

const API_KEY = process.env.ONE_XM_API_KEY;
const BASE_URL = 'https://api.1xm.ai/v1';

async function fileToDataUrl(path, mime = 'image/png') {
  const data = await fs.readFile(path);
  return `data:${mime};base64,${data.toString('base64')}`;
}

async function generateNanoBanana2({ prompt, inputImages = [], resolution = '1K' }) {
  const content = [];

  for (const imagePath of inputImages) {
    content.push({
      type: 'image_url',
      image_url: { url: await fileToDataUrl(imagePath) }
    });
  }

  content.push({
    type: 'text',
    text: `${prompt}\n\nGenerate image only. Resolution target: ${resolution}. Do not return explanation text.`
  });

  const res = await fetch(`${BASE_URL}/chat/completions`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gemini-3.1-flash-image-preview',
      messages: [{ role: 'user', content }],
      max_tokens: 2000
    })
  });

  const body = await res.json();
  if (!res.ok) {
    throw new Error(body.error?.message || 'Nano Banana request failed');
  }

  const message = body.choices?.[0]?.message?.content || '';
  const dataUrl = message.match(/data:image\/\w+;base64,[A-Za-z0-9+/=]+/)?.[0];
  const imageUrl = message.match(/https?:\/\/[^\s)\]>\"]+/)?.[0];

  return dataUrl || imageUrl;
}

const result = await generateNanoBanana2({
  prompt: '一张高级龙虾餐厅宣传海报,真实摄影风格',
  resolution: '1K'
});

console.log(result);

Python 示例 ​

python
import base64
import re
from pathlib import Path

import requests

API_KEY = "sk-你的Key"
BASE_URL = "https://api.1xm.ai/v1"


def file_to_data_url(path: str, mime: str = "image/png") -> str:
    data = Path(path).read_bytes()
    return f"data:{mime};base64,{base64.b64encode(data).decode()}"


def generate_nano_banana_2(prompt: str, input_images=None, resolution="1K"):
    input_images = input_images or []
    content = []

    for image_path in input_images:
        content.append({
            "type": "image_url",
            "image_url": {"url": file_to_data_url(image_path)},
        })

    content.append({
        "type": "text",
        "text": f"{prompt}\n\nGenerate image only. Resolution target: {resolution}. Do not return explanation text.",
    })

    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "gemini-3.1-flash-image-preview",
            "messages": [{"role": "user", "content": content}],
            "max_tokens": 2000,
        },
        timeout=180,
    )
    response.raise_for_status()

    result = response.json()
    message = result["choices"][0]["message"].get("content", "")

    data_url_match = re.search(r"data:image/\w+;base64,[A-Za-z0-9+/=]+", message)
    url_match = re.search(r"https?://[^\s)\]>\"]+", message)

    return data_url_match.group(0) if data_url_match else url_match.group(0)


image = generate_nano_banana_2("一张高级龙虾餐厅宣传海报,真实摄影风格")
print(image)

Nano Banana Pro 入参示例 ​

Nano Banana Pro 使用 Google GenAI SDK 调用,核心参数在 models.generate_content 中传入。

python
response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        input_image,
        "保持主体不变,生成高级电商海报",
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
    ),
)

generate_content 参数 ​

参数类型必填示例说明
modelstring✅gemini-3-pro-image-previewNano Banana Pro 模型 ID
contentsstring / array✅"A poster..." 或 [image, prompt]文本生图传字符串;图片编辑传图片对象 + prompt
config.response_modalitiesarray✅["TEXT", "IMAGE"]必须包含 IMAGE 才会返回图片
config.image_config.image_sizestring❌1K / 2K / 4K输出分辨率档位

contents 写法 ​

场景示例说明
文本生图contents="A cinematic product poster"只传文本 prompt
单图编辑contents=[input_image, "换成白底商品图"]图片对象放前,prompt 放后
多图融合contents=[img1, img2, img3, "融合成统一主视觉"]多张图片 + 一个最终指令

image_config.image_size ​

值说明
1K快速预览、低成本素材
2K商品图、海报、内容配图
4K高质量海报、精修图;耗时更长

Nano Banana Pro:Google GenAI SDK 接入 ​

Nano Banana Pro 推荐使用 Google GenAI SDK。你可以配置 GEMINI_API_KEY 和可选的 GEMINI_API_URL。

bash
pip install google-genai pillow
export GEMINI_API_KEY="你的 API Key"
# 如使用 1XM 提供的 Gemini 兼容入口,请按你的控制台配置填写:
export GEMINI_API_URL="https://api.1xm.ai/v1"

文本生图 ​

python
from google import genai
from google.genai import types
from PIL import Image
from io import BytesIO
import os

api_key = os.environ["GEMINI_API_KEY"]
api_url = os.environ.get("GEMINI_API_URL")

if api_url:
    client = genai.Client(api_key=api_key, http_options={"base_url": api_url.rstrip("/")})
else:
    client = genai.Client(api_key=api_key)

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="A cinematic lobster restaurant poster, premium lighting",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="1K"),
    ),
)

for part in response.parts:
    if part.inline_data is not None:
        image = Image.open(BytesIO(part.inline_data.data))
        image.save("nano-banana-pro-output.png")

参考图编辑 ​

python
from google import genai
from google.genai import types
from PIL import Image
from io import BytesIO
import os

client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options={"base_url": os.environ["GEMINI_API_URL"].rstrip("/")},
)

input_image = Image.open("input.png")

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        input_image,
        "保持主体不变,把背景换成高级商业摄影棚,输出一张电商海报。",
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
    ),
)

for part in response.parts:
    if part.inline_data is not None:
        image = Image.open(BytesIO(part.inline_data.data))
        image.save("edited.png")

分辨率 ​

两个模型都建议使用以下分辨率档位:

值说明
1K默认,适合快速预览、头像、小图和低成本场景
2K适合商品图、海报、内容配图
4K适合高质量海报、印刷、精修图;耗时更长

Nano Banana 2 通过 prompt 里的 Resolution target: 1K/2K/4K 传达分辨率目标。Nano Banana Pro 通过 image_config.image_size 设置。

返回图片处理建议 ​

返回形式处理方式
data:image/...;base64,...解析 base64 后保存成图片文件
https://... 图片 URL服务端下载后保存,或直接返回给前端展示
同时有文本和图片以图片为准,文本只作为日志或调试信息

生产环境建议把生成图片保存到你自己的对象存储或图床,避免只依赖临时响应内容。

异步任务调用 ​

如果你是 API 中转站、批量生图服务、SaaS 网页工具,或担心 2K / 4K、多参考图任务触发 Cloudflare / Nginx / SDK 超时,推荐直接使用 1XM 统一图片异步任务接口。Nano Banana 2 和 Nano Banana Pro 都通过同一个接口创建任务,完成后返回稳定图片 URL。

异步接口支持:

能力说明
文本生图只传 prompt
单图编辑image 传一个 data URL
多图融合image 传 data URL 数组
轮询结果用返回的 poll_url 或 GET /v1/images/tasks/{task_id}
Webhook可选传 webhook_url,任务完成或失败后回调
幂等重试推荐传 Idempotency-Key,避免网络重试造成重复任务和重复扣费

Nano Banana 2 异步任务 ​

bash
curl -X POST "https://api.1xm.ai/v1/images/tasks" \
  -H "Authorization: Bearer sk-your-1xm-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nb2-order-20260519-001" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "生成一张干净的电商产品海报,白色背景,真实摄影风格。只返回图片。",
    "size": "1:1",
    "quality": "1K"
  }'

Nano Banana Pro 异步任务 ​

bash
curl -X POST "https://api.1xm.ai/v1/images/tasks" \
  -H "Authorization: Bearer sk-your-1xm-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nbpro-order-20260519-001" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "保持主体不变,生成一张高级商业摄影棚海报,只返回图片。",
    "size": "16:9",
    "quality": "4K",
    "image": [
      "data:image/png;base64,...",
      "data:image/jpeg;base64,..."
    ],
    "webhook_url": "https://example.com/webhook"
  }'

轮询任务 ​

bash
curl "https://api.1xm.ai/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-your-1xm-api-key"

创建接口会先返回 queued:

json
{
  "id": "task_xxx",
  "object": "image.task",
  "status": "queued",
  "poll_url": "https://api.1xm.ai/v1/images/tasks/task_xxx",
  "poll_after": 5
}

成功后返回:

json
{
  "id": "task_xxx",
  "object": "image.task",
  "status": "succeeded",
  "data": [
    {
      "url": "https://img.1xm.ai/generated/xxx.png"
    }
  ],
  "usage": {
    "model": "gemini-3-pro-image-preview",
    "images": 1,
    "billed_quota": 310000
  }
}

异步字段约定 ​

字段说明
model必填;gemini-3.1-flash-image-preview 或 gemini-3-pro-image-preview
prompt必填;生图或编辑指令,建议写明“只返回图片”
size图片比例,例如 1:1、16:9、9:16;兼容 1024x1024 等常见尺寸
quality输出档位,支持 1K、2K、4K;Nano Banana Pro 建议用 2K / 4K
image可选;data URL 字符串或 data URL 数组,支持单图编辑和多图融合
webhook_url可选,任务完成或失败后回调
Idempotency-Key推荐必传,避免重试造成重复任务和重复扣费

Gemini 图片模型通常不会按 OpenAI 的 n 语义一次返回多张图。建议把单个任务当作生成 1 张图使用;如果需要多张图,创建多个异步任务,并用不同的 Idempotency-Key 管理重试。

注意

异步 JSON 任务中的 image 只接收 data URL。不要直接传远程图片 URL;请先由你的服务端下载图片、校验大小和格式,再转成 data:image/...;base64,...。

错误处理 ​

常见错误:

错误原因处理建议
401 UnauthorizedAPI Key 无效或未传检查 Authorization: Bearer sk-...
model not found模型名错误或账号未开通确认模型 ID 和分组权限
请求超时图片任务耗时较长改用 /v1/images/tasks 异步任务接口
无图片返回prompt 返回了文字解释在 prompt 中要求“只返回图片,不要解释文字”
图片太大data URL 过大服务端压缩图片或降低参考图数量

生产接入建议 ​

  • API Key 只放服务端,不能放前端。
  • 图片编辑时由服务端读取图片并转 data URL。
  • 对下游客户做并发限制,避免大量 2K/4K 请求同时进入。
  • 生成结果建议保存到你的对象存储,并记录任务参数、模型、耗时和输出 URL。
  • 参考图、prompt 和输出图可能包含用户隐私,不要在日志中打印完整 data URL。
  • 对于长耗时或批量任务,建议直接使用 /v1/images/tasks 异步任务接口,前端通过任务 ID 查询状态。

Agent Skill 示例 ​

如果你要在 Codex / Agent 工作流里直接调用 Nano Banana,可以参考 1XM Agent Skills 仓库:

text
https://github.com/coolyhx/1xm-agent-skills

其中包含:

  • 1xm-nano-banana-2
  • 1xm-nano-banana-pro

1XM.AI - 专为国内开发者打造的 AI API 中转服务