Appearance
Nano Banana 图片 API
Nano Banana 是 1XM.AI 支持的 Gemini 图像生成能力,适合文本生图、图片编辑、多参考图融合、商品图、海报图、角色一致性和营销素材生成。
本文覆盖两个常用模型:
| 模型 | 模型 ID | 推荐场景 | 接入方式 |
|---|---|---|---|
| Nano Banana 2 | gemini-3.1-flash-image-preview | 快速生图、高并发、轻量商品图和素材生成 | 同步 /chat/completions、Gemini 原生 /v1beta/models/{model_id}:generateContent 或异步 /images/tasks |
| Nano Banana Pro | gemini-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 URL | https://api.1xm.ai/v1 |
| Endpoint | POST /chat/completions |
| Gemini 原生 Endpoint | POST 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
| 项目 | 值 |
|---|---|
| 推荐 SDK | google-genai |
| 模型名 | gemini-3-pro-image-preview |
| API Key | GEMINI_API_KEY |
| 自定义 Endpoint | GEMINI_API_URL,按你的 1XM 接入配置填写 |
| Gemini 原生 Endpoint | POST 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
}顶层参数
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
model | string | ✅ | gemini-3.1-flash-image-preview | Nano Banana 2 模型 ID |
messages | array | ✅ | 见上方示例 | OpenAI-compatible 消息数组 |
max_tokens | integer | ❌ | 2000 | 给图片响应保留足够输出空间,建议 2000 |
temperature | number | ❌ | 0.7 | 可选;需要更稳定输出时可降低 |
messages[].content[] 参数
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
type | string | ✅ | text / image_url | 内容块类型 |
text | string | 文本块必填 | 生成一张电商海报... | 生图或编辑指令;建议写明“只返回图片” |
image_url.url | string | 图片块必填 | 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 2 | gemini-3.1-flash-image-preview |
| Nano Banana Pro | gemini-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 参数
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
model | string | ✅ | gemini-3-pro-image-preview | Nano Banana Pro 模型 ID |
contents | string / array | ✅ | "A poster..." 或 [image, prompt] | 文本生图传字符串;图片编辑传图片对象 + prompt |
config.response_modalities | array | ✅ | ["TEXT", "IMAGE"] | 必须包含 IMAGE 才会返回图片 |
config.image_config.image_size | string | ❌ | 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 Unauthorized | API 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-21xm-nano-banana-pro