Nano Banana Pro API 同步與異步調用的 4 個核心差異

調用 Nano Banana Pro API 生成圖像時，同步調用和異步調用有什麼區別？目前 APIYI 和 Gemini 官方都僅支持同步調用模式，但 APIYI 通過提供 OSS URL 圖片輸出顯著改善了用戶體驗。本文將系統解析同步與異步調用的核心差異，以及 APIYI 平臺在圖片輸出格式上的優化方案。

核心價值: 讀完本文，你將理解同步調用與異步調用在 API 設計中的本質差異、APIYI 平臺 OSS URL 輸出相比 base64 編碼的優勢，以及如何根據業務場景選擇最優的圖片獲取方案。

Nano Banana Pro API 調用模式核心對比

同步調用的工作原理

同步調用 （Synchronous Call） 採用 請求-等待-響應 模式:

1. 客戶端發起請求: 發送圖像生成請求到服務器
2. 保持 HTTP 連接: 客戶端保持 TCP 連接打開，等待服務器完成推理
3. 阻塞等待: 在 30-170 秒的推理時間內，客戶端無法處理其他操作
4. 接收完整響應: 服務器返回生成的圖像數據 （base64 或 URL）
5. 關閉連接: 完成後關閉 HTTP 連接

關鍵特徵: 同步調用是阻塞式 （Blocking） 的，客戶端必須等待服務器響應後才能繼續執行後續操作。這要求設置足夠長的超時時間 （1K/2K 推薦 300 秒，4K 推薦 600 秒），以避免在推理完成前連接被中斷。

異步調用的工作原理

異步調用 （Asynchronous Call） 採用 請求-接受-通知 模式:

1. 客戶端提交任務: 發送圖像生成請求到服務器
2. 立即返回任務 ID: 服務器接受請求，返回任務 ID （如 task_abc123），立即關閉連接
3. 後臺推理: 服務器在後臺進行圖像生成，客戶端可以處理其他操作
4. 獲取結果: 客戶端通過以下兩種方式之一獲取結果:
   • 輪詢 （Polling）: 定期請求 /tasks/task_abc123/status 查詢任務狀態
   • Webhook 回調: 任務完成後，服務器主動調用客戶端提供的回調 URL
5. 下載圖像: 任務完成後，通過返回的 URL 下載生成的圖像

關鍵特徵: 異步調用是非阻塞式 （Non-blocking） 的，客戶端在提交任務後可以立即處理其他請求，無需長時間保持連接。適合批量處理、後臺任務和對實時性要求不高的場景。

💡 技術建議: APIYI 平臺目前僅支持同步調用模式，但通過優化超時配置和提供 OSS URL 輸出，顯著提升了用戶體驗。對於需要批量生成圖像的場景，建議通過 API易 apiyi.com 平臺調用，該平臺提供穩定的 HTTP 端口接口，默認配置了合理的超時時間，支持高併發同步調用。

核心差異 1: 連接保持時間與超時配置

同步調用的連接保持要求

同步調用要求客戶端在整個圖像生成過程中保持 HTTP 連接打開，這導致以下技術挑戰:

Python 同步調用示例:

import requests
import time

def generate_image_sync（prompt: str， size: str = "4096x4096"） -> dict:
    """
    同步調用 Nano Banana Pro API 生成圖像

    Args:
        prompt: 圖像提示詞
        size: 圖像尺寸

    Returns:
        API 響應結果
    """
    start_time = time.time（）

    # 同步調用:保持連接直到生成完成
    response = requests.post（
        "http://api.apiyi.com:16888/v1/images/generations"，
        json={
            "prompt": prompt，
            "size": size，
            "model": "nano-banana-pro"，
            "n": 1，
            "response_format": "url"  # APIYI 支持 URL 輸出
        }，
        headers={"Authorization": "Bearer YOUR_API_KEY"}，
        timeout=（10， 600）  # 連接超時 10 秒，讀取超時 600 秒
    ）

    elapsed = time.time（） - start_time
    print（f"⏱️ 同步調用耗時: {elapsed:.2f} 秒"）
    print（f"🔗 連接狀態: 保持打開 {elapsed:.2f} 秒"）

    return response.json（）


# 使用示例
result = generate_image_sync（
    prompt="A futuristic cityscape at sunset"，
    size="4096x4096"
）

print（f"✅ 圖像 URL: {result['data'][0]['url']}"）

關鍵觀察:

• 客戶端在 100-170 秒的推理時間內完全阻塞
• HTTP 連接持續打開，消耗系統資源
• 如果超時設置不當 （如 60 秒），會在推理完成前斷開

異步調用的短連接優勢

異步調用僅在提交任務和查詢狀態時建立短連接，大幅降低連接保持時間:

Python 異步調用示例 （模擬未來 APIYI 支持）:

import requests
import time

def generate_image_async（prompt: str， size: str = "4096x4096"） -> str:
    """
    異步調用 Nano Banana Pro API 生成圖像 （未來功能）

    Args:
        prompt: 圖像提示詞
        size: 圖像尺寸

    Returns:
        任務 ID
    """
    # 步驟 1: 提交任務 （短連接）
    response = requests.post（
        "http://api.apiyi.com:16888/v1/images/generations/async"，  # 未來接口
        json={
            "prompt": prompt，
            "size": size，
            "model": "nano-banana-pro"，
            "n": 1，
            "response_format": "url"
        }，
        headers={"Authorization": "Bearer YOUR_API_KEY"}，
        timeout=（10， 30）  # 提交任務僅需 30 秒超時
    ）

    task_data = response.json（）
    task_id = task_data["task_id"]
    print（f"✅ 任務已提交: {task_id}"）
    print（f"🔓 連接已關閉，可以處理其他任務"）

    return task_id


def poll_task_status（task_id: str， max_wait: int = 300） -> dict:
    """
    輪詢任務狀態直到完成

    Args:
        task_id: 任務 ID
        max_wait: 最大等待時間 （秒）

    Returns:
        生成結果
    """
    start_time = time.time（）
    poll_interval = 5  # 每 5 秒輪詢一次

    while time.time（） - start_time < max_wait:
        # 查詢任務狀態 （短連接）
        response = requests.get（
            f"http://api.apiyi.com:16888/v1/tasks/{task_id}"，  # 未來接口
            headers={"Authorization": "Bearer YOUR_API_KEY"}，
            timeout=（10， 10）  # 查詢狀態僅需 10 秒超時
        ）

        status_data = response.json（）
        status = status_data["status"]

        if status == "completed":
            elapsed = time.time（） - start_time
            print（f"✅ 任務完成！ 總耗時: {elapsed:.2f} 秒"）
            return status_data["result"]

        elif status == "failed":
            raise Exception（f"任務失敗: {status_data.get（'error'）}"）

        else:
            print（f"⏳ 任務狀態: {status}， 等待 {poll_interval} 秒後重試..."）
            time.sleep（poll_interval）

    raise TimeoutError（f"任務超時: {task_id}"）


# 使用示例
task_id = generate_image_async（
    prompt="A serene mountain landscape"，
    size="4096x4096"
）

# 在輪詢期間，可以處理其他任務
print（"🚀 可以併發處理其他請求..."）

# 輪詢任務狀態
result = poll_task_status（task_id， max_wait=600）
print（f"✅ 圖像 URL: {result['data'][0]['url']}"）

from flask import Flask， request， jsonify
import requests

app = Flask（__name__）

# 全局字典存儲任務結果
task_results = {}


@app.route（'/webhook/image_completed'， methods=['POST']）
def handle_webhook（）:
    """接收 APIYI 異步任務完成的 Webhook 回調"""
    data = request.json

    task_id = data['task_id']
    status = data['status']
    result = data.get（'result'）

    if status == 'completed':
        task_results[task_id] = result
        print（f"✅ 任務 {task_id} 完成: {result['data'][0]['url']}"）
    else:
        print（f"❌ 任務 {task_id} 失敗: {data.get（'error'）}"）

    return jsonify（{"received": True}）， 200


def generate_image_with_webhook（prompt: str， size: str = "4096x4096"） -> str:
    """
    使用 Webhook 模式異步生成圖像

    Args:
        prompt: 圖像提示詞
        size: 圖像尺寸

    Returns:
        任務 ID
    """
    response = requests.post（
        "http://api.apiyi.com:16888/v1/images/generations/async"，
        json={
            "prompt": prompt，
            "size": size，
            "model": "nano-banana-pro"，
            "n": 1，
            "response_format": "url"，
            "webhook_url": "https://your-domain.com/webhook/image_completed"  # 回調 URL
        }，
        headers={"Authorization": "Bearer YOUR_API_KEY"}，
        timeout=（10， 30）
    ）

    task_id = response.json（）["task_id"]
    print（f"✅ 任務已提交: {task_id}"）
    print（f"📞 Webhook 將回調: https://your-domain.com/webhook/image_completed"）

    return task_id


# 啓動 Flask 服務器監聽 Webhook
if __name__ == '__main__':
    app.run（host='0.0.0.0'， port=5000）

🎯 當前限制: APIYI 和 Gemini 官方目前均僅支持同步調用模式，異步調用功能計劃在未來版本推出。對於需要高併發圖像生成的場景，建議通過 API易 apiyi.com 平臺使用多線程或多進程併發調用同步接口，並配置合理的超時時間。

核心差異 2: 併發處理能力與資源佔用

同步調用的併發限制

同步調用在高併發場景下面臨顯著的資源佔用問題:

單線程阻塞問題:

import time

# ❌ 錯誤: 單線程順序調用，總耗時 = 單次耗時 × 任務數
def generate_multiple_images_sequential（prompts: list） -> list:
    results = []
    start_time = time.time（）

    for prompt in prompts:
        result = generate_image_sync（prompt， size="4096x4096"）
        results.append（result）

    elapsed = time.time（） - start_time
    print（f"❌ 順序調用 {len（prompts）} 張圖像耗時: {elapsed:.2f} 秒"）
    # 假設每張圖 120 秒，10 張圖 = 1200 秒 （20 分鐘！）

    return results

多線程併發優化:

from concurrent.futures import ThreadPoolExecutor， as_completed
import time

# ✅ 正確: 多線程併發調用，充分利用 I/O 等待時間
def generate_multiple_images_concurrent（prompts: list， max_workers: int = 5） -> list:
    """
    多線程併發生成多張圖像

    Args:
        prompts: 提示詞列表
        max_workers: 最大併發線程數

    Returns:
        生成結果列表
    """
    results = []
    start_time = time.time（）

    with ThreadPoolExecutor（max_workers=max_workers） as executor:
        # 提交所有任務
        future_to_prompt = {
            executor.submit（generate_image_sync， prompt， "4096x4096"）: prompt
            for prompt in prompts
        }

        # 等待所有任務完成
        for future in as_completed（future_to_prompt）:
            prompt = future_to_prompt[future]
            try:
                result = future.result（）
                results.append（result）
                print（f"✅ 完成: {prompt[:30]}..."）
            except Exception as e:
                print（f"❌ 失敗: {prompt[:30]}... - {e}"）

    elapsed = time.time（） - start_time
    print（f"✅ 併發調用 {len（prompts）} 張圖像耗時: {elapsed:.2f} 秒"）
    # 假設每張圖 120 秒，10 張圖 ≈ 120-150 秒 （2-2.5 分鐘）

    return results


# 使用示例
prompts = [
    "A cyberpunk city at night"，
    "A serene forest landscape"，
    "An abstract geometric pattern"，
    "A futuristic space station"，
    "A vintage car in the desert"，
    # ...更多提示詞
]

results = generate_multiple_images_concurrent（prompts， max_workers=5）
print（f"🎉 生成了 {len（results）} 張圖像"）

異步調用的併發優勢

異步調用在批量處理場景下具有顯著優勢:

批量提交 + 批量輪詢:

def generate_batch_async（prompts: list） -> list:
    """
    批量異步生成圖像 （未來功能）

    Args:
        prompts: 提示詞列表

    Returns:
        任務 ID 列表
    """
    task_ids = []

    # 步驟 1: 快速批量提交所有任務 （每個 1-3 秒）
    for prompt in prompts:
        task_id = generate_image_async（prompt， size="4096x4096"）
        task_ids.append（task_id）

    print（f"✅ 批量提交 {len（task_ids）} 個任務，耗時約 {len（prompts） * 2} 秒"）

    # 步驟 2: 批量輪詢任務狀態
    results = []
    for task_id in task_ids:
        result = poll_task_status（task_id， max_wait=600）
        results.append（result）

    return results

💰 成本優化: Google Gemini API 提供 Batch API 模式，支持異步處理並提供 50% 的價格折扣 （標準價格 $0.133-$0.24/張，Batch API $0.067-$0.12/張），但需容忍最長 24 小時的交付時間。對於不需要實時生成的場景，可考慮使用 Batch API 降低成本。

核心差異 3: APIYI 平臺的 OSS URL 輸出優勢

base64 編碼 vs URL 輸出對比

Nano Banana Pro API 支持兩種圖片輸出格式:

base64 編碼的性能問題:

1. 響應體膨脹 33%: base64 編碼會增加約 33% 的數據量

   • 原始 4K 圖像: 約 6 MB
   • base64 編碼後: 約 8 MB

2. 無法利用 CDN: base64 字符串嵌入在 JSON 響應中，無法通過 CDN 緩存

3. 移動端內存壓力: 解碼 base64 字符串需要額外的內存和 CPU 資源

APIYI OSS URL 輸出的優勢:

import requests

# ✅ 推薦: 使用 APIYI OSS URL 輸出
response = requests.post（
    "http://api.apiyi.com:16888/v1/images/generations"，
    json={
        "prompt": "A beautiful sunset over mountains"，
        "size": "4096x4096"，
        "model": "nano-banana-pro"，
        "n": 1，
        "response_format": "url"  # 指定 URL 輸出
    }，
    headers={"Authorization": "Bearer YOUR_API_KEY"}，
    timeout=（10， 600）
）

result = response.json（）

# 響應體僅包含 URL，大小約 200 字節
print（f"響應體大小: {len（response.content）} 字節"）
# 輸出: 響應體大小: 234 字節

# OSS URL 示例
image_url = result['data'][0]['url']
print（f"圖像 URL: {image_url}"）
# 輸出: https://apiyi-oss.oss-cn-beijing.aliyuncs.com/nano-banana/abc123.png

# 後續通過標準 HTTP 下載圖像，享受 CDN 加速
image_response = requests.get（image_url）
with open（"output.png"， "wb"） as f:
    f.write（image_response.content）

對比: base64 輸出的性能問題:

# ❌ 不推薦: base64 編碼輸出
response = requests.post（
    "https://api.example.com/v1/images/generations"，
    json={
        "prompt": "A beautiful sunset over mountains"，
        "size": "4096x4096"，
        "model": "nano-banana-pro"，
        "n": 1，
        "response_format": "b64_json"  # base64 編碼
    }，
    headers={"Authorization": "Bearer YOUR_API_KEY"}，
    timeout=（10， 600）
）

result = response.json（）

# 響應體包含完整 base64 字符串，大小約 8 MB
print（f"響應體大小: {len（response.content）} 字節"）
# 輸出: 響應體大小: 8388608 字節 （8 MB！）

# 需要解碼 base64 字符串
import base64
image_b64 = result['data'][0]['b64_json']
image_bytes = base64.b64decode（image_b64）

with open（"output.png"， "wb"） as f:
    f.write（image_bytes）

🚀 推薦配置: 在調用 APIYI 平臺的 Nano Banana Pro API 時，始終使用 response_format: "url" 獲取 OSS URL 輸出，而非 base64 編碼。這不僅顯著減少 API 響應大小和傳輸時間，還能充分利用 CDN 加速和瀏覽器緩存，提升用戶體驗。

核心差異 4: 適用場景與未來規劃

同步調用的最佳適用場景

推薦場景:

1. 實時圖像生成: 用戶提交提示詞後立即展示生成的圖像
2. 小批量處理: 生成 1-10 張圖像，併發調用即可滿足性能要求
3. 簡單集成: 無需實現輪詢或 Webhook，降低開發複雜度
4. 交互式應用: AI 繪畫工具、圖像編輯器等需要即時反饋的場景

典型代碼模式:

from flask import Flask， request， jsonify
import requests

app = Flask（__name__）

@app.route（'/generate'， methods=['POST']）
def generate_image（）:
    """實時圖像生成接口"""
    data = request.json
    prompt = data['prompt']
    size = data.get（'size'， '1024x1024'）

    # 同步調用，用戶等待生成完成
    response = requests.post（
        "http://api.apiyi.com:16888/v1/images/generations"，
        json={
            "prompt": prompt，
            "size": size，
            "model": "nano-banana-pro"，
            "n": 1，
            "response_format": "url"
        }，
        headers={"Authorization": "Bearer YOUR_API_KEY"}，
        timeout=（10， 300 if size ！= '4096x4096' else 600）
    ）

    result = response.json（）
    return jsonify（{
        "success": True，
        "image_url": result['data'][0]['url']
    }）

if __name__ == '__main__':
    app.run（host='0.0.0.0'， port=8000）

異步調用的未來應用場景

適用場景 （未來支持）:

1. 批量圖像生成: 生成 100+ 張圖像，如電商批量商品圖、設計素材庫
2. 後臺定時任務: 每日自動生成特定類型的圖像，無需實時響應
3. 低成本處理: 使用 Google Batch API 獲取 50% 價格折扣，容忍 24 小時交付時間
4. 高併發場景: 數百個用戶同時提交生成請求，避免連接池耗盡

典型代碼模式 （未來）:

from flask import Flask， request， jsonify
from celery import Celery
import requests

app = Flask（__name__）
celery = Celery（'tasks'， broker='redis://localhost:6379/0'）

@celery.task
def generate_image_task（prompt: str， size: str， user_id: str）:
    """Celery 異步任務:生成圖像"""
    # 提交異步任務到 APIYI
    response = requests.post（
        "http://api.apiyi.com:16888/v1/images/generations/async"，  # 未來接口
        json={
            "prompt": prompt，
            "size": size，
            "model": "nano-banana-pro"，
            "n": 1，
            "response_format": "url"，
            "webhook_url": f"https://your-domain.com/webhook/{user_id}"
        }，
        headers={"Authorization": "Bearer YOUR_API_KEY"}，
        timeout=（10， 30）
    ）

    task_id = response.json（）["task_id"]
    return task_id


@app.route（'/generate_async'， methods=['POST']）
def generate_image_async（）:
    """異步圖像生成接口"""
    data = request.json
    prompt = data['prompt']
    size = data.get（'size'， '1024x1024'）
    user_id = data['user_id']

    # 提交 Celery 任務，立即返回
    task = generate_image_task.delay（prompt， size， user_id）

    return jsonify（{
        "success": True，
        "message": "任務已提交，完成後將通過 Webhook 通知"，
        "task_id": task.id
    }）


@app.route（'/webhook/<user_id>'， methods=['POST']）
def handle_webhook（user_id: str）:
    """接收 APIYI 異步任務完成的 Webhook 回調"""
    data = request.json
    task_id = data['task_id']
    result = data['result']

    # 通知用戶圖像生成完成 （如發送郵件、推送通知等）
    notify_user（user_id， result['data'][0]['url']）

    return jsonify（{"received": True}）， 200

APIYI 平臺的未來規劃

💡 開發建議: APIYI 計劃在 2026 年第三季度推出異步調用功能，支持任務提交、狀態查詢和 Webhook 回調。對於當前有批量處理需求的開發者，建議使用多線程併發調用同步接口，並通過 API易 apiyi.com 平臺獲取穩定的 HTTP 端口接口和優化的超時配置。

常見問題

import requests

# 生成圖像並獲取 URL
result = generate_image_sync（prompt="A beautiful landscape"， size="4096x4096"）
temp_url = result['data'][0]['url']
print（f"臨時 URL: {temp_url}"）

# 下載圖像到本地或自己的 OSS
image_response = requests.get（temp_url）
with open（"permanent_image.png"， "wb"） as f:
    f.write（image_response.content）

# 或上傳到自己的 OSS （以阿里雲 OSS 爲例）
import oss2
auth = oss2.Auth（'YOUR_ACCESS_KEY'， 'YOUR_SECRET_KEY'）
bucket = oss2.Bucket（auth， 'oss-cn-beijing.aliyuncs.com'， 'your-bucket'）
bucket.put_object（'images/permanent_image.png'， image_response.content）

// 前端代碼 （React 示例）
async function generateImage（prompt， size） {
  // 調用自己的後端接口
  const response = await fetch（'https://your-backend.com/api/generate'， {
    method: 'POST'，
    headers: {
      'Content-Type': 'application/json'，
      'Authorization': 'Bearer YOUR_USER_TOKEN'  // 用戶認證 token
    }，
    body: JSON.stringify（{ prompt， size }）
  }）；

  const result = await response.json（）；
  return result.image_url；  // 返回 APIYI OSS URL
}

// 使用
const imageUrl = await generateImage（"A futuristic city"， "4096x4096"）；
document.getElementById（'result-image'）.src = imageUrl；

# 後端代碼 （Flask 示例）
from flask import Flask， request， jsonify
import requests

app = Flask（__name__）

@app.route（'/api/generate'， methods=['POST']）
def generate（）:
    # 驗證用戶 token
    user_token = request.headers.get（'Authorization'）
    if not verify_user_token（user_token）:
        return jsonify（{"error": "Unauthorized"}）， 401

    data = request.json

    # 後端調用 APIYI API （API Key 不會暴露給前端）
    response = requests.post（
        "http://api.apiyi.com:16888/v1/images/generations"，
        json={
            "prompt": data['prompt']，
            "size": data['size']，
            "model": "nano-banana-pro"，
            "n": 1，
            "response_format": "url"
        }，
        headers={"Authorization": "Bearer YOUR_APIYI_API_KEY"}，  # 安全存儲在後端
        timeout=（10， 600）
    ）

    result = response.json（）
    return jsonify（{"image_url": result['data'][0]['url']}）

總結

Nano Banana Pro API 同步與異步調用的核心要點:

1. 同步調用特徵: 保持 HTTP 連接直到生成完成，阻塞等待 30-170 秒，需配置長超時 （300-600 秒）
2. 異步調用優勢: 立即返回任務 ID，非阻塞，適合批量處理和後臺任務，但目前 APIYI 和 Gemini 官方均未支持
3. APIYI OSS URL 輸出: 相比 base64 編碼，響應體減少 99.998%，支持 CDN 加速和瀏覽器緩存，顯著提升性能
4. 當前最佳實踐: 使用同步調用 + 多線程併發 + OSS URL 輸出，通過 APIYI HTTP 端口接口獲取優化的超時配置
5. 未來規劃: APIYI 計劃在 2026 Q2 推出異步調用功能，支持任務提交、狀態查詢和 Webhook 回調

推薦通過 API易 apiyi.com 快速集成 Nano Banana Pro API。該平臺提供優化的 HTTP 端口接口 （http://api.apiyi.com:16888/v1）、獨家的 OSS URL 圖片輸出，以及合理的超時配置，適合實時圖像生成和批量處理場景。

作者: APIYI 技術團隊 | 如有技術問題，歡迎訪問 API易 apiyi.com 獲取更多 AI 模型接入方案。