Imagen 快速入门指南：使用 Gemini API 生成图像

本文面向具备编程基础的开发者，系统讲解如何通过 Google Gemini Python SDK 调用 Imagen 4 系列模型完成文本到图像生成。内容覆盖 SDK 安装、API 密钥配置、客户端初始化、模型选型（Imagen 4、Ultra、Fast、Imagen 3）、提示词参数（number_of_images、person_generation、aspect_ratio、image_size、output_mime_type）的语义与约束，并分析 generate_images 调用流程、SynthID 水印机制及文本渲染能力。同时给出常见错误排查与生产优化建议。

技术背景

文本到图像生成已从研究演示走向产品级能力，但开发者常面临模型选型混乱、参数语义不清、付费与配额限制不透明、生成结果不可控等问题。Imagen 4 系列是 Google 当前质量最高的文生图模型，通过 Gemini API 统一暴露，支持自然语言提示、多风格输出和文本渲染。它适用于营销素材、插画、漫画分镜、书籍配图等场景。主要限制包括：仅限付费用户、单次最多生成 4 张、人物生成策略受限（儿童始终禁止）、输出格式目前仅支持 JPEG，且所有图像嵌入不可见 SynthID 水印。

核心原理

Imagen 基于扩散模型，将文本提示编码为条件向量，逐步去噪生成图像。Gemini Python SDK 采用“客户端一次初始化、模型每次调用指定”的设计：genai.Client(api_key=...) 负责认证与传输，client.models.generate_images(model=..., prompt=..., config=...) 负责推理。config 中的 number_of_images 控制采样数量，person_generation 控制人物策略，aspect_ratio 与 image_size 控制输出几何与分辨率，output_mime_type 控制编码格式。返回对象 result.generated_images 是列表，每项包含 image 对象，Colab 中可直接 .show()，外部环境需用 PIL.Image.open(BytesIO(image.image_bytes)) 解码。SynthID 在生成阶段嵌入，用于溯源与合规。

架构分析

整体数据流为：提示词与配置 → SDK 序列化 → Gemini API 网关鉴权与配额校验 → Imagen 推理集群 → 图像编码与 SynthID 嵌入 → 返回 generated_images 列表。关键设计决策包括：模型 ID 与客户端解耦，便于灰度切换；配置以 dict 传入，保持 REST 与 SDK 一致；人物生成采用白名单策略，儿童硬性禁止；分辨率与宽高比分离，避免隐式裁剪。生产集成时建议将客户端封装为单例，配置集中管理，并对返回图像做持久化与元数据记录。

完整实战教程

##### 版权所有 2026 Google LLC。

# @title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Gemini API：图像生成入门

Imagen 4 系列模型是 Google 质量最高的文本到图像模型，具备多项新增和改进的能力。Imagen 4 可以做到以下几点：

* 生成细节精细、光照丰富且几乎没有干扰性伪影的图像

* 理解用自然语言编写的提示词

* 生成多种格式和风格的图像

* 有效渲染文本

本 notebook 使用 Python SDK。如需 REST API，请查看 Imagen 入门 指南。

注意： 图像生成是仅限付费用户的功能，如果你使用的是免费套餐，将无法使用。请查看定价页面了解详情。

设置

安装 SDK

从 PyPI 安装 SDK。

%pip install -q -U google-genai

设置您的 API 密钥

要运行以下单元格，您的 API 密钥必须存储在名为 GEMINI_API_KEY 的 Colab Secret 中。如果您还没有 API 密钥，或者不确定如何创建 Colab Secret，请参阅

Authentication image以获取演练。

from google.colab import userdata

GEMINI_API_KEY = userdata.get('GEMINI_API_KEY')

初始化 SDK 客户端

使用新版 SDK，你现在只需用 API 密钥（如果使用 Vertex AI，则使用 OAuth）初始化一个客户端。模型现在在每次调用时设置。

from google import genai

client = genai.Client(api_key=GEMINI_API_KEY)

生成图像

选择模型

你可以从一系列可用的 Imagen 模型中进行选择：

* Imagen 4（imagen-3.0-generate-002）是新的标准模型，你应该使用它来生成图像。

* Imagen 4 Ultra（imagen-3.0-generate-002）是最好的 Imagen 模型，能够生成更精细的图像，尤其擅长生成包含文字的图像。请注意，它一次只能生成一张图像。

* Imagen 4 Fast（imagen-4.0-fast-generate-001）是一个更快的模型，与 Imagen 4 和 Ultra 相比，生成成本更低。详情请参阅定价页面。

* Imagen 3（imagen-3.0-generate-002）是上一代模型。如果你需要重新运行旧的提示词，它仍然可用，但现在建议使用第 4 代模型。

MODEL_ID = "imagen-3.0-generate-002" # @param ["imagen-3.0-generate-002", "imagen-3.0-generate-002", "imagen-4.0-fast-generate-001", "imagen-3.0-generate-002"] {"allow-input":true}

提示词创建

现在，编写你的提示词并设置一些可选参数。imagen-3.0-generate-002 模型基于长描述进行训练，因此更长、更具描述性的提示词会带来更好的结果。请注意，如果你使用较短的提示词，可能会导致遵循度较低，输出更加随机。

查看提示词指南以获取有关创建提示词的更多建议。

以下是可以设置的与提示词相关的参数：

* number_of_images：指定将生成多少张图像。默认值为 4，有效值介于 1 到 4 之间（含）。在下面的代码单元格中，使用 sample_count 来定义此参数。

* person_generation：允许模型生成包含成年人的图像。儿童始终被阻止。支持的值为 DONT_ALLOW 和 ALLOW_ADULT。默认值为 ALLOW_ADULT。

* aspect_ratio：指定生成图像的宽高比。支持的值为 1:1、3:4、4:3、16:9 和 9:16。默认值为 1:1。

* image_size：图像的输出分辨率，对于支持的模型，可以是 1k（默认）或 2k。

* output_mime_type：图像的输出类型，将为 image/jpeg。这是目前唯一允许的值。

生成的图像中始终会添加不可见的数字 SynthID 水印。

prompt = "A cat lounging lazily on a sunny windowsill playing with a kid toy." # @param {type:"string"}
number_of_images = 1 # @param {type:"slider", min:1, max:4, step:1}
person_generation = "ALLOW_ADULT" # @param ['DONT_ALLOW', 'ALLOW_ADULT']
aspect_ratio = "1:1" # @param ["1:1", "3:4", "4:3", "16:9", "9:16"],
image_size = "1k" # @param ["1k", "2k"]

生成图像

result = client.models.generate_images(
    model=MODEL_ID,
    prompt=prompt,
    config=dict(
        number_of_images=number_of_images,
        output_mime_type="image/jpeg",
        person_generation=person_generation,
        aspect_ratio=aspect_ratio,
        image_size=image_size,
    )
)

显示图像

使用以下代码查看你生成的图像。

for generated_image in result.generated_images:
  (image := generated_image.image).show()

# Outside of Colab, you'll need to use those libraries to open the images
# from PIL import Image
# from io import BytesIO
# for generated_image in result.generated_images:
#   image = Image.open(BytesIO(generated_image.image.image_bytes))

Notebook output

使用文本生成图像

Imagen 3 和 4 模型擅长生成带有文本的图像。以下是一个漫画条的示例：

prompt = "A 3-panel cosmic epic comic. Panel 1: Tiny 'Stardust' in nebula; radar shows anomaly (text 'ANOMALY DETECTED'), hull text 'stardust'. Pilot whispers. Panel 2: Bioluminescent leviathan emerges; console red text 'WARNING!. Panel 3: Leviathan chases ship through asteroids; console re text 'SHIELD CRITICAL!', screen text 'EVADE!'. Pilot screams, SFX 'CRUNCH!', 'ROOOOAAARR!'." # @param {type:"string"}
number_of_images = 1 # @param {type:"slider", min:1, max:4, step:1}
person_generation = "ALLOW_ADULT" # @param ['DONT_ALLOW', 'ALLOW_ADULT']
aspect_ratio = "1:1" # @param ["1:1", "3:4", "4:3", "16:9", "9:16"]

result = client.models.generate_images(
    model=MODEL_ID,
    prompt=prompt,
    config=dict(
        number_of_images=number_of_images,
        output_mime_type="image/jpeg",
        person_generation=person_generation,
        aspect_ratio=aspect_ratio
    )
)

for generated_image in result.generated_images:
  (image := generated_image.image).show()

Notebook output

这是第二个示例。这一次，由于需要处理的文本相当多，笔记本中保存的图像是使用 Imagen 4 Ultra 生成的：

prompt = "a wall on which a colorful tag is drawn and that cab be read as the first verse of Charles Baudelaire's poem \"l'invitation au voyage\": Mon enfant, ma sœur,    Songe à la douceur  D’aller là-bas vivre ensemble !    Aimer à loisir,    Aimer et mourir  Au pays qui te ressemble !" # @param {type:"string"}
number_of_images = 1 # @param {type:"slider", min:1, max:4, step:1}
person_generation = "ALLOW_ADULT" # @param ['DONT_ALLOW', 'ALLOW_ADULT']
aspect_ratio = "9:16" # @param ["1:1", "3:4", "4:3", "16:9", "9:16"]

result = client.models.generate_images(
    model=MODEL_ID,
    prompt=prompt,
    config=dict(
        number_of_images=number_of_images,
        output_mime_type="image/jpeg",
        person_generation=person_generation,
        aspect_ratio=aspect_ratio
    )
)

for generated_image in result.generated_images:
  (image := generated_image.image).show()

Notebook output

后续步骤

实用文档参考：

要提升你的提示词编写技巧，请查看提示词指南，其中提供了关于创建提示词的绝佳建议。

查看这些精彩的 Imagen 示例：

以下是一些 Imagen 示例，帮助你开启想象，探索如何以富有创意的方式使用它：

* 为书籍绘制插图：使用 Gemini 和 Imagen 为一本开源书籍创建插图

继续探索 Gemini API

Gemini 不仅擅长生成图像，也擅长理解图像。请查看空间理解指南，了解这些能力的介绍，并查看视频理解指南获取视频示例。

常见问题

常见错误：1) 免费套餐调用返回权限错误，需确认已开通付费并查看定价页；2) GEMINI_API_KEY 未设置或 Colab Secret 名称不匹配，检查 userdata.get('GEMINI_API_KEY')；3) 模型 ID 拼写错误或使用了未开放模型，核对可用列表；4) number_of_images 超出 1-4 范围导致参数校验失败；5) 提示词过短导致遵循度低、输出随机，应使用长描述性提示；6) 非 Colab 环境直接调用 .show() 报错，改用 PIL 解码；7) 文本渲染不理想时，可切换 Imagen 4 Ultra 并明确文字内容与位置。排查时优先打印异常响应体，确认配额、区域与模型可用性。

企业应用扩展

生产优化方向：1) 将 API 密钥放入 Secret Manager 或环境变量，避免硬编码；2) 对生成结果做缓存与去重，降低重复调用成本；3) 使用异步或批量任务队列控制并发，避免触发速率限制；4) 记录 prompt、模型 ID、参数与 SynthID 元数据，满足审计与合规；5) 对图像做后处理与压缩，适配不同终端；6) 结合 Gemini 的图像理解能力做自动质检与打标；7) 关注 Imagen 4 Fast 以降低成本，Ultra 用于高质量文本渲染场景；8) 参考官方提示词指南持续迭代提示词模板。

总结

本文面向具备编程基础的开发者，系统讲解如何通过 Google Gemini Python SDK 调用 Imagen 4 系列模型完成文本到图像生成。内容覆盖 SDK 安装、API 密钥配置、客户端初始化、模型选型（Imagen 4、Ultra、Fast、Imagen 3）、提示词参数（number_of_images、person_generation、aspect_ratio、image_size、output_mime_type）的语义与约束，并分析 generate_images 调用流程、SynthID 水印机制及文本渲染能力。同时给出常见错误排查与生产优化建议。

内容来源与验证

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员
查看全部API 与工程实践教程