Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kapon.cloud/llms.txt

Use this file to discover all available pages before exploring further.

本文档介绍如何使用 Gemini 原生 API 协议（generateContent）调用图像生成模型，适用于需要完整参数控制的高级场景。
对于大多数用户，推荐使用更简单的 OpenAI 兼容接口。

​
接口地址

POST /v1beta/models/{model}:generateContent

​
支持的模型

模型最大分辨率特点
gemini-3-pro-image-preview4K高质量，支持复杂提示词
gemini-2.5-flash-image1K快速生成

​
基础请求

curl -X POST "$BASE_URL/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "一只熊猫在图书馆看书，赛博朋克风格"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["image", "text"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "2K"
      }
    }
  }'

​
请求参数

​
contents 数组（必填）

每个 content 对象包含 parts 数组：
部分类型说明
text文本提示词
inline_dataBase64 编码的参考图（用于图像编辑）

​
generationConfig 对象

参数类型说明
responseModalitiesstring[]响应模态，图像生成需包含 "image"

​
generationConfig.imageConfig 对象

参数类型默认值说明
aspectRatiostring"1:1"宽高比
imageSizestring"1K"分辨率档位

​
宽高比设置

常用宽高比如下：
值输出特点适用场景
1:1正方形头像、图标
2:3 / 3:2经典插画比例角色立绘、构图较细腻的插画
3:4 / 4:3略偏竖/偏横移动端/桌面端插画
4:5 / 5:4接近相纸比例人像、摄影风格图
16:9横向宽屏网页横幅、视频封面
9:16竖向手机壁纸、社交媒体
21:9超宽电影感Banner、大屏展示

​
分辨率档位说明

imageConfig.imageSize 支持三个档位：
档位含义典型用途
1K约 1K 级别像素（最长边约 1K）预览、移动端、小图
2K约 2K 级别像素高清插画、桌面壁纸
4K约 4K 级别像素超高清、精修图、大屏展示
不同宽高比在各档位下的典型像素，可以参考《Gemini 图像生成》中的分辨率与宽高比表格，例如：
  • Gemini 2.5 Flash（1K 档）：
    • 1:1 → 1024×1024
    • 16:9 → 1344×768
    • 9:16 → 768×1344
  • Gemini 3 Pro Image 预览版：
    • 1K / 2K / 4K + 各宽高比（1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9）都有对应的标准分辨率栅格。
  • gemini-2.5-flash-image 仅支持 1K，指定更高档位会自动降级到 1K；
  • gemini-3-pro-image-preview 支持 1K / 2K / 4K 三档。

​
参考图编辑

通过 inline_data 传入参考图进行图像编辑： 
{
  "contents": [{
    "parts": [
      {
        "text": "将这张图片转换为油画风格"
      },
      {
        "inline_data": {
          "mime_type": "image/jpeg",
          "data": "<BASE64_IMAGE_DATA>"
        }
      }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["image", "text"],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "2K"
    }
  }
}

​
多参考图

可以在 parts 数组中添加多个 inline_data，最多支持 15 张参考图： 
{
  "contents": [{
    "parts": [
      {"text": "基于第一张图的构图，参考第二张的色调风格"},
      {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_BASE_IMAGE>"}},
      {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_STYLE_IMAGE>"}}
    ]
  }],
  "generationConfig": {
    "responseModalities": ["image", "text"],
    "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
  }
}

​
响应结构

{
  "candidates": [{
    "content": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<BASE64_IMAGE_DATA>"
          }
        },
        {
          "text": "生成完成的描述文本（可选）"
        }
      ]
    }
  }],
  "usageMetadata": {
    "promptTokenCount": 50,
    "candidatesTokenCount": 100,
    "totalTokenCount": 150
  }
}
字段说明
candidates[].content.parts[].inlineData生成的图片数据
usageMetadata.promptTokenCount输入文本 tokens
usageMetadata.candidatesTokenCount输出 tokens

​
计费说明

采用混合计费：
计费项说明
文本输入从 usageMetadata.promptTokenCount 获取
图像输出优先从 usageMetadata.candidatesTokensDetails 中 modality=image 的 token 数读取；若上游未细分，则按模型 & 分辨率档位近似折算 image tokens
大致规则（仅用于缺省情况下的近似计费）：
  • Gemini 2.5 Flash（1K 档）：输出每张约 1120 image tokens；
  • Gemini 3 Pro Image 预览版：
    • 1K / 2K 档：每张约 1120 image tokens；
    • 4K 档：每张约 2000 image tokens。

​
选择建议

场景推荐模型
快速原型验证gemini-2.5-flash-image
生产环境高质量gemini-3-pro-image-preview
复杂语义理解gemini-3-pro-image-preview
参考图风格迁移gemini-3-pro-image-preview

​
相关文档