Gemini 图像生成（OpenAI 兼容格式）

通过 OpenAI 兼容的 POST /v1/images/generations 接口调用 Gemini 图像模型。适用于已有基于 OpenAI SDK / DALL·E 接口的代码，希望在最小改动下切换到 Gemini 图像模型的场景。

WARNING

建议优先使用 Gemini 原生格式图像生成。本接口由代理侧将 OpenAI 图像请求转换为 Gemini generateContent 调用，可能存在以下问题：

• OpenAI size 档位（1024x1024 等）与 Gemini aspectRatio / imageSize 不完全对应，可能被就近映射；
• OpenAI 的 quality、style、response_format 等字段部分可能被忽略；
• 批量生成 (n > 1)、图像编辑等高级场景支持度可能不同；
• 新模型或新参数的适配可能滞后于原生接口。

具体支持范围、字段映射规则与已知差异请咨询 FreeAPI。

请求

Endpoint

POST https://www.free-api.ai/api/v1/images/generations

请求头

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

请求参数

字段	类型	必填	说明
model	string	是	Gemini 图像模型 ID，例如 gemini-2.5-flash-image-preview、gemini-3-pro-image-preview
prompt	string	是	图像描述
n	integer	否	生成数量，默认 1
size	string	否	图像尺寸，如 1024x1024、1792x1024、1024x1792；会被映射为 Gemini 的 aspectRatio
quality	string	否	质量档位，standard / hd；在 Gemini 侧可能被忽略
style	string	否	风格，vivid / natural；在 Gemini 侧可能被忽略
response_format	string	否	响应格式，url 或 b64_json；Gemini 通常返回 b64_json
user	string	否	终端用户标识

请求示例

cURL

curl https://www.free-api.ai/api/v1/images/generations \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "一只戴着宇航头盔的橘猫漂浮在星云之间，写实风格，高细节",
    "n": 1,
    "size": "1792x1024",
    "response_format": "b64_json"
  }'

Python (OpenAI SDK)

import base64
from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://www.free-api.ai/api/v1",
)

resp = client.images.generate(
    model="gemini-3-pro-image-preview",
    prompt="一只戴着宇航头盔的橘猫漂浮在星云之间，写实风格，高细节",
    n=1,
    size="1792x1024",
    response_format="b64_json",
)

with open("out.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

响应示例

{
  "created": 1730000000,
  "data": [
    {
      "b64_json": "<base64-encoded-image>",
      "revised_prompt": "..."
    }
  ]
}

当 response_format 为 url 时，data[].url 返回图片链接；但由于 Gemini 上游默认以 Base64 返回，建议始终使用 b64_json 以获得最稳定的行为。

字段映射参考

OpenAI 参数	Gemini 对应	说明
prompt	contents[0].parts[0].text	文本提示词
size = "1024x1024"	aspectRatio = "1:1"	近似映射
size = "1792x1024"	aspectRatio = "16:9"	近似映射
size = "1024x1792"	aspectRatio = "9:16"	近似映射
n	多次调用或 candidate 数	不同模型实现方式不同
quality / style	—	通常被忽略

以上映射规则仅供参考，实际以代理侧实现为准。

常见错误

HTTP 状态	说明
400	请求参数错误，或 size / model 不被支持
401	鉴权失败
429	请求频率限制
5xx	上游服务异常

何时改用原生接口

如果遇到以下情况，建议切换到 Gemini 原生格式图像生成：

• 需要精细控制 aspectRatio、imageSize 等 Gemini 专属参数；
• 需要图生图 / 图像编辑（传入参考图 + 指令）；
• 需要同时获取文本与图像的多模态输出；
• 使用较新的 Gemini 图像模型且发现兼容接口行为异常。