# Gemini 图像生成

通过图片生成任务调用 Gemini 图像模型，传入参考图并轮询图片结果。

`gemini-3.1-flash-image-preview` 和 `gemini-3-pro-image-preview` 支持文生图和参考图生成。先调用 `GET /v1/models` 确认当前 API Key 可用的模型 ID。

新接入推荐创建异步图片任务：

```http
POST /v1/images/generations/jobs
```

保存返回的 `id`，再调用 `GET /v1/images/generations/jobs/{job_id}` 轮询结果。需要在同一个请求里等待生成完成的客户端，也可以使用同步接口 `POST /v1/images/generations`；生成可能耗时较长，请设置足够的客户端超时。

这两个接口使用 OpenAI Images 兼容的请求体（`model`、`prompt` 等），不是 Chat Completions 的 `messages`。如果使用 Gemini 原生协议，则调用 `/v1beta/models/{model}:generateContent`，请求和响应结构另有区别。

## 参数速查

| 参数 | 写法 | 说明 |
|---|---|---|
| `model` | `gemini-3.1-flash-image-preview` 或 `gemini-3-pro-image-preview` | 以模型列表为准 |
| `prompt` | 文本指令 | 描述主题、构图和参考图的用途 |
| `image` | 公网图片 URL 或 URL 数组 | 可选，按顺序传入参考图 |
| `aspect_ratio` | `1:1`、`16:9`、`9:16` 等 | 画面比例 |
| `image_size` | `1K`、`2K`、`4K` | 图片档位，具体可用值取决于模型和渠道 |
| `response_format` | `url` 或 `b64_json` | 结果格式；建议先使用 `url` |

不要把 `extra_body.google.image_config.aspect_ratio` 当作此图片接口的必填位置；这里直接传顶层 `aspect_ratio` 和 `image_size`。`size` 不是这两个模型指定图片档位的推荐字段。

## 模型 ID

| 产品名 | 模型 ID | 说明 |
|---|---|---|
| Gemini 3.1 Flash Image | `gemini-3.1-flash-image-preview` | 快速生成和编辑 |
| Gemini 3 Pro Image | `gemini-3-pro-image-preview` | 高质量生成和编辑 |

不要把 `nano_banana_2-4K` 与这两个 Gemini Preview 模型混用；前者是独立的模型 ID，以 `/v1/models` 实际返回值为准。

## 文生图

```bash
curl https://kaienapi.com/v1/images/generations/jobs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "生成一张 16:9 的科技产品横版海报，白色背景，画面干净，不要文字",
    "aspect_ratio": "16:9",
    "image_size": "1K",
    "response_format": "url"
  }'
```

`gemini-3-pro-image-preview` 使用相同的接口和请求结构，只需替换 `model`。需要 4K 时可将 `image_size` 改为 `4K`，并按实际返回的图片尺寸验证结果。

## 参考图生成

参考图使用公网可访问、在任务执行期间不会过期的 OSS/CDN URL。单图也可以作为一个元素放入 `image` 数组。

```bash
curl https://kaienapi.com/v1/images/generations/jobs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "把参考图转成干净的 3D 平面插画风格，保留主体轮廓和主要颜色，输出一张 1:1 图片。",
    "image": ["https://example.com/source.png"],
    "aspect_ratio": "1:1",
    "image_size": "1K",
    "response_format": "url"
  }'
```

多图时按顺序添加 URL，并在 `prompt` 中写明每张图的用途：

```json
{
  "model": "gemini-3-pro-image-preview",
  "prompt": "参考图 1 的人物和图 2 的配色，生成一张 16:9 横版海报。",
  "image": [
    "https://example.com/person.png",
    "https://example.com/style.png"
  ],
  "aspect_ratio": "16:9",
  "image_size": "2K",
  "response_format": "url"
}
```

本页示例使用网络 URL；如果参考图是本地文件，先上传并获取公网可访问的 URL，再提交图片任务。不要把 Chat Completions 的 `image_url` 内容块直接放进图片接口请求体。

## 读取结果

创建任务会返回任务 `id` 和状态。使用同一 API Key 查询：

```bash
JOB_ID="imgtask_xxx"
curl "https://kaienapi.com/v1/images/generations/jobs/$JOB_ID" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

`queued` 和 `running` 表示继续等待；`succeeded` 时从 `data` 读取图片；`failed` 时读取 `error.message`。例如：

```json
{
  "id": "imgtask_xxx",
  "object": "image.generation.job",
  "status": "succeeded",
  "model": "gemini-3.1-flash-image-preview",
  "data": [{ "url": "https://example.com/result.png" }]
}
```

建议前 30 秒每 `2-3` 秒轮询一次，之后可放慢到每 `5-10` 秒一次。客户端临时断线时保存任务 ID，恢复后继续查询，不要重新提交相同任务。同步接口成功时直接从响应的 `data` 数组读取图片，不返回任务状态供轮询。

`response_format: "b64_json"` 时读取 `data[].b64_json`；不同渠道可能只能返回 URL，接入时根据实际字段处理。长期保存图片请复制到自己的对象存储。

## 画幅与尺寸

图片接口在顶层传 `aspect_ratio` 和 `image_size`，例如：

```json
{
  "aspect_ratio": "16:9",
  "image_size": "2K"
}
```

同时在 `prompt` 里描述横版或竖版用途。宽高比是生成要求，不是严格的像素尺寸保证；依赖精确比例时应检查最终图片宽高。部分模型或渠道对参数的支持可能不同，遇到方图或尺寸不符时，先检查模型 ID、渠道和请求字段。

## 常见问题

**请求体用了 `messages` 或结果里找不到 `choices`**

图片生成接口使用 `prompt` 和可选的 `image` URL 数组；成功结果在 `data`，不在 `choices[0].message.content`。

**提交后没有立即得到图片**

异步接口先返回任务 ID。轮询 `/v1/images/generations/jobs/{job_id}`，直到状态为 `succeeded` 或 `failed`。

**传了比例但没有生效**

确认传的是顶层 `aspect_ratio`，并检查模型与实际图片尺寸。`image_size` 指定档位，不能替代画幅参数。