Gemini 图像

Google 图像模型有两类,调用方式不同:

模型类型 可用接口
Gemini 原生图像输出(含 Nano Banana 系列) ① POST /v1/images/generations、POST /v1/images/edits(OpenAI 兼容)
② POST /v1beta/models/{model}:generateContent(Gemini 原生)
Imagen 仅 POST /v1/images/generations(不支持编辑)

可用模型以 模型列表 返回为准(或控制台模型价格页)。

Imagen 原生的 :predict 接口未开放,请使用 OpenAI 兼容的图片生成接口。

最短路径:只要拿到图片,用 OpenAI 兼容接口 + b64_json;需要图文混合输出或多轮对话改图,用 Gemini 原生 generateContent。

方式一:OpenAI 兼容图片接口

项 值
方法与路径 POST /v1/images/generations(文生图)、POST /v1/images/edits(改图,仅 Gemini 图像模型)
鉴权 Authorization: Bearer YOUR_API_KEY
Content-Type application/json;改图也可用 multipart/form-data

快速示例

BASH
curl https://www.nextai-code.com/v1/images/generations \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "雨后的江南小巷,青石板反光,电影感摄影",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'
PYTHON
import base64, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["NEXTAI_API_KEY"], base_url="https://www.nextai-code.com/v1")

resp = client.images.generate(
    model="gemini-3.1-flash-image",
    prompt="雨后的江南小巷,青石板反光,电影感摄影",
    size="16:9",
    quality="2k",
)
for i, item in enumerate(resp.data):
    with open(f"out_{i}.png", "wb") as f:
        f.write(base64.b64decode(item.b64_json))

改图(JSON,参考图用 data URL 或 http(s) 链接):

BASH
curl https://www.nextai-code.com/v1/images/edits \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "把背景换成金色逆光的摄影棚",
    "image": ["data:image/png;base64,iVBORw0KGgo..."]
  }'

改图(multipart):

BASH
curl https://www.nextai-code.com/v1/images/edits \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -F "model=gemini-3.1-flash-image" \
  -F "prompt=把背景换成金色逆光的摄影棚" \
  -F "image[][email protected]" \
  -F "image[][email protected]"

请求参数

参数 类型 必填 说明
model string 是 模型 ID
prompt string 是 提示词
n integer 否 生成张数,默认 1,平台允许最大 10;模型自身上限往往更低(Imagen 一般不超过 4),超出时可能报错或返回较少张数
size string 否 决定宽高比。可直接写比例(如 1:1、16:9、9:16、3:2、2:3),或写像素尺寸,平台按下列规则换算为比例:256x256 / 512x512 / 1024x1024 → 1:1,1792x1024 → 16:9,1024x1792 → 9:16,1536x1024 → 3:2,1024x1536 → 2:3。也可写 1k / 2k / 4k 表示分辨率档位
quality string 否 决定分辨率档位:standard / low / medium / auto / 1k → 1K;hd / high / 2k → 2K;ultra / 4k → 4K。Gemini 图像模型传其他值会报错
response_format string 否 只支持 b64_json(默认)。传 url 会报错
image / images string / array 改图必填 仅 /v1/images/edits。JSON 中 image 可为字符串或字符串数组(data URL、公网可访问的 http(s) 链接或纯 base64;纯 base64 按 JPEG 处理,建议用 data URL 标明格式);images 也接受 [{"image_url":{"url":"..."}}],不支持 file_id。multipart 用 image / image[] 文件字段

分辨率说明

  • Gemini 2 系列图像模型和初代 Nano Banana 不支持分辨率档位,quality 不改变输出尺寸;其他 Gemini 图像模型支持 1K / 2K / 4K(具体档位取决于模型)。
  • size 写 1k / 2k / 4k 且与 quality 指定的档位不一致时报错。
  • Imagen:size 未传时宽高比默认 1:1。quality 只识别 standard / low / medium / auto / hd / high / 4k / ultra 及大写 1K / 2K,小写 2k 会按 1K 处理,建议用 hd 指定 2K。
  • 档位不承诺精确宽高,实际尺寸以生成文件为准。

Gemini 图像模型不支持的 OpenAI 参数(传了会报错):stream: true、partial_images、response_format: url、style、input_fidelity、mask、background(auto / opaque 以外的值)、moderation(auto 以外的值)、output_format(png 以外的值)、output_compression、watermark: false,以及其他未知字段。风格要求请写进 prompt。

响应

JSON
{
  "created": 1734567890,
  "data": [
    {"b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "url": "", "revised_prompt": ""}
  ]
}
字段 类型 说明
created integer Unix 时间戳(秒)
data[].b64_json string 图片的 base64 数据
  • 多张结果都在 data[] 中,请遍历读取,不要只取 data[0]。
  • Imagen 中被安全策略过滤的图片会被跳过,返回张数可能少于 n;全部被过滤时报错。
  • Gemini 图像模型只返回图片,不返回模型附带的文字说明;需要文字请用方式二。

方式二:Gemini 原生 generateContent

仅适用于 Gemini 图像模型。接口、鉴权、请求与响应格式与 Gemini 原生 完全一致,区别只在 generationConfig 中声明图片输出。

项 值
方法与路径 POST /v1beta/models/{model}:generateContent
鉴权 x-goog-api-key: YOUR_API_KEY、?key=YOUR_API_KEY 或 Authorization: Bearer YOUR_API_KEY

快速示例

BASH
curl "https://www.nextai-code.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "一只戴宇航头盔的橘猫,水彩风格"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
    }
  }'
PYTHON
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NEXTAI_API_KEY"],
    http_options=types.HttpOptions(base_url="https://www.nextai-code.com"),
)

resp = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents="一只戴宇航头盔的橘猫,水彩风格",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="1:1", image_size="2K"),
    ),
)
for i, part in enumerate(resp.candidates[0].content.parts):
    if part.inline_data:
        with open(f"out_{i}.png", "wb") as f:
            f.write(part.inline_data.data)
    elif part.text:
        print(part.text)

改图:把参考图作为 inlineData part 放在文本前面:

JSON
{
  "contents": [{
    "role": "user",
    "parts": [
      {"inlineData": {"mimeType": "image/png", "data": "<base64>"}},
      {"text": "把背景换成金色逆光的摄影棚"}
    ]
  }],
  "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}

关键参数

参数 说明
generationConfig.responseModalities 需要图片输出时必须显式设为 ["TEXT","IMAGE"],原生接口不会自动补
generationConfig.imageConfig 常用 aspectRatio、imageSize;可选值取决于模型
generationConfig.candidateCount 候选数量,上限取决于模型

响应

图片在 candidates[].content.parts[] 中以 inlineData 返回,data 为 base64:

JSON
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        {"text": "这是你要的橘猫插画。"},
        {"inlineData": {"mimeType": "image/png", "data": "iVBORw0KGgo..."}}
      ]
    },
    "finishReason": "STOP"
  }],
  "usageMetadata": {"promptTokenCount": 12, "candidatesTokenCount": 1300, "totalTokenCount": 1312}
}

遍历所有 parts,取带 inlineData 的部分解码即可。finishReason 为 SAFETY 等或存在 promptFeedback.blockReason 时表示被安全策略拦截。

错误

错误体为 OpenAI 格式 {"error": {"message": "...", "type": "...", "code": "..."}},两种方式相同。

HTTP 场景 处理
400 prompt_blocked 提示词或结果被安全策略拦截,或没有返回任何候选 修改提示词后重试
400 n 大于 10 降低 n
400 或 422 传入了上文列出的 Gemini 不支持参数、quality 取值无法识别、size 与 quality 指定了不同分辨率、对 Imagen 调用 /v1/images/edits 按上文修正参数,或换用 Gemini 图像模型改图。错误信息为统一提示,不会指出具体字段
5xx 模型未产出图片(如提示词不适合生成图片、Imagen 结果全部被过滤) 调整提示词后重试;先记录响应头 X-Oneapi-Request-Id

方式二(原生接口)被安全策略拦截时不一定返回错误:HTTP 200 但 finishReason 为 SAFETY 等、或带 promptFeedback.blockReason,见上文响应说明。

通用错误见 错误码。

相关文档