Gemini 图像生成（原生格式）

使用 Gemini 原生的 generateContent 接口进行图像生成与图像编辑。通过在 generationConfig.responseModalities 中声明 IMAGE 模态，模型会在返回中携带图片内容。

代表模型：

• gemini-2.5-flash-image-preview（Nano Banana）
• gemini-3-pro-image-preview

TIP

推荐使用本接口进行图像生成。Gemini 原生格式对图像生成、图生图、分辨率与宽高比等参数支持更完整。若需通过 OpenAI 兼容接口调用，请参考 OpenAI 兼容格式图像生成。

WARNING

建议使用官方原生接口。跨格式调用（如通过 OpenAI /v1/images/generations 调用 Gemini 图像模型）由代理侧进行格式转换，可能存在参数缺失或行为差异等问题。具体支持范围请咨询 FreeAPI。

请求

Endpoint

POST https://www.free-api.ai/api/v1beta/models/{model}:generateContent

路径参数

名称	必填	说明
model	是	图像模型名称，例如 gemini-2.5-flash-image-preview、gemini-3-pro-image-preview

请求头

名称	必填	说明
Authorization	是	Bearer your-api-key
Content-Type	是	application/json

请求参数

字段	类型	必填	说明
contents	array	是	提示词与参考图的内容数组
generationConfig	object	是	生成配置，必须包含 responseModalities
generationConfig.responseModalities	string[]	是	响应模态，图像生成需包含 "IMAGE"，可组合 ["TEXT", "IMAGE"]
generationConfig.imageConfig	object	否	图像相关配置
generationConfig.imageConfig.aspectRatio	string	否	宽高比，例如 "1:1"、"16:9"、"9:16"、"4:3"、"3:4"
generationConfig.imageConfig.imageSize	string	否	图像尺寸档位，例如 "1K"、"2K"、"4K"（不同模型支持档位不同）

请求示例

文生图（cURL）

curl "https://www.free-api.ai/api/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "一只戴着宇航头盔的橘猫漂浮在星云之间，写实风格，高细节" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "4K"
      }
    }
  }'

图生图 / 图像编辑

在 parts 中同时提供参考图 (inlineData) 与编辑指令文本：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<base64-encoded-image>"
          }
        },
        { "text": "把背景替换为夕阳下的海边，保持主体不变" }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"]
  }
}

Python (google-genai SDK)

import base64
from google import genai
from google.genai import types

client = genai.Client(
    api_key="your-api-key",
    http_options={"base_url": "https://www.free-api.ai/api"},
)

resp = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="一只戴着宇航头盔的橘猫漂浮在星云之间，写实风格，高细节",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

for part in resp.candidates[0].content.parts:
    if part.inline_data:
        with open("out.png", "wb") as f:
            f.write(part.inline_data.data)

响应示例

图像以 Base64 的 inlineData 形式返回，可能同时包含文本与图像 part：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "已为您生成一张太空橘猫图。" },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<base64-encoded-image>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 24,
    "candidatesTokenCount": 128,
    "totalTokenCount": 152
  }
}

保存图像（以 Python 为例）：

import base64

with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

常见问题

• 返回中没有图像 part：请检查 generationConfig.responseModalities 是否包含 "IMAGE"，以及所选模型是否支持图像生成。
• 宽高比不生效：部分模型仅支持固定档位的 aspectRatio，请参考模型文档。
• 图像被安全策略拦截：finishReason 为 SAFETY 时，尝试调整提示词或降低敏感内容。

常见错误

HTTP 状态	说明
400	请求参数错误
401 / 403	鉴权失败
429	请求频率限制
5xx	上游服务异常