最近更新：2026年3月6日 07:13

图像生成 API 使用指南

概述

Nano Banana 是 NextAI Code 基于 Google Gemini 模型推出的 AI 图像系列，提供两大核心能力：

功能	端点	说明
文生图	`/v1/images/generations`	根据文字描述生成图片
图生图	`/v1/images/edits`	基于参考图像进行编辑或风格转换

使用场景

场景	说明
内容创作	生成文章配图、社交媒体素材、营销海报
设计辅助	快速生成设计草图、风格参考、概念图
批量生图	脚本自动化批量生成产品图、变体图
图像编辑	风格转换、背景替换、艺术化处理

该系列模型具有极高的指令遵循能力和图像质量，支持多种画幅比例和分辨率设置。

认证

所有请求需携带 API Key。访问令牌管理页面创建新令牌（以 sk- 开头）。

支持的模型

模型名称	产品名称	分辨率	文生图	图生图
`gemini-2.5-flash-image`	Nano Banana	仅 1K	✅	✅
`gemini-2.5-flash-image-preview`	Nano Banana (预览版)	仅 1K	✅	✅
`gemini-3-pro-image-preview`	Nano Banana Pro	1K / 2K / 4K	✅	✅

重要限制: Nano Banana 系列每次请求仅支持生成 1 张 图片。

模型选择建议

追求速度: 选择 gemini-2.5-flash-image，生成速度最快
追求画质: 选择 gemini-3-pro-image-preview，支持高分辨率输出

通用参数

以下参数在文生图和图生图 API 中通用。

size 参数 (宽高比)

size 参数用于控制输出图片的宽高比，支持两种格式：

格式 1: 比例格式 (推荐)

值	说明	适用场景
`1:1`	正方形	头像、社交媒体
`16:9`	横向宽屏	电脑壁纸、视频封面
`9:16`	纵向竖屏	手机壁纸、Stories
`3:2`	横向标准	摄影作品
`2:3`	纵向标准	海报设计
`4:3`	横向传统	传统显示器
`3:4`	纵向传统	竖版海报
`21:9`	超宽屏	电影感画面

格式 2: 像素格式 (OpenAI 兼容)

输入值	映射结果
`1024x1024`	`1:1`
`1792x1024`	`16:9`
`1024x1792`	`9:16`
`1536x1024`	`3:2`
`1024x1536`	`2:3`

默认值: 不传 size 参数时，默认为 1:1。

注意: size 参数仅控制宽高比，实际像素尺寸由 quality 参数决定。

quality 参数 (分辨率)

仅 Nano Banana Pro (gemini-3-pro-image-preview) 支持此参数。 Nano Banana (gemini-2.5-flash-image) 始终输出 1K 分辨率，忽略此参数。

值	分辨率	1:1 像素
`standard` / `low` / `medium`	1K	1024×1024
`hd` / `high`	2K	2048×2048
`4k` / `ultra`	4K	4096×4096

默认值: 不传 quality 参数时，默认为 1K。

输出尺寸对照表

根据 size（宽高比）和 quality（分辨率）的组合，实际输出像素如下：

宽高比	1K (standard)	2K (hd)	4K (ultra)
1:1	1024×1024	2048×2048	4096×4096
16:9	1820×1024	3640×2048	7280×4096
9:16	1024×1820	2048×3640	4096×7280
3:2	1536×1024	3072×2048	6144×4096
2:3	1024×1536	2048×3072	4096×6144
4:3	1365×1024	2731×2048	5461×4096
3:4	1024×1365	2048×2731	4096×5461
21:9	2389×1024	4778×2048	9557×4096

文生图 API

根据文字描述生成图片。

端点信息

属性	值
URL	`POST https://www.nextai-code.com/v1/images/generations`
认证	Bearer Token
Content-Type	`application/json`

请求参数

参数	类型	必填	说明
`model`	string	✅	模型名称
`prompt`	string	✅	图片描述 (建议使用英文)
`size`	string	❌	宽高比 (默认 `1:1`)
`quality`	string	❌	分辨率 (默认 `standard`)
`n`	integer	❌	生成数量 (必须为 1)

请求示例

cURL

curl -X POST "https://www.nextai-code.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-..." \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A futuristic city with neon lights, cyberpunk style",
    "size": "16:9",
    "quality": "hd"
  }'

Python (OpenAI SDK)

from openai import OpenAI
import base64

client = OpenAI(
    api_key="sk-...",
    base_url="https://www.nextai-code.com/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image-preview",
    prompt="A cute astronaut cat on the moon",
    size="1:1",
    quality="hd",
    n=1
)

# 保存图片
image_data = base64.b64decode(response.data[0].b64_json)
with open("output.jpg", "wb") as f:
    f.write(image_data)

图生图 API

基于参考图像进行编辑、风格转换或内容修改。

端点信息

属性	值
URL	`POST https://www.nextai-code.com/v1/images/edits`
认证	Bearer Token
Content-Type	`multipart/form-data` 或 `application/json`

请求参数

参数	类型	必填	说明
`model`	string	✅	模型名称
`prompt`	string	✅	编辑指令
`image`	file/string/array	✅	输入图像
`size`	string	❌	输出宽高比 (默认 `1:1`)
`quality`	string	❌	输出分辨率 (默认 `standard`)

image 参数格式

image 参数支持多种输入方式：

Content-Type	格式	示例
`multipart/form-data`	文件上传	`-F "image=@photo.jpg"`
`application/json`	Base64 Data URL	`"data:image/jpeg;base64,..."`
`application/json`	HTTP URL	`"https://example.com/photo.jpg"`
`application/json`	多图数组	`["data:image/...","data:image/..."]`

多图输入: Nano Banana Pro 最多支持 14 张 参考图像。

请求示例

cURL (文件上传)

curl -X POST "https://www.nextai-code.com/v1/images/edits" \
  -H "Authorization: Bearer sk-..." \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=Transform into a watercolor painting style" \
  -F "image=@photo.jpg" \
  -F "size=1:1" \
  -F "quality=hd"

cURL (JSON Base64)

curl -X POST "https://www.nextai-code.com/v1/images/edits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-..." \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "Transform into a Vogue magazine cover with dramatic lighting",
    "image": "data:image/jpeg;base64,/9j/4AAQ...",
    "size": "3:4",
    "quality": "hd"
  }'

Python

from openai import OpenAI
import base64
from pathlib import Path

client = OpenAI(
    api_key="sk-...",
    base_url="https://www.nextai-code.com/v1"
)

# 读取并编码图片
image_bytes = Path("selfie.jpg").read_bytes()
image_b64 = base64.b64encode(image_bytes).decode()
image_data_url = f"data:image/jpeg;base64,{image_b64}"

response = client.images.edit(
    model="gemini-3-pro-image-preview",
    prompt="Transform into a professional portrait with studio lighting",
    image=image_data_url,
    size="1:1"
)

# 保存结果
result_data = base64.b64decode(response.data[0].b64_json)
Path("output.jpg").write_bytes(result_data)

响应格式

两个 API 的响应格式相同。

成功响应

{
  "created": 1734567890,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQEBLAEs...",
      "url": "",
      "revised_prompt": ""
    }
  ]
}

响应字段

字段	类型	说明
`created`	integer	Unix 时间戳
`data`	array	图片数据数组
`data[].b64_json`	string	Base64 编码的图片 (JPEG)

错误处理

状态码	错误代码	说明	处理建议
400	`prompt_blocked`	提示词或生成内容违规	修改提示词，避免敏感内容
401	`invalid_api_key`	API Key 无效	检查令牌是否正确
429	`rate_limit_exceeded`	请求频率超限	降低请求频率或稍后重试
500	`bad_response_body`	生成失败	修改提示词或重试

最佳实践

提示词建议

使用英文提示词: 英文通常能获得更精准的细节控制
描述要具体: 详细描述场景、颜色、风格、光线等
添加风格关键词: 如 "cinematic lighting"、"professional photography"

超时设置

图片生成耗时较长，请设置充足的超时时间：

模型	典型耗时	建议超时
`gemini-2.5-flash-image`	1-3 分钟	5 分钟
`gemini-3-pro-image-preview`	2-5 分钟	10 分钟

内容安全

Nano Banana 内置了严格的内容安全过滤器。包含暴力、色情、仇恨言论等内容的请求将被拒绝，返回 prompt_blocked 错误。