Gemini 生图 API

Gemini 生图 API

Gemini 图片调用使用原生 v1beta 路径，而不是 OpenAI Images 路径。它适用于文生图、带参考图的编辑和图生图；模型与可用尺寸以当前 Key 的模型列表为准。

1. 接口总览

Base URL 是 https://mrxapi.com。

2. 鉴权

推荐把 API Key 放在请求头：

复制Authorization: Bearer sk-替换为你的密钥
Content-Type: application/json

部分 Gemini 客户端使用 x-goog-api-key。仅当你的 SDK 明确要求此头时使用，并确保 Key 不出现在 URL、浏览器前端或日志中。

3. 查询模型

复制curl "https://mrxapi.com/v1beta/models" \
  -H "Authorization: Bearer $MRXAPI_KEY"

从返回的 models[].name 或模型广场获取真实模型 ID。模型列表受 Key 分组限制，列表中没有的模型不能通过改写请求名称调用。

4. 文生图

复制curl --request POST "https://mrxapi.com/v1beta/models/MODEL_ID:generateContent" \
  --header "Authorization: Bearer $MRXAPI_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "简洁的产品海报，干净留白，16:9，无文字"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}
    }
  }'

5. 请求字段

尺寸和画幅是模型能力，不是网关对输出像素的保证。生产业务应读取返回图片的实际尺寸。

6. 图片编辑 / 图生图

把编辑指令与输入图片放到同一个 parts 数组中。Base64 只传数据本体，不要带 data:image/...;base64, 前缀：

复制{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "保留主体和构图，把背景改为晨雾森林"},
      {"inlineData": {"mimeType": "image/png", "data": "BASE64_IMAGE"}}
    ]
  }],
  "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}

7. 读取成功响应

图片通常位于：

复制candidates[].content.parts[].inlineData.data

客户端应同时检查 HTTP 状态、candidates 是否存在，以及是否有 inlineData.data；HTTP 200 本身不代表一定获得图片。根据 inlineData.mimeType 保存对应文件类型。

8. 超时、重试与并发

图片生成耗时可能明显长于文本请求。客户端设置合理超时；网络异常时使用有限次数退避重试。不要对同一不可幂等请求无限重放，避免重复生成与计费。

9. 常见错误

10. 接入验收清单

确认模型列表可读、最小文生图有图片数据、输出可解码、控制台记录可见，并确认 Key 未暴露在客户端日志中。