图像模型进阶用户更新于
POST/v1/images/generations

API 调试台

POST/v1/images/generations
查看密钥

使用你填写的 Key 发送真实请求，按对应接口计费。

Gemini 3 Pro Image Preview

请求 ID gemini-3-pro-image-preview

协议

认证

请求需要 API Key。在控制台的 API Key 管理 获取密钥。发送 JSON 请求时，设置 Content-Type: application/json。

  • Authorization: Bearer YOUR_API_KEY
  • Gemini · x-goog-api-key: YOUR_API_KEY

请求参数

POST /v1/images/generations

参数类型是否必填说明
modelstring必填填写此模型的请求 ID gemini-3-pro-image-preview.
promptstring必填描述要生成的图像。
aspect_ratiostring选填输出图像的宽高比。 例如 1:1 或 16:9。 省略时根据 size 推导。 默认 1:1.
image_sizestring选填输出分辨率档位。 可用值 1K, 2K, 4K. 省略时根据 size 推导。 默认 1K.
ninteger选填单次请求的图片数量，建议保持为 1。 默认 1.
image_urlsstring[]选填JSON 参考图数组。每项可为公开 HTTPS 图片链接或 Base64 图片 data URL。 兼容字段 image_input. 参考图上限 4.
?asyncstring选填URL 查询参数。传 1、true 或 yes 返回 202 和 task_id。省略时等待生成结果。

POST /v1/images/edits

参数类型是否必填说明
modelstring必填填写此模型的请求 ID gemini-3-pro-image-preview.
promptstring必填描述要对参考图进行的修改。
aspect_ratiostring选填输出图像的宽高比。 例如 1:1 或 16:9。 省略时根据 size 推导。 默认 1:1. 编辑时通过 JSON 请求体传入。
image_sizestring选填输出分辨率档位。 可用值 1K, 2K, 4K. 省略时根据 size 推导。 编辑时通过 JSON 请求体传入。 默认 1K.
ninteger选填单次请求的图片数量，建议保持为 1。 默认 1.
image_urlsstring[]视条件JSON 参考图数组。每项可为公开 HTTPS 图片链接或 Base64 图片 data URL。 兼容字段 image_input. 参考图上限 4. 使用 JSON 编辑时至少传一张。
image[]file[]视条件使用 multipart/form-data 编辑时，至少上传一张图片，可重复传此字段。单文件也可用 image。 参考图上限 4.
?asyncstring选填URL 查询参数。传 1、true 或 yes 返回 202 和 task_id。省略时等待生成结果。

POST /v1beta/models/gemini-3-pro-image-preview:generateContent

参数类型是否必填说明
model (path)string必填URL 路径中的模型 ID，填写 gemini-3-pro-image-preview。
contentsobject[]必填按顺序排列的会话内容。每项使用 parts 保存输入片段。
contents[].rolestring选填消息角色。普通用户输入使用 user，模型历史消息使用 model。
contents[].partsobject[]必填内容项中的片段数组。文本片段使用 text。
contents[].parts[].inlineDataobject视条件内联媒体对象。使用 mimeType 和 Base64 编码的 data。可用媒体类型取决于模型和接入点。
systemInstructionobject选填系统指令对象。把指令文字放入 parts[].text。
generationConfig.maxOutputTokensinteger选填输出 token 的上限。可用上限因模型和接入点而异。
generationConfig.responseModalitiesstring[]选填输出类型列表。使用 ["IMAGE"] 请求图片。

请求示例

先将 API Key 设置为本机环境变量 ICODEEASY_API_KEY，并选择支持直接 HTTP 调用的接入点。接入点要求特定客户端时，按对应客户端指南配置。

示例中的素材 URL 和素材 ID 需要替换成自己的有效素材。

Images Generations

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/generations' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3-pro-image-preview",
  "prompt": "A watercolor illustration of a paper lantern by a lake.",
  "aspect_ratio": "16:9",
  "image_size": "1K"
}'

Images Edits

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/edits' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3-pro-image-preview",
  "prompt": "Change the background to a pale blue wall. Preserve the subject.",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "aspect_ratio": "16:9",
  "image_size": "1K"
}'

Gemini generateContent

bash
curl -sS 'https://api.icodeeasy.cc/v1beta/models/gemini-3-pro-image-preview:generateContent' \
  -H "x-goog-api-key: $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "A watercolor illustration of a paper lantern by a lake."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}'

Gemini generateContent · JSON

查询图片任务

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

响应与任务

/v1/images/generations · /v1/images/edits

HTTP 200 · 同步成功

使用 ?sync=1 时，成功响应中的 data[].url 是图片地址。created 为 Unix 秒时间戳，id 为任务 ID。

json
{
  "id": "d142c93a-de26-40c9-be62-0de840d10960",
  "created": 1781599773,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

HTTP 202 · 异步提交

json
{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "pending"
}

使用 ?async=1 后，用同一 API Key 查询 GET /v1/images/tasks/{task_id}。status 可为 pending、completed 或 failed。完成后从 result_url 读取图片地址。

HTTP 200 · 查询到已完成任务

json
{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gemini-3-pro-image-preview",
  "result_url": "https://example.com/generated-image.png"
}

常见错误

查询返回 failed 时读取 error。若存在 error_detail，根据 retryable 判断是否适合重新提交。

响应示例与错误处理

Gemini generateContent · JSON

遍历 candidates[].content.parts[]，从含有 inlineData 的块中读取图片。按 mimeType 保存 Base64 解码后的 data。

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    }
  ]
}

完整接入指南 · 查看完整接口指南，了解请求字段、任务状态和响应格式。

能力与限制

  • text_to_image · 支持
  • image_to_image · 支持
  • image_editing · 支持
  • native_generation · 支持
  • reference_images · 有条件支持 — 需要以支持的请求格式提供有效参考图
  • 限制 参考图：最多 4 张 · 分辨率: 1k, 2k, 4k

兼容别名与退役重定向

  • gemini-3-pro-image → gemini-3-pro-image-preview (别名)

模型能力目录 · 查看定价

相关指南

图片生成 API

用 OpenAI 兼容接口生成或编辑图片，提交提示词、尺寸和参考图，读取同步结果或查询异步任务状态。

Gemini 原生生成接口

用 Gemini 原生格式发起普通 JSON 请求或 SSE 流式请求。模型 ID 写在路径中，文本输入通过 contents[].parts[] 传入。

模型能力目录

按文本、图片和视频分类查看公开模型的规范化请求 ID、兼容协议、支持客户端、工具调用、输入输出能力与限制，并根据最近核对日期判断信息新鲜度。

注册并获取 API Key