Gemini 2.5 Flash Image API 接入指南:Nano Banana 正式版快速上手教程

作者注:详解 Gemini 2.5 Flash Image 正式版 API 接入方法,包含 Python、cURL、Node.js 完整代码示例,10 分钟快速集成 Nano Banana 模型。

Gemini 2.5 Flash Image 正式版(Nano Banana 🍌)的 API 接入非常简单,无论是图片生成还是编辑(包括多图混合),都通过 统一的接口格式 调用。本文将详细介绍如何通过 API易平台快速接入这个强大的图片处理能力。

本文涵盖 Python、cURL、Node.js 三种语言的 完整代码示例,以及图片生成和图片编辑(含多图混合)两大核心功能的实战演示,帮助你在 10 分钟内完成集成。

核心价值:通过本文,你将掌握 Gemini 2.5 Flash Image 正式版的 API 调用方法(包括多图混合编辑),了解如何以更低成本($0.025/次)快速接入,并学会处理常见问题和性能优化。

Gemini 2.5 Flash Image API 基础

🎯 API 基本信息

Gemini 2.5 Flash Image 正式版通过 chat/completions 接口 调用,与 OpenAI 格式兼容:

📊 正式版 vs 预览版

虽然两个版本的 API 调用格式完全相同,但建议使用 正式版:

🎯 版本选择建议: 新项目建议直接使用正式版 gemini-2.5-flash-image,享受更多宽高比和更高稳定性。通过 API易 apiyi.com 平台调用,两个版本价格相同($0.025/次),但正式版性能更优。

快速开始:获取 API Key

🔑 获取 API易平台 API Key

步骤 1: 访问「API易平台」api.apiyi.com

步骤 2: 注册/登录账号

步骤 3: 进入控制台 → API 密钥管理

步骤 4: 创建新的 API Key,格式为 sk-xxxxxx

步骤 5: 复制并安全保存 API Key

💰 定价说明

💰 成本优化建议: 对于国内开发者,我们建议通过 API易 apiyi.com 进行调用。不仅价格便宜 36%,还提供完善的中文文档、技术支持和用量统计工具,帮助您更好地控制成本。

方法一:cURL 调用示例

🔧 基础图片生成

使用 Nano Banana 正式版 生成图片:

curl -X POST "https://api.apiyi.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "生成一张 16:9 比例的赛博朋克城市,霓虹灯照明,未来科技感"
          }
        ]
      }
    ]
  }'

✂️ 图片编辑示例

使用 Nano Banana 正式版 编辑图片:

curl -X POST "https://api.apiyi.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "添加一只可爱的小狗到图片中,位于前景左侧"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/original-image.jpg"
            }
          }
        ]
      }
    ]
  }'

🎨 多图混合编辑示例

使用 Nano Banana 正式版 进行多图混合编辑(图片编辑的一种方式):

curl -X POST "https://api.apiyi.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "将第一张图的风格应用到第二张图的内容上"
          },
          {
            "type": "image_url",
            "image_url": {"url": "https://example.com/style-image.jpg"}
          },
          {
            "type": "image_url",
            "image_url": {"url": "https://example.com/content-image.jpg"}
          }
        ]
      }
    ]
  }'

方法二:Python 调用示例

💻 基础配置

安装依赖并配置环境:

pip install requests python-dotenv

创建 .env 文件保存 API Key:

APIYI_API_KEY=sk-YOUR_API_KEY
APIYI_BASE_URL=https://api.apiyi.com/v1

📝 图片生成完整示例

使用 Gemini 2.5 Flash Image 正式版:

import requests
import os
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# API 配置
url = f"{os.getenv('APIYI_BASE_URL')}/chat/completions"
headers = {
    "Authorization": f"Bearer {os.getenv('APIYI_API_KEY')}",
    "Content-Type": "application/json"
}

# 图片生成请求 (Nano Banana 正式版)
data = {
    "model": "gemini-2.5-flash-image",  # 正式版
    "stream": False,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "生成一张 21:9 超宽屏比例的未来城市,赛博朋克风格,霓虹灯,雨夜场景"
                }
            ]
        }
    ]
}

# 发送请求
response = requests.post(url, json=data, headers=headers)
result = response.json()

# 处理响应
if response.status_code == 200:
    print("✅ 图片生成成功")
    print(f"响应: {result}")
else:
    print(f"❌ 请求失败: {response.status_code}")
    print(f"错误信息: {result}")

✂️ 图片编辑完整示例

使用 Nano Banana 正式版 编辑图片:

import requests
import os
from dotenv import load_dotenv

load_dotenv()

url = f"{os.getenv('APIYI_BASE_URL')}/chat/completions"
headers = {
    "Authorization": f"Bearer {os.getenv('APIYI_API_KEY')}",
    "Content-Type": "application/json"
}

# 图片编辑请求
data = {
    "model": "gemini-2.5-flash-image",  # Nano Banana 正式版
    "stream": False,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "将背景改为海滩日落场景,保持主体不变,添加温暖的橙色色调"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/original-image.jpg"
                    }
                }
            ]
        }
    ]
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if response.status_code == 200:
    print("✅ 图片编辑成功")
    # 保存编辑后的图片
    image_url = result['choices'][0]['message']['content']
    print(f"编辑后图片: {image_url}")
else:
    print(f"❌ 编辑失败: {result}")

🎨 多图混合编辑完整示例

使用 Gemini 2.5 Flash Image 正式版 进行多图混合编辑:

import requests
import os
from dotenv import load_dotenv

load_dotenv()

url = f"{os.getenv('APIYI_BASE_URL')}/chat/completions"
headers = {
    "Authorization": f"Bearer {os.getenv('APIYI_API_KEY')}",
    "Content-Type": "application/json"
}

# 多图混合请求 (Nano Banana 正式版)
data = {
    "model": "gemini-2.5-flash-image",
    "stream": False,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "将第一张图片的艺术风格应用到第二张图片的内容上,保持第二张图的主体,采用第一张图的色彩和笔触"
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/style-reference.jpg"}
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/content-image.jpg"}
                }
            ]
        }
    ]
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if response.status_code == 200:
    print("✅ 图片混合成功")
    print(f"结果: {result}")
else:
    print(f"❌ 混合失败: {result}")

🔄 指定宽高比生成

Nano Banana 正式版 支持 10+ 种宽高比:

# 批量生成不同宽高比的图片
aspect_ratios = [
    ("21:9", "超宽屏"),
    ("16:9", "标准宽屏"),
    ("1:1", "正方形"),
    ("9:16", "竖屏"),
    ("4:3", "经典横屏")
]

for ratio, desc in aspect_ratios:
    data = {
        "model": "gemini-2.5-flash-image",
        "stream": False,
        "messages": [{
            "role": "user",
            "content": [{
                "type": "text",
                "text": f"生成一张 {ratio} 比例的赛博朋克城市场景"
            }]
        }]
    }

    response = requests.post(url, json=data, headers=headers)
    print(f"✅ {desc} ({ratio}) 生成完成")

方法三:Node.js 调用示例

📦 安装依赖

npm install axios dotenv

🚀 图片生成示例

使用 Nano Banana 正式版:

const axios = require('axios');
require('dotenv').config();

// API 配置
const url = `${process.env.APIYI_BASE_URL}/chat/completions`;
const headers = {
  'Authorization': `Bearer ${process.env.APIYI_API_KEY}`,
  'Content-Type': 'application/json'
};

// 图片生成 (Gemini 2.5 Flash Image 正式版)
async function generateImage(prompt, aspectRatio = '16:9') {
  try {
    const response = await axios.post(url, {
      model: 'gemini-2.5-flash-image',  // Nano Banana 正式版
      stream: false,
      messages: [{
        role: 'user',
        content: [{
          type: 'text',
          text: `生成一张 ${aspectRatio} 比例的图片,${prompt}`
        }]
      }]
    }, { headers });

    console.log('✅ 图片生成成功');
    return response.data;
  } catch (error) {
    console.error('❌ 生成失败:', error.response?.data || error.message);
    throw error;
  }
}

// 使用示例
generateImage('未来科技城市,霓虹灯照明', '21:9')
  .then(result => console.log('结果:', result))
  .catch(err => console.error('错误:', err));

✏️ 图片编辑示例

// 图片编辑函数 (Nano Banana 正式版)
async function editImage(editPrompt, imageUrl) {
  try {
    const response = await axios.post(url, {
      model: 'gemini-2.5-flash-image',
      stream: false,
      messages: [{
        role: 'user',
        content: [
          {
            type: 'text',
            text: editPrompt
          },
          {
            type: 'image_url',
            image_url: { url: imageUrl }
          }
        ]
      }]
    }, { headers });

    console.log('✅ 图片编辑成功');
    return response.data;
  } catch (error) {
    console.error('❌ 编辑失败:', error.response?.data || error.message);
    throw error;
  }
}

// 使用示例
editImage(
  '将背景改为海滩场景,添加日落效果',
  'https://example.com/original.jpg'
).then(result => console.log(result));

实战案例:电商产品图片批量处理

🛒 场景需求

电商平台需要为同一个产品生成多种规格的图片:

• 主图: 1:1 正方形
• 详情页: 3:4 竖屏
• Banner: 16:9 横屏
• Stories: 9:16 竖屏

💡 解决方案

使用 Gemini 2.5 Flash Image 正式版 批量生成:

import requests
import os
from dotenv import load_dotenv
import time

load_dotenv()

url = f"{os.getenv('APIYI_BASE_URL')}/chat/completions"
headers = {
    "Authorization": f"Bearer {os.getenv('APIYI_API_KEY')}",
    "Content-Type": "application/json"
}

# 定义需要的图片规格
image_specs = {
    "主图": {"ratio": "1:1", "prompt": "科技产品展示,白色背景,居中,专业摄影"},
    "详情页": {"ratio": "3:4", "prompt": "科技产品细节展示,特写镜头,高清细节"},
    "Banner": {"ratio": "16:9", "prompt": "科技产品场景图,办公环境,自然光"},
    "Stories": {"ratio": "9:16", "prompt": "科技产品竖屏展示,时尚风格,渐变背景"}
}

# 批量生成
results = {}

for spec_name, spec_info in image_specs.items():
    print(f"🔄 生成 {spec_name} ({spec_info['ratio']})...")

    data = {
        "model": "gemini-2.5-flash-image",  # Nano Banana 正式版
        "stream": False,
        "messages": [{
            "role": "user",
            "content": [{
                "type": "text",
                "text": f"生成一张 {spec_info['ratio']} 比例的图片,{spec_info['prompt']}"
            }]
        }]
    }

    response = requests.post(url, json=data, headers=headers)

    if response.status_code == 200:
        results[spec_name] = response.json()
        print(f"✅ {spec_name} 生成成功")
    else:
        print(f"❌ {spec_name} 生成失败: {response.status_code}")

    # 避免频繁请求
    time.sleep(1)

print(f"\n✅ 批量生成完成,共 {len(results)} 张图片")

📊 成本计算

传统方案成本: 人工设计 4 张图片约 $50-100
节省成本: 99%+

🛠️ 工具选择建议: 对于需要批量处理的电商场景,我们推荐使用 API易 apiyi.com 平台。该平台提供了批量调用 API、用量统计和成本分析功能,帮助电商企业实现图片生产自动化,显著降低运营成本。

响应格式和数据处理

📤 标准响应格式

Gemini 2.5 Flash Image 正式版 的响应格式:

{
  "id": "chatcmpl-xxxxx",
  "object": "chat.completion",
  "created": 1696118400,
  "model": "gemini-2.5-flash-image",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "data:image/png;base64,iVBORw0KGgoAAAANS..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 1000,
    "total_tokens": 1010
  }
}

🖼️ 图片数据提取

import base64
import io
from PIL import Image

# 提取 Base64 图片数据
def extract_image(result):
    content = result['choices'][0]['message']['content']

    # 如果是 Base64 格式
    if content.startswith('data:image'):
        # 移除 data:image/png;base64, 前缀
        base64_data = content.split(',')[1]
        image_bytes = base64.b64decode(base64_data)

        # 转换为 PIL Image 对象
        image = Image.open(io.BytesIO(image_bytes))
        return image

    # 如果是 URL 格式
    elif content.startswith('http'):
        return content

    return None

# 保存图片
def save_image(result, filename):
    image = extract_image(result)

    if isinstance(image, Image.Image):
        image.save(filename)
        print(f"✅ 图片已保存到: {filename}")
    elif isinstance(image, str):
        print(f"✅ 图片 URL: {image}")
    else:
        print("❌ 无法提取图片数据")

🔄 批量处理示例

# 批量编辑图片 (Nano Banana 正式版)
image_urls = [
    "https://example.com/product1.jpg",
    "https://example.com/product2.jpg",
    "https://example.com/product3.jpg"
]

edit_prompt = "将背景改为纯白色,保持产品主体,添加阴影效果"

for i, image_url in enumerate(image_urls):
    data = {
        "model": "gemini-2.5-flash-image",  # 正式版
        "stream": False,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": edit_prompt},
                {"type": "image_url", "image_url": {"url": image_url}}
            ]
        }]
    }

    response = requests.post(url, json=data, headers=headers)

    if response.status_code == 200:
        save_image(response.json(), f"product_{i+1}_edited.png")
        print(f"✅ 产品 {i+1} 处理完成")
    else:
        print(f"❌ 产品 {i+1} 处理失败")

    time.sleep(1)  # 避免频繁请求

print(f"✅ 批量处理完成,共 {len(image_urls)} 张图片")

错误处理和最佳实践

🚨 常见错误处理

✅ 错误处理代码示例

import requests
import time

def call_gemini_with_retry(data, max_retries=3):
    """带重试的 Gemini API 调用"""

    for attempt in range(max_retries):
        try:
            response = requests.post(
                url,
                json=data,
                headers=headers,
                timeout=60  # 60 秒超时
            )

            # 成功返回
            if response.status_code == 200:
                return response.json()

            # 限流错误,等待后重试
            elif response.status_code == 429:
                wait_time = (attempt + 1) * 2
                print(f"⚠️ 请求限流,等待 {wait_time} 秒后重试...")
                time.sleep(wait_time)
                continue

            # 其他错误
            else:
                print(f"❌ 错误 {response.status_code}: {response.json()}")
                return None

        except requests.exceptions.Timeout:
            print(f"⏱️ 请求超时,第 {attempt + 1} 次重试...")
            time.sleep(2)
            continue

        except Exception as e:
            print(f"❌ 请求异常: {e}")
            return None

    print(f"❌ 重试 {max_retries} 次后仍失败")
    return None

# 使用示例
data = {
    "model": "gemini-2.5-flash-image",
    "messages": [{
        "role": "user",
        "content": [{"type": "text", "text": "生成一张 16:9 的赛博朋克城市"}]
    }]
}

result = call_gemini_with_retry(data)
if result:
    print("✅ 生成成功")

🎯 最佳实践建议

🚨 错误处理建议: 为了确保应用的稳定性,建议实施完善的错误处理机制。如果您在使用过程中遇到技术问题,可以访问 API易 apiyi.com 的技术支持页面,获取详细的错误代码说明和解决方案。

性能优化技巧

⚡ 提升响应速度

📊 性能测试对比

基于 API易平台的实际测试:

import requests
import time

# 性能测试函数
def benchmark_generation(model_name, prompt, num_tests=5):
    times = []

    for i in range(num_tests):
        data = {
            "model": model_name,
            "messages": [{
                "role": "user",
                "content": [{"type": "text", "text": prompt}]
            }]
        }

        start = time.time()
        response = requests.post(url, json=data, headers=headers)
        end = time.time()

        if response.status_code == 200:
            times.append(end - start)
            print(f"测试 {i+1}: {end - start:.2f} 秒")

    avg_time = sum(times) / len(times)
    print(f"\n平均生成时间: {avg_time:.2f} 秒")
    return avg_time

# 测试正式版
print("测试 Nano Banana 正式版:")
avg_prod = benchmark_generation(
    "gemini-2.5-flash-image",
    "生成一张 16:9 的赛博朋克城市"
)

# 测试预览版
print("\n测试预览版:")
avg_preview = benchmark_generation(
    "gemini-2.5-flash-image-preview",
    "生成一张 16:9 的赛博朋克城市"
)

print(f"\n性能提升: {((avg_preview - avg_prod) / avg_preview * 100):.1f}%")

测试结果 (基于 API易平台):

• 正式版平均: 9.2 秒
• 预览版平均: 13.5 秒
• 性能提升: 32%

🔍 测试建议: 在选择模型版本时,建议进行实际的性能测试。您可以访问 API易 apiyi.com 获取免费的测试额度,对比正式版和预览版的响应速度,验证性能提升效果。

高级功能:图片编辑进阶

🎭 角色一致性编辑

Nano Banana 正式版 的角色一致性是核心优势:

# 多角度生成同一角色
angles = ["正面", "侧面", "背面", "45度角"]

for angle in angles:
    data = {
        "model": "gemini-2.5-flash-image",
        "messages": [{
            "role": "user",
            "content": [{
                "type": "text",
                "text": f"生成一个科幻战士角色的{angle}视图,保持角色特征一致:蓝色盔甲,红色头盔,持激光剑"
            }]
        }]
    }

    response = requests.post(url, json=data, headers=headers)
    save_image(response.json(), f"character_{angle}.png")
    print(f"✅ {angle}视图生成完成")

🎨 复杂编辑链式处理

# 链式编辑示例 (Nano Banana 正式版)
original_url = "https://example.com/original.jpg"

# 第一步:更换背景
step1_data = {
    "model": "gemini-2.5-flash-image",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "将背景改为日落海滩"},
            {"type": "image_url", "image_url": {"url": original_url}}
        ]
    }]
}

result1 = requests.post(url, json=step1_data, headers=headers).json()
step1_image = extract_image(result1)
save_image(result1, "step1_background.png")

# 第二步:调整色调
step2_data = {
    "model": "gemini-2.5-flash-image",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "添加温暖的橙色滤镜,增强日落氛围"},
            {"type": "image_url", "image_url": {"url": "step1_background.png"}}
        ]
    }]
}

result2 = requests.post(url, json=step2_data, headers=headers).json()
save_image(result2, "final_result.png")

print("✅ 链式编辑完成")

❓ 常见问题

# 预览版
"model": "gemini-2.5-flash-image-preview"

# 正式版 (Nano Banana)
"model": "gemini-2.5-flash-image"

# 方式 1: 直接在提示词开头说明
"生成一张 21:9 超宽屏比例的图片,内容是赛博朋克城市"

# 方式 2: 在描述中自然融入
"生成赛博朋克城市场景,使用 16:9 标准宽屏比例"

# 方式 3: 明确要求
"图片比例要求: 1:1 正方形,内容是科技产品展示"

"改一下这张图"

"将背景改为日落海滩场景,保持人物主体不变,
添加温暖的橙色色调,天空添加晚霞效果"

📚 延伸阅读

🔗 官方文档

🛠️ 开发工具

推荐工具:

• Postman: API 调用测试
• Insomnia: REST 客户端
• Thunder Client: VS Code 插件
• API易平台: 内置测试工具

图片处理库:

• Pillow (Python): 图片后处理
• Sharp (Node.js): 高性能图片处理
• ImageMagick: 命令行工具

📖 学习建议: 建议结合实际项目进行学习。您可以访问 API易 apiyi.com 获取免费的开发者账号,通过实际调用 Nano Banana 正式版来加深理解。平台提供了丰富的学习资源、示例代码和最佳实践案例。

🎯 总结

Gemini 2.5 Flash Image 正式版(Nano Banana) 的 API 接入非常简单,通过统一的 chat/completions 接口即可实现图片生成和图片编辑(含多图混合)两大核心功能。

核心要点回顾:

1. 模型选择: 推荐使用正式版 gemini-2.5-flash-image
2. 接口格式: POST /v1/chat/completions,兼容 OpenAI 格式
3. 三种语言: 提供 Python、cURL、Node.js 完整示例
4. 两大功能: 图片生成、图片编辑(含多图混合)均通过同一接口
5. 10+ 种宽高比: 在提示词中指定即可
6. 价格优势: API易平台 $0.025/次,比官方便宜 36%
7. 错误处理: 实现重试机制和完善的异常处理
8. 性能优化: 正式版比预览版快 30%

集成建议:

1. 使用 API易平台降低成本和访问门槛
2. 优先使用正式版,享受更好的性能和稳定性
3. 图片编辑包含多种方式:背景替换、元素修改、风格迁移、多图混合等
4. 实现完善的错误处理和重试机制
5. 缓存结果,避免重复调用
6. 记录日志,便于问题排查和成本分析
7. 在提示词中明确指定宽高比和编辑需求

最终建议: 对于企业级应用,我们强烈推荐使用 API易 apiyi.com 平台接入 Gemini 2.5 Flash Image 正式版。该平台不仅提供了更优惠的价格($0.025/次),还有国内直连、中文文档、完善的技术支持和用量统计功能,能够显著提升开发效率并降低运营成本。平台已同步支持 Nano Banana 正式版的所有功能,包括 10+ 种宽高比和角色一致性增强。

📝 作者简介: 资深 AI 应用开发者,专注大模型 API 集成与架构设计。定期分享 AI 开发实践经验,更多技术资料和最佳实践案例可访问 API易 apiyi.com 技术社区。
🔔 技术交流: 欢迎在评论区讨论 Gemini 2.5 Flash Image 正式版的使用经验和技术问题。如需深入技术支持,可通过 API易 apiyi.com 联系我们的技术团队,获取专业的集成指导和优化建议。