Gemini Image | UniKeyX API Docs

1

Text to image

文字生成图片

cURL

curl https://www.unikeyx.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "一只哑光蓝色陶瓷杯，白色摄影棚背景，居中构图，柔和自然阴影，不要文字和 Logo"
          }
        ]
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "1:1",
          "image_size": "1K"
        }
      }
    }
  }'

Google 图片模型使用 /chat/completions，不要改成 /images/generations。图片参数必须放在 extra_body.google.image_config 中。

2

Image editing

加入参考图进行编辑

使用 HTTP 图片 URL

curl https://www.unikeyx.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "保持商品主体不变，只把背景替换为浅灰色摄影棚，并保留原来的构图和阴影方向"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/product-reference.jpg"
            }
          }
        ]
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "1:1",
          "image_size": "1K"
        }
      }
    }
  }'

使用本地图片 Base64

import base64
import mimetypes
import os
import requests

API_KEY = "YOUR_UNIKEYX_API_KEY"
IMAGE_PATH = "product-reference.png"
mime_type = mimetypes.guess_type(IMAGE_PATH)[0] or "image/png"
file_size = os.path.getsize(IMAGE_PATH)

if file_size > 7_000_000:
    raise ValueError("参考图超过 7 MB，请压缩后再发送")

with open(IMAGE_PATH, "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("ascii")

payload = {
    "model": "gemini-3.1-flash-image",
    "stream": False,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "保留产品颜色、结构和 Logo，只更换为户外露营场景"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:{mime_type};base64,{encoded}"
                }
            }
        ]
    }],
    "extra_body": {
        "google": {
            "image_config": {
                "aspect_ratio": "1:1",
                "image_size": "1K"
            }
        }
    }
}

response = requests.post(
    "https://www.unikeyx.com/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=300,
)
response.raise_for_status()
result = response.json()

3

Attachments

参考图与 HTTP 附件规则

支持格式 使用 JPEG、PNG 或 WebP。扩展名与实际文件内容必须一致。

HTTP / HTTPS URL 必须能被 UniKeyX 服务端直接访问，并直接返回图片内容。登录页、HTML 页面和需要 Cookie 的私有链接不能作为参考图。

本地文件 不能发送 C:\image.png 等本机路径。请读取文件并转换为 data:image/...;base64,...。

多张参考图 按顺序继续追加 image_url 内容块。建议一次不超过 9 张，并在提示词里说明每张图的用途。

文件体积 当前 UniKeyX Gemini Image 兼容链路要求每张参考图原始文件不超过 7 MB（7,000,000 bytes）。HTTP 图片被服务端读取后也按同一规则处理。

Base64 会让请求体增大约 33%。例如 7.14 MB 的 PNG 转换后约为 9.52 MB，可能被上游立即拒绝。为给 JSON、提示词和请求头留出空间，生产环境建议把单张参考图压缩到 5 MB 以内，再转换为 Base64。压缩只用于请求传输，不需要覆盖原始图片。

4

Parameters

尺寸、比例与分辨率

model 当前使用 gemini-3.1-flash-image。提交前可通过 GET /v1/models 确认 Token 是否有模型权限。

aspect_ratio 1:1、1:4、1:8、2:3、3:2、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9。

image_size UniKeyX 已验证可用 1K、2K、4K。分辨率越高，等待时间和费用通常越高。

字段命名 OpenAI 兼容请求使用蛇形字段：image_config、aspect_ratio、image_size，不要使用 imageConfig 或 aspectRatio。

stream 图片请求建议设为 false，等待完整 JSON 响应后再提取图片。

5

Response

读取并保存返回图片

Python：兼容 PNG / JPEG / WebP Data URL

import base64
import re

content = result["choices"][0]["message"]["content"]
match = re.search(
    r"data:(image/[a-zA-Z0-9.+-]+);base64,([a-zA-Z0-9+/=\s]+)",
    content,
)

if not match:
    raise RuntimeError("响应中没有找到图片数据")

mime_type = match.group(1).lower()
extension = {
    "image/jpeg": "jpg",
    "image/png": "png",
    "image/webp": "webp",
}.get(mime_type, "bin")

image_bytes = base64.b64decode("".join(match.group(2).split()))
with open(f"google-image-output.{extension}", "wb") as output:
    output.write(image_bytes)

不要把输出格式写死为 PNG。实际响应可能是 JPEG、PNG 或 WebP，保存文件时应以 Data URL 中的 MIME 类型为准。

FAQ

Gemini Image FAQ

为什么调用 /images/generations 失败？

Google 图片模型是多模态对话模型，请使用 /v1/chat/completions，并在消息内容中传文字和参考图。

HTTP 图片 URL 为什么读取失败？

确认 URL 能从公网直接下载图片、返回正确的图片 Content-Type，且不需要登录、Cookie、Referer 或临时浏览器会话。私有图片请改用 Base64 Data URL。

加入参考图后为什么立即生图失败？

先检查单张原始图片是否超过 7,000,000 bytes。Base64 编码会增加约三分之一体积；建议先压缩到 5 MB 以内，再作为 Data URL 发送。HTTP 图片也应遵守相同的单图限制。

400：imageConfig / aspectRatio 不支持

OpenAI 兼容请求必须使用 image_config、aspect_ratio 和 image_size。

401：Token 无效

请使用在 www.unikeyx.com 创建、且已获得该模型权限的 Token。不要混用其他环境或其他站点签发的 Token。

响应为什么不是普通图片 URL？

兼容接口通常把图片作为 Markdown 中的 Base64 Data URL 返回。请按本页“读取并保存返回图片”的示例提取 MIME 类型和字节内容。