Gemini Images API#

UniGateway 提供 Gemini generateContent 风格的图像接口，用于文生图、图生图和多参考图生成。本文覆盖 Nano Banana 系列图像模型的调用方式、图像输入、画幅和尺寸控制，以及结果解析。本文不涵盖语音或视频生成。

import requests
key = "<YOUR_UNIGATEWAY_API_KEY>"
resp = requests.post("https://api.unigateway.ai/v1beta/models/gemini-3-pro-image-preview:generateContent", headers={"Authorization":f"Bearer {key}","Content-Type":"application/json"}, json={"contents":[{"parts":[{"text":"Your prompt."}]}],"generationConfig":{"responseModalities":["TEXT","IMAGE"],"imageConfig":{"aspectRatio":"16:9","imageSize":"4K"}}})
print(resp.json())

概览#

支持的模型：

请前往 UniGateway API Keys 创建或获取 API Key。有关 API Key 的创建、访问控制、轮换和安全管理，请参阅 账户与 API Key。模型可用性以 UniGateway 模型库 为准。

export GEMINI_BASE_URL="https://api.unigateway.ai"
export UNIGATEWAY_API_KEY="<YOUR_API_KEY>"

鉴权#

每个请求均应携带 UniGateway API Key：

Authorization: Bearer $UNIGATEWAY_API_KEY

渠道亲和性#

需要将同一图像生成业务会话的 Gemini 请求路由到同一渠道时，在每个相关请求中携带以下请求头：

x-gemini-session-id: <session-id>

将 <session-id> 替换为应用生成的稳定会话标识。对同一会话的文生图、图生图和后续重试请求使用相同的值；不同的独立会话使用不同的值。未携带该请求头时，请求不会使用渠道亲和性。

该请求头仅用于渠道路由，不保存图像生成上下文或 Gemini 对话历史。每次调用仍需在请求体中传入所需的文本和图像内容。不要在 session ID 中写入 API Key、用户个人信息或其他敏感数据。

适用场景#

Gemini Images API 适合以下图像工作流：

• 通过文本提示词生成图像。
• 向输入中加入一张图像，按文本指令完成图生图。
• 向同一个请求加入多张参考图，使它们共同参与生成。
• 使用明确的画幅比例和 1K、2K、4K 输出尺寸档位。
• 处理偏高质量的复杂指令与文字渲染需求。

请求结构#

接口：POST https://api.unigateway.ai/v1beta/models/{model}:generateContent

将 {model} 替换为已支持的模型 ID，例如：

/v1beta/models/gemini-3-pro-image-preview:generateContent
/v1beta/models/gemini-3.1-flash-image-preview:generateContent

请求体以 contents 为核心，并可包含 systemInstruction、safetySettings 和 generationConfig：

{
  "contents": [
    {
      "parts": [
        { "text": "你的提示词。" }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    }
  }
}

参数说明#

temperature、topP、topK、maxOutputTokens、stopSequences、tools、toolConfig 和 cachedContent 属于 Gemini 原生请求结构，但并非图像生成的通用配置。图像生成工作流通常只使用本节列出的字段；增加其他字段后如接口返回参数错误，应根据当前响应移除或调整。responseModalities 仅使用 TEXT 和 IMAGE，不要传入语音或视频模态。有关文本生成、工具调用和其他文本 generationConfig 字段，请参阅 Gemini API。

图像输入规则#

图像输入通过 parts[].inline_data 传递，不使用视频或音频字段。

{
  "inline_data": {
    "mime_type": "image/png",
    "data": "<BASE64_IMAGE>"
  }
}

可在同一个 parts[] 中继续添加多个 inline_data 块，以传入多张参考图。

当前未单独声明 inline_data 图像的固定最大文件大小或像素上限。generationConfig.imageConfig.imageSize 只控制生成结果的尺寸，不代表上传图像的大小限制。客户端上传前建议校验：

• 文件扩展名与实际 MIME 类型一致。
• Base64 内容能够正常解码为图像。
• 仅将图像数据传入 inline_data，不要传入视频或音频数据。
• 上传文件大小以 UniGateway 服务端实际限制为准。

示例：将图像编码为 Base64#

B64=$(base64 -i input.png 2>/dev/null || base64 -w0 input.png)

后续示例中的 <BASE64_IMAGE> 应替换为该图像的 Base64 内容。

文生图#

cURL 请求示例#

以下示例使用 gemini-3-pro-image-preview 生成 16:9、4K 图像：

curl -sS -X POST "$GEMINI_BASE_URL/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-gemini-session-id: <session-id>" \
  -d '{
    "contents": [{
      "parts": [
        { "text": "A clean product hero image for an AI gateway dashboard." }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "4K"
      }
    }
  }' > result.json

Python 请求示例#

安装依赖：

pip install google-genai pillow

Google Gen AI SDK 的 base_url 使用 UniGateway 根地址，并通过 api_version 指定 v1beta。图像生成时应在 response_modalities 中包含 IMAGE：

需要渠道亲和性时，在 SDK 的 HttpOptions.headers 中设置 x-gemini-session-id，并在同一业务会话的全部调用中保持该值一致：

headers={"x-gemini-session-id": "<session-id>"}

import os

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["UNIGATEWAY_API_KEY"],
    http_options=types.HttpOptions(
        base_url="https://api.unigateway.ai",
        api_version="v1beta",
        headers={"x-gemini-session-id": "<session-id>"},
    ),
)

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="A clean product hero image for an AI gateway dashboard.",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="4K",
        ),
    ),
)

for part in response.candidates[0].content.parts:
    if part.inline_data:
        part.as_image().save("dashboard.png")
        break

JavaScript 请求示例#

安装依赖：

npm install @google/genai

以下示例使用 Google Gen AI JavaScript SDK，通过 UniGateway 的根地址和 v1beta API 版本发起请求：

import { writeFile } from "node:fs/promises";

import { GoogleGenAI, Modality } from "@google/genai";

async function main() {
  const client = new GoogleGenAI({
    apiKey: process.env.UNIGATEWAY_API_KEY,
    httpOptions: {
      baseUrl: "https://api.unigateway.ai",
      apiVersion: "v1beta",
      headers: { "x-gemini-session-id": "<session-id>" },
    },
  });

  const response = await client.models.generateContent({
    model: "gemini-3-pro-image-preview",
    contents: "A clean product hero image for an AI gateway dashboard.",
    config: {
      responseModalities: [Modality.TEXT, Modality.IMAGE],
      imageConfig: {
        aspectRatio: "16:9",
        imageSize: "4K",
      },
    },
  });

  for (const part of response.candidates?.[0]?.content?.parts ?? []) {
    if (part.inlineData?.data) {
      await writeFile("dashboard.png", Buffer.from(part.inlineData.data, "base64"));
      return;
    }
  }

  throw new Error("The response did not include an image result.");
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

响应说明#

响应示例#

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is the generated image."
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE>"
            }
          }
        ]
      }
    }
  ]
}

详细的响应解析与保存方式请参阅响应格式和保存返回图像。

示例：Gemini 3.1 Flash Image Preview (Nano Banana 2)，方形通用图像#

curl -sS -X POST "$GEMINI_BASE_URL/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-gemini-session-id: <session-id>" \
  -d '{
    "contents": [{
      "parts": [
        { "text": "A clean square icon set for chat, image, video, and search." }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }' > icons.json

图生图#

将文本指令和图像块放入同一个 parts[]。以下示例将输入图像作为参考，生成符合编辑指令的新图像。

cURL 请求示例#

B64=$(base64 -i input.png 2>/dev/null || base64 -w0 input.png)

curl -sS -X POST "$GEMINI_BASE_URL/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-gemini-session-id: <session-id>" \
  -d "{
    \"contents\": [{
      \"parts\": [
        { \"text\": \"将背景替换为纯白色。\" },
        { \"inline_data\": { \"mime_type\": \"image/png\", \"data\": \"${B64}\" } }
      ]
    }],
    \"generationConfig\": {
      \"responseModalities\": [\"TEXT\", \"IMAGE\"],
      \"imageConfig\": { \"aspectRatio\": \"16:9\", \"imageSize\": \"4K\" }
    }
  }" > edit-result.json

Python 请求示例#

使用 types.Part.from_bytes 将本地图像作为内容块传入。图像的 MIME 类型应与文件实际类型一致：

import os
from pathlib import Path

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["UNIGATEWAY_API_KEY"],
    http_options=types.HttpOptions(
        base_url="https://api.unigateway.ai",
        api_version="v1beta",
        headers={"x-gemini-session-id": "<session-id>"},
    ),
)

source_image = types.Part.from_bytes(
    data=Path("input.png").read_bytes(),
    mime_type="image/png",
)

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=["将背景替换为纯白色。", source_image],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="4K",
        ),
    ),
)

for part in response.candidates[0].content.parts:
    if part.inline_data:
        part.as_image().save("edited.png")
        break

JavaScript 请求示例#

import { readFile, writeFile } from "node:fs/promises";

import { GoogleGenAI, Modality } from "@google/genai";

async function main() {
  const client = new GoogleGenAI({
    apiKey: process.env.UNIGATEWAY_API_KEY,
    httpOptions: {
      baseUrl: "https://api.unigateway.ai",
      apiVersion: "v1beta",
      headers: { "x-gemini-session-id": "<session-id>" },
    },
  });
  const sourceImage = await readFile("input.png");
  const response = await client.models.generateContent({
    model: "gemini-3-pro-image-preview",
    contents: [
      {
        parts: [
          { text: "将背景替换为纯白色。" },
          {
            inlineData: {
              mimeType: "image/png",
              data: sourceImage.toString("base64"),
            },
          },
        ],
      },
    ],
    config: {
      responseModalities: [Modality.TEXT, Modality.IMAGE],
      imageConfig: {
        aspectRatio: "16:9",
        imageSize: "4K",
      },
    },
  });

  for (const part of response.candidates?.[0]?.content?.parts ?? []) {
    if (part.inlineData?.data) {
      await writeFile("edited.png", Buffer.from(part.inlineData.data, "base64"));
      return;
    }
  }

  throw new Error("The response did not include an image result.");
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

图生图的响应字段与文生图响应说明相同。使用前应遍历 candidates[].content.parts[]，确认取得 inlineData.data 后再保存图像。

多参考图生成#

在 parts[] 中追加多个图像块即可。下面的结构可用于让多张参考图共同参与生成：

{
  "contents": [{
    "parts": [
      { "text": "将全部物品合成一张白底产品照。" },
      {
        "inline_data": {
          "mime_type": "image/png",
          "data": "<BASE64_IMAGE_1>"
        }
      },
      {
        "inline_data": {
          "mime_type": "image/png",
          "data": "<BASE64_IMAGE_2>"
        }
      },
      {
        "inline_data": {
          "mime_type": "image/png",
          "data": "<BASE64_IMAGE_3>"
        }
      }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "4:3",
      "imageSize": "2K"
    }
  }
}

图像尺寸控制#

使用 generationConfig.imageConfig 控制生成结果的画幅和尺寸。

示例：生成适合竖版展示的图像。

{
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "9:16",
      "imageSize": "2K"
    }
  }
}

响应格式#

图像数据位于候选结果内容块的 inlineData.data 中：

响应示例#

{
  "candidates": [
    {
      "content": {
        "parts": [
          { "text": "Here is the generated image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "..."
            }
          }
        ]
      }
    }
  ]
}

字段说明#

请注意请求中的图像字段使用 inline_data、mime_type，而响应中的图像字段使用 inlineData、mimeType。

保存返回图像#

Bash#

# macOS
jq -r 'first(..|objects|select(.inlineData?.data)|.inlineData.data)' result.json | base64 -D > output.png

# Linux
jq -r 'first(..|objects|select(.inlineData?.data)|.inlineData.data)' result.json | base64 --decode > output.png

Python#

import base64
import json
from pathlib import Path

response = json.loads(Path("result.json").read_text(encoding="utf-8"))
for candidate in response.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        inline_data = part.get("inlineData")
        if inline_data and inline_data.get("data"):
            Path("output.png").write_bytes(base64.b64decode(inline_data["data"]))
            raise SystemExit(0)

raise RuntimeError("The response did not include an image result.")

JavaScript#

import { readFile, writeFile } from "node:fs/promises";

const response = JSON.parse(await readFile("result.json", "utf8"));
for (const candidate of response.candidates ?? []) {
  for (const part of candidate.content?.parts ?? []) {
    if (part.inlineData?.data) {
      await writeFile("output.png", Buffer.from(part.inlineData.data, "base64"));
      process.exit(0);
    }
  }
}

throw new Error("The response did not include an image result.");

常见错误与处理#