Nano Banana 图片编辑基于谷歌 Gemini 图像生成模型,目前推荐使用正式版:
- 正式版:
gemini-2.5-flash-image(推荐,支持 10 种宽高比和分辨率自定义)
- 预览版:
gemini-2.5-flash-image-preview(⚠️ 将于2025年10月30日下线)
重要提醒:预览版 gemini-2.5-flash-image-preview 将于 2025年10月30日 正式下线。届时本站将自动重定向到正式版 gemini-2.5-flash-image。建议尽快迁移到正式版以避免服务中断。
2025年10月3日更新:谷歌发布了正式版 gemini-2.5-flash-image,新增 10 种宽高比支持和分辨率自定义功能。正式版性能更稳定,功能更强大。
📚 最新文档
飞书完整使用指南 - 更新最快,支持评论互动访问飞书文档获取最新的使用教程、技巧分享和问题解答。文档持续更新,遇到问题可直接在飞书上评论交流。
编辑功能特点
- 🖼️ 多图合成:支持将多张图片合成为一张
- ✏️ 文本指令编辑:通过自然语言描述编辑需求
- 🔄 图片修改:添加、删除或修改图片中的元素
- 🎨 风格转换:改变图片风格、色彩、效果
- ⚡ 快速处理:平均 10 秒完成编辑任务
调用方式对比
API易 支持两种调用方式,您可以根据需求选择:
谷歌原生格式
推荐新用户使用
- 端点:
/v1beta/models/gemini-2.5-flash-image:generateContent
- ✅ 支持自定义分辨率和宽高比
- ✅ 图片生成和编辑都支持尺寸控制
- ✅ 支持 10 种宽高比输出
- 📖 使用谷歌官方 API 格式
OpenAI 兼容模式
兼容已有代码
- 端点:
/v1/chat/completions
- ⚠️ 生成图片默认 1:1 比例
- ✅ 编辑图片智能遵循原图比例
- ❌ 不支持自定义分辨率
- 📖 兼容 OpenAI 调用格式
快速选择指南
- ✅ 新项目 / 需要自定义尺寸 → 使用谷歌原生格式
- ✅ 已有 OpenAI 格式代码 → 继续使用 OpenAI 兼容模式
- ✅ 编辑图片且不需要指定尺寸 → 两种格式都可以
- ⚠️ 必须指定输出宽高比 → 只能用谷歌原生格式
端点对比表
| 特性 | 谷歌原生格式 | OpenAI 兼容模式 |
|---|
| 端点URL | /v1beta/models/gemini-2.5-flash-image:generateContent | /v1/chat/completions |
| 图片生成尺寸 | 支持 10 种宽高比自定义 | 默认 1:1 |
| 图片编辑尺寸 | 支持宽高比自定义 | 智能遵循原图比例 |
| 调用格式 | 谷歌官方格式 | OpenAI 格式 |
| 适用场景 | 需要精确控制输出尺寸 | 快速集成,兼容现有代码 |
编辑能力
支持的编辑类型
- 图片合成:将多张图片合并成一张
- 元素添加:在图片中添加新的对象或元素
- 风格修改:改变图片的艺术风格或色调
- 背景替换:更换图片背景
- 尺寸调整:改变图片比例或尺寸
- 细节优化:增强图片质量或修复缺陷
代码示例
根据您的需求,可以选择以下两种方式之一:
方式一:谷歌原生格式(推荐)
支持自定义分辨率和宽高比,使用谷歌官方 API 格式。
POST https://api.apiyi.com/v1beta/models/gemini-2.5-flash-image:generateContent
请求格式
{
"contents": [
{
"parts": [
{
"text": "编辑指令文本"
},
{
"inline_data": {
"mime_type": "image/jpeg",
"data": "base64编码的图片数据"
}
}
]
}
],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9"
}
}
}
支持的宽高比
21:9, 16:9, 4:3, 3:2, 1:1, 9:16, 3:4, 2:3, 5:4, 4:5
Bash 完整示例
参考完整的 Bash 脚本实现:gemini-image-edit.sh
#!/bin/bash
API_KEY="sk-your-api-key"
INPUT_IMAGE="./dog.png"
PROMPT="增加一只帅气的猫咪在狗狗的旁边"
ASPECT_RATIO="16:9"
OUTPUT_FILE="edited_$(date +%Y%m%d_%H%M%S).png"
API_URL="https://api.apiyi.com/v1beta/models/gemini-2.5-flash-image:generateContent"
{/* 编码图片 */}
IMG_BASE64=$(base64 -i "$INPUT_IMAGE")
MIME_TYPE="image/png"
{/* 构建请求 */}
curl -X POST "$API_URL" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [
{"text": "'"$PROMPT"'"},
{"inline_data": {"mime_type": "'"$MIME_TYPE"'", "data": "'"$IMG_BASE64"'"}}
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {"aspectRatio": "'"$ASPECT_RATIO"'"}
}
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > "$OUTPUT_FILE"
echo "图片已保存: $OUTPUT_FILE"
完整的 Bash 脚本包含错误处理和更多功能,请查看源代码。
方式二:OpenAI 兼容模式
兼容现有 OpenAI 格式代码,适合快速集成。编辑图片时会智能遵循原图比例。
POST https://api.apiyi.com/v1/chat/completions
请求格式
{
"model": "gemini-2.5-flash-image",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "编辑指令文本"
},
{
"type": "image_url",
"image_url": {
"url": "图片URL1"
}
},
{
"type": "image_url",
"image_url": {
"url": "图片URL2"
}
}
]
}
]
}
Python 完整示例
#!/usr/bin/env python3
import requests
import json
import base64
import re
from datetime import datetime
import sys
# 配置
API_KEY = "sk-" # 请替换为你的实际密钥
API_URL = "https://api.apiyi.com/v1/chat/completions"
def edit_images():
"""
图片编辑主函数
支持多图片合成和编辑
"""
# 设置请求头
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# 请求数据 - 多图片合成示例
data = {
"model": "gemini-2.5-flash-image",
"stream": False,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Combine 2 images and add a Corgi dog image"
},
{
"type": "image_url",
"image_url": {
"url": "https://github.com/dianping/cat/raw/master/cat-home/src/main/webapp/images/logo/cat_logo03.png"
}
},
{
"type": "image_url",
"image_url": {
"url": "https://raw.githubusercontent.com/leonindy/camel/master/camel-admin/src/main/webapp/assets/images/camel_logo_blue.png"
}
}
]
}
]
}
print("🚀 正在请求图片编辑API...")
print(f"📝 编辑指令: {data['messages'][0]['content'][0]['text']}")
print(f"🖼️ 输入图片数量: {len([c for c in data['messages'][0]['content'] if c['type'] == 'image_url'])}")
try:
# 发送请求
response = requests.post(API_URL, headers=headers, json=data)
response.raise_for_status()
print("✅ API请求成功,正在处理响应...")
# 解析响应
result = response.json()
# 提取内容
content = result['choices'][0]['message']['content']
print(f"📄 收到内容长度: {len(content)} 字符")
print(f"📄 内容预览: {content[:200]}...")
# 查找Base64图片数据
base64_data = None
# 方法1: 查找标准格式 data:image/type;base64,data
base64_match = re.search(r'data:image/[^;]+;base64,([A-Za-z0-9+/=]+)', content)
if base64_match:
base64_data = base64_match.group(1)
print("✅ 找到标准格式的Base64数据")
else:
# 方法2: 查找纯Base64数据(长字符串)
base64_match = re.search(r'([A-Za-z0-9+/=]{100,})', content)
if base64_match:
base64_data = base64_match.group(1)
print("✅ 找到纯Base64数据")
else:
print("❌ 错误: 无法找到Base64图片数据")
print("📄 完整响应内容:")
print(json.dumps(result, indent=2, ensure_ascii=False))
return False
# 生成文件名
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filename = f"edited_image_{timestamp}.png"
print("💾 正在保存编辑后的图片...")
# 解码并保存图片
try:
image_data = base64.b64decode(base64_data)
with open(filename, 'wb') as f:
f.write(image_data)
print(f"🎉 图片编辑完成!")
print(f"📁 文件保存为: {filename}")
print(f"📊 文件大小: {len(image_data):,} 字节")
return True
except Exception as e:
print(f"❌ 错误: 保存图片时出现问题: {e}")
return False
except requests.exceptions.RequestException as e:
print(f"❌ 错误: API请求失败: {e}")
return False
except KeyError as e:
print(f"❌ 错误: 响应格式不正确,缺少字段: {e}")
if 'response' in locals():
print("📄 完整响应内容:")
print(json.dumps(response.json(), indent=2, ensure_ascii=False))
return False
except Exception as e:
print(f"❌ 错误: 未知错误: {e}")
return False
def custom_edit_example():
"""
自定义编辑示例
"""
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# 自定义编辑任务
data = {
"model": "gemini-2.5-flash-image",
"stream": False,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please remove the background and make it transparent, then add a sunset background"
},
{
"type": "image_url",
"image_url": {
"url": "your_image_url_here" # 替换为你的图片URL
}
}
]
}
]
}
print("🎨 执行自定义编辑任务...")
# 调用编辑逻辑...
def main():
"""
主函数 - 演示不同的编辑功能
"""
print("=" * 60)
print("Nano Banana 图片编辑器 - Python版本")
print("=" * 60)
print(f"🕐 开始时间: {datetime.now()}")
# 检查API Key
if API_KEY == "sk-":
print("⚠️ 请先设置正确的API密钥")
return
print("\n🔧 可用的编辑功能:")
print("1. 多图片合成")
print("2. 背景替换")
print("3. 元素添加")
print("4. 风格转换")
print("\n🚀 执行多图片合成示例...")
success = edit_images()
print("\n" + "=" * 60)
if success:
print("🎉 编辑任务执行成功!")
print("✅ 图片已保存到本地")
else:
print("❌ 编辑任务执行失败!")
print("💡 请检查API密钥和网络连接")
print(f"🕐 结束时间: {datetime.now()}")
print("=" * 60)
if __name__ == "__main__":
success = main()
sys.exit(0 if success else 1)
编辑示例场景
1. 多图片合成
# 将两个logo合成,并添加新元素
{
"type": "text",
"text": "Combine these two logos and add a cute animal"
}
2. 背景替换
# 替换图片背景
{
"type": "text",
"text": "Remove the background and add a sunset landscape"
}
3. 风格转换
# 改变图片风格
{
"type": "text",
"text": "Convert this photo to anime/cartoon style"
}
4. 元素修改
# 添加或删除元素
{
"type": "text",
"text": "Add sunglasses to the person and change hair color to blue"
}
使用建议
选择合适的调用方式
推荐使用谷歌原生格式
- 功能最完整,支持自定义分辨率
- 性能更稳定,与谷歌官方同步更新
- 适合长期使用和新项目开发
查看 谷歌原生格式示例 我已经有使用 OpenAI 格式的代码,需要迁移吗?
无需强制迁移
- OpenAI 兼容模式会持续支持
- 老代码可以继续使用,无需修改
- 如需自定义输出尺寸,可考虑逐步迁移
查看 OpenAI 兼容模式示例
必须使用谷歌原生格式
- 只有谷歌原生格式支持
aspectRatio 参数
- 支持 10 种常用宽高比
- OpenAI 兼容模式编辑图片时会智能遵循原图比例
支持的宽高比:21:9, 16:9, 4:3, 3:2, 1:1, 9:16, 3:4, 2:3, 5:4, 4:5
2025年10月30日
- 预览版
gemini-2.5-flash-image-preview 将于此日期下线
- 本站会自动重定向到正式版
- 建议提前测试正式版
gemini-2.5-flash-image 的兼容性
迁移指南
如果您当前使用预览版模型或希望迁移到谷歌原生格式,请参考:
检查当前配置
确认您当前使用的模型名称和调用端点:
- 模型名称:
gemini-2.5-flash-image-preview → 改为 gemini-2.5-flash-image
- 如需自定义尺寸:迁移到谷歌原生格式端点
测试新配置
在开发环境测试新的模型或端点:
- 验证返回结果格式
- 检查输出图片质量和尺寸
- 确认性能和响应时间
逐步部署
建议采用灰度发布策略:
- 先在少量用户中测试
- 观察反馈和错误率
- 逐步扩大范围直至全量
最佳实践
编辑指令优化
明确具体
使用具体、明确的描述✅ “将背景改为蓝色海洋场景”
❌ “改变背景”
分步描述
将复杂编辑分解为步骤✅ “先移除背景,然后添加森林场景,最后增加阳光效果”
图片输入建议
- 格式支持:PNG、JPEG、GIF 等主流格式
- 分辨率:建议不超过 4096x4096
- 文件大小:单张图片建议不超过 10MB
- URL要求:确保图片URL可公开访问
编辑质量优化
- 高质量输入:使用清晰、高分辨率的原图
- 合理指令:避免过于复杂或矛盾的编辑要求
- 多次迭代:对复杂编辑可以分多步进行
- 参考示例:参考成功的编辑案例
错误处理
常见错误及解决方案
原因:图片URL不可访问或需要身份验证解决:
- 使用公开可访问的图片URL
- 检查URL是否正确
- 确保图片服务器允许外部访问
原因:编辑指令不够明确或输入图片质量较低解决:
- 使用更具体、明确的编辑指令
- 提供高质量的输入图片
- 分步骤进行复杂编辑
原因:编辑任务失败或响应格式异常解决:
- 检查编辑指令是否合理
- 确认输入图片是否有效
- 查看完整的API响应内容
定价信息
- 按次计费:$0.025/次编辑任务
- 官网对比:官网定价 $0.04/次
- 实际成本:结合充值优惠约 ¥0.14/次
- 节省幅度:相比官网节省约 50%
高级功能
批量编辑
def batch_edit_images(image_urls, edit_instruction):
"""批量编辑多张图片"""
results = []
for i, url in enumerate(image_urls):
data = {
"model": "gemini-2.5-flash-image",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": edit_instruction},
{"type": "image_url", "image_url": {"url": url}}
]
}]
}
# 执行编辑...
results.append(result)
return results
编辑历史记录
def save_edit_history(original_url, instruction, result_path):
"""保存编辑历史记录"""
history = {
"timestamp": datetime.now().isoformat(),
"original_image": original_url,
"edit_instruction": instruction,
"result_path": result_path
}
# 保存到文件或数据库...
相关文档
编辑技巧:对于复杂的编辑需求,建议先用简单指令测试效果,再逐步增加复杂度。这样可以获得更好的编辑结果。