图片生成 API

Imagen API 使用文本提示来引导生成过程，可让您在几秒钟内生成高质量图片。您还可以使用 Imagen API 来提高图片的分辨率。

查看 Imagen for Generation 模型卡片

支持的模型

注意：自 2025 年 6 月 24 日起，Imagen 版本 1 和 2 已弃用。Imagen 模型 imagegeneration@002、imagegeneration@005 和 imagegeneration@006 将于 2025 年 9 月 24 日移除。 如需详细了解如何迁移到 Imagen 3，请参阅迁移到 Imagen 3。

注意：以下 Imagen 4 预览版模型将于 2025 年 11 月 30 日移除： imagen-4.0-generate-preview-06-06、 imagen-4.0-ultra-generate-preview-06-06 和 imagen-4.0-fast-generate-preview-06-06。为避免服务中断，请在 2025 年 11 月 30 日之前将使用 Imagen 4 预览版模型的所有工作流迁移到以下正式版 Imagen 4 模型：imagen-4.0-generate-001、imagen-4.0-ultra-generate-001、imagen-4.0-fast-generate-001。

Imagen API 支持以下模型：

• imagen-4.0-generate-001
• imagen-4.0-fast-generate-001
• imagen-4.0-ultra-generate-001
• imagen-3.0-generate-002
• imagen-3.0-generate-001
• imagen-3.0-fast-generate-001
• imagen-3.0-capability-001
• imagegeneration@006
• imagegeneration@005
• imagegeneration@002

重要提示：如果提示很复杂且您使用了增强型提示，imagen-4.0-fast-generate-001 生成的结果可能不理想。如要解决此问题，您可以将 enhancePrompt 设置为 false。

如需详细了解每个模型支持的功能，请参阅 Imagen 模型。

示例语法

用于通过文本提示创建图片的语法。

语法

用于生成图片的语法。

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_VERSION}:predict \
-d '{
  "instances": [
    {
      "prompt": "..."
    }
  ],
  "parameters": {
    "sampleCount": ...
  }
}'

Python

generation_model = ImageGenerationModel.from_pretrained("MODEL_VERSION")

response = generation_model.generate_images(
    prompt="...",
    negative_prompt="...",
    aspect_ratio=...,
)
response.images[0].show()

生成图片

REST

参数
prompt	string 必需。图片的文本提示。
addWatermark	bool 可选。向生成的图片添加不可见水印。 默认值为 true，但以下模型除外： imagegeneration@002 imagegeneration@005
aspectRatio	string 可选。生成的输出图片的宽高比。默认值为“1:1”。 此参数不适用于放大后的输出。
enhancePrompt	boolean 可选。一个可选参数，使用基于 LLM 的重写提示功能，以提供更高质量的图片，从而更好地反映原始提示的意图。停用此功能可能会影响图片质量和提示遵循度。
language	string 可选。与文本提示语言对应的语言代码。支持以下值： auto：自动检测。如果 Imagen 检测到受支持的语言，会将提示和（可选）反向提示翻译为英语。如果检测到不受支持的语言，Imagen 会按原样使用输入文本，这可能会导致意外输出。系统不会返回错误代码。 en：英语（如果省略，则其为默认值） zh 或 zh-CN：中文（简体） zh-TW：中文（繁体） hi：印地语 ja：日语 ko：韩语 pt：葡萄牙语 es：西班牙语
negativePrompt	string 可选。用于说明在生成的图片中不建议的内容。 imagen-3.0-generate-002 及更新版本的模型不支持 negativePrompt。
outputOptions	outputOptions 可选。在 outputOptions 对象中描述输出图片格式。
personGeneration	string 可选。允许模型生成人物。支持以下值： "dont_allow"：禁止在图片中包含人物或人脸。 "allow_adult"：仅允许生成成人。 "allow_all"：允许生成任何年龄的人。 默认值为 "allow_adult"。
safetySetting	string 可选。为安全性过滤策略添加过滤级别。支持以下值： "block_low_and_above"：最强的过滤级别，采用最严苛的屏蔽策略。已弃用的值："block_most"。 "block_medium_and_above"：屏蔽部分有问题的提示和回答。已弃用的值："block_some"。 "block_only_high"：减少因安全性过滤机制而被屏蔽的请求数量。Imagen 生成的不良内容的数量可能会增加。已弃用的值："block_few"。 "block_none"：屏蔽极少数有问题的提示和回答。此功能的使用是有一定限制的。 之前的字段值："block_fewest"。 默认值为 "block_medium_and_above"。
sampleCount	int 必需。要生成的图片数量。默认值为 4。
sampleImageSize	string 可选。指定生成的图片的输出分辨率。可接受的值为 "1K" 或 "2K"。默认值为 "1K"。
seed	Uint32 可选。用于生成图片的随机种子。当 addWatermark 设置为 true 时，此参数不可用。 如果 enhancePrompt 设置为 true，则 seed 参数将不起作用，因为 enhancePrompt 会生成新的提示，从而生成新的或不同的图片。
storageUri	可选：string。 用于存储生成的图片的 Cloud Storage URI。

输出选项对象

outputOptions 对象描述图片输出。

参数
outputOptions.mimeType	可选：string。 输出应另存为的图片格式。支持以下值： "image/png"：另存为 PNG 图片 "image/jpeg"：另存为 JPEG 图片 默认值为 "image/png"。
outputOptions.compressionQuality	可选：int。 如果输出类型为 "image/jpeg"，则为压缩级别。可接受 0 到 100 之间的值。默认值为 75。

响应

REST 请求的响应正文。

参数
predictions	VisionGenerativeModelResult 对象的数组，每个对象对应一个请求的 sampleCount。如果有任何图片被 Responsible AI 过滤掉，则不包括这些图片，除非 includeRaiReason 被设置为 true。

视觉生成模型结果对象

模型结果的相关信息。

参数
bytesBase64Encoded	base64 编码的生成图片。如果输出图片未通过 Responsible AI 的过滤机制，则不存在该参数。
mimeType	生成的图片的类型。如果输出图片未通过 Responsible AI 的过滤机制，则不存在该参数。
raiFilteredReason	Responsible AI 过滤原因。仅在启用了 includeRaiReason 且该图片被过滤掉的情况下才会返回该参数。
safetyAttributes.categories	安全性属性的名称。仅在启用了 includeSafetyAttributes 且输出图片通过了 Responsible AI 的过滤机制的情况下才会返回该参数。
safetyAttributes.scores	安全性属性的得分。仅在启用了 includeSafetyAttributes 且输出图片通过了 Responsible AI 的过滤机制的情况下才会返回该参数。

Python

参数
prompt	string 必需。图片的文本提示。
add_watermark	bool 可选。为生成的图片添加水印。 默认值为 true，但以下模型除外： imagegeneration@002 imagegeneration@005
aspect_ratio	string 可选。生成的输出图片的宽高比。默认值为“1:1”。 此参数不适用于放大后的输出。
compression_quality	int 可选。如果输出 MIME 类型为 "image/jpeg"，则为压缩级别。默认值为 75。
language	string 可选。图片的文本提示采用的语言。支持以下值： auto：自动检测。如果 Imagen 检测到受支持的语言，会将提示和（可选）反向提示翻译为英语。如果检测到不受支持的语言，Imagen 会按原样使用输入文本，这可能会导致意外输出。系统不会返回错误代码。 en：英语（如果省略，则其为默认值） zh 或 zh-CN：中文（简体） zh-TW：中文（繁体） hi：印地语 ja：日语 ko：韩语 pt：葡萄牙语 es：西班牙语 默认值为 "auto"。
negative_prompt	string 可选。用于说明在生成的图片中不建议的内容。 imagen-3.0-generate-002 及更新版本的模型不支持 negative_prompt。
number_of_images	int 必需。要生成的图片数量。默认值为 1。
output_gcs_uri	string 可选。用于存储生成的图片的 Cloud Storage URI。
output_mime_type	string 可选。输出应另存为的图片格式。支持以下值： "image/png"：另存为 PNG 图片 "image/jpeg"：另存为 JPEG 图片 默认值为 "image/png"。
person_generation	string 可选。允许模型生成人物。支持以下值： "dont_allow"：禁止生成人物 "allow_adult"：允许生成成人，但不允许生成儿童 "allow_all"：允许生成成人和儿童 默认值为 "allow_adult"。
safety_filter_level	string 可选。为安全性过滤策略添加过滤级别。支持以下值： "block_low_and_above"：最强的过滤级别，采用最严苛的屏蔽策略。已弃用的值："block_most"。 "block_medium_and_above"：屏蔽部分有问题的提示和回答。已弃用的值："block_some"。 "block_only_high"：屏蔽少数有问题的提示和回答。已弃用的值："block_few"。 "block_none"：屏蔽极少数有问题的提示和回答。已弃用的值："block_fewest"。 默认值为 "block_medium_and_above"。
sample_image_size	string 可选。指定生成的图片的输出分辨率。可接受的值为 "1K" 或 "2K"。默认值为 "1K"。
seed	int 可选。用于生成图片的随机种子。当 addWatermark 设置为 true 时，此参数不可用。 如果 enhancePrompt 设置为 true，则 seed 将不起作用，因为 enhancePrompt 会生成新的提示，从而生成新的或不同的图片。

提高图片的分辨率

REST

参数
mode	string 必需。对于分辨率提升请求，必须设置为 "upscale"。
upscaleConfig	UpscaleConfig 必需。UpscaleConfig 对象。
outputOptions	OutputOptions 可选。在 outputOptions 对象中描述输出图片格式。
storageUri	string 可选。用于存储生成的图片的 Cloud Storage URI。

分辨率提升配置对象

参数
upscaleConfig.upscaleFactor	string 必需。分辨率提升系数。支持的值包括 "x2" 和 "x4"。

响应

REST 请求的响应正文。

参数
predictions	VisionGenerativeModelResult 对象的数组，每个对象对应一个请求的 sampleCount。如果有任何图片被 Responsible AI 过滤掉，则不包括这些图片，除非 includeRaiReason 被设置为 true。

示例

以下示例展示了如何使用 Imagen 模型生成图片。

生成图片

REST

在使用任何请求数据之前，请先进行以下替换：

• PROJECT_ID：您的 Google Cloud 项目 ID。

• MODEL_VERSION：要使用的 Imagen 模型版本。如需详细了解可用的模型，请参阅 Imagen 模型。

• LOCATION：您的项目的区域。 例如 us-central1、europe-west2 或 asia-northeast3。如需查看可用区域的列表，请参阅 Vertex AI 上的生成式 AI 位置。
• TEXT_PROMPT：用于指导模型生成什么图片的文本提示。生成和修改都需要此字段。
• IMAGE_COUNT：生成的图片数量。 接受的整数值：1-8 (imagegeneration@002)、1-4（所有其他模型版本）。默认值：4。

其他可选参数

根据您的应用场景，使用以下可选变量。在 "parameters": {} 对象中添加以下部分或全部参数。此列表展示了常见的可选参数，但并非详尽无遗。如需详细了解可选参数，请参阅 Imagen API 参考文档：生成图片。

"parameters": {
  "sampleCount": IMAGE_COUNT,
  "addWatermark": ADD_WATERMARK,
  "aspectRatio": "ASPECT_RATIO",
  "enhancePrompt": ENABLE_PROMPT_REWRITING,
  "includeRaiReason": INCLUDE_RAI_REASON,
  "includeSafetyAttributes": INCLUDE_SAFETY_ATTRIBUTES,
  "outputOptions": {
    "mimeType": "MIME_TYPE",
    "compressionQuality": COMPRESSION_QUALITY
  },
  "personGeneration": "PERSON_SETTING",
  "safetySetting": "SAFETY_SETTING",
  "seed": SEED_NUMBER,
  "storageUri": "OUTPUT_STORAGE_URI"
}

• ADD_WATERMARK：布尔值。可选。是否为生成的图片启用水印。将该字段设置为 true 时生成的任何图片都包含数字 SynthID，您可以使用此 ID 来验证带水印的图片。如果您省略此字段，则系统会使用默认值 true；您必须将该值设置为 false 才能停用此功能。仅当 seed 字段设置为 false 时，您才可以使用该字段来获取确定性输出。
• ASPECT_RATIO：字符串。可选。用于控制宽高比的生成模式参数。支持的宽高比值及其预期用途：
  • 1:1（默认，方形）
  • 3:4（广告、社交媒体）
  • 4:3（电视、摄影）
  • 16:9（横向）
  • 9:16（纵向）
• ENABLE_PROMPT_REWRITING：布尔值。可选。一个参数，使用基于 LLM 的重写提示功能，以提供更高质量的图片，从而更好地反映原始提示的意图。停用此功能可能会影响图片质量和提示遵循度。默认值：true。
• INCLUDE_RAI_REASON：布尔值。可选。是否在输入或输出被屏蔽的回答中启用 Responsible AI 过滤的原因代码。默认值：true。
• INCLUDE_SAFETY_ATTRIBUTES：布尔值。可选。是否针对未经过滤的输入和输出在回答中启用安全属性列表的四舍五入 Responsible AI 分数。安全属性类别："Death, Harm & Tragedy"、"Firearms & Weapons"、"Hate"、"Health"、"Illicit Drugs"、"Politics"、"Porn"、"Religion & Belief"、"Toxic"、"Violence"、"Vulgarity"、"War & Conflict"。默认值为 false。
• MIME_TYPE：字符串。可选。图片内容的 MIME 类型。可用的值：
  • image/jpeg
  • image/gif
  • image/png
  • image/webp
  • image/bmp
  • image/tiff
  • image/vnd.microsoft.icon
• COMPRESSION_QUALITY：整数。可选。仅适用于 JPEG 输出文件。模型为以 JPEG 文件格式生成的图片保留的细节程度。值：0 到 100，数字越大表示压缩程度越高。默认值：75。
• PERSON_SETTING：字符串。可选。用于控制模型允许的人物类型或人脸生成的安全设置。可用的值：
  • allow_adult（默认）：仅允许生成成年人（名人除外）。不允许针对任何设置生成名人。
  • dont_allow：禁止在生成的图片中包含人物或人脸。
• SAFETY_SETTING：字符串。可选。用于控制所生成图片的安全性过滤机制阈值的设置。可用的值：
  • block_low_and_above：最高安全阈值，使过滤的生成图片的数量最多。之前的值：block_most。
  • block_medium_and_above（默认值）：中等安全性阈值，用于平衡潜在有害内容和安全内容的过滤选项。之前的值：block_some。
  • block_only_high：安全阈值，可减少因安全过滤器而被屏蔽的请求数量。此设置可能会增加 Imagen 生成的不良内容。 之前的值：block_few。
• SEED_NUMBER：整数。可选。您提供的任何非负整数，以使输出图片具有确定性。提供相同的种子编号会生成相同的输出图片。 如果您使用的模型支持数字水印，则必须设置 "addWatermark": false 才能使用此字段。接受的整数值：1 - 2147483647。
• OUTPUT_STORAGE_URI：字符串。可选。用于存储输出图片的 Cloud Storage 存储桶。如果未提供，则回答中会返回 base64 编码的图片字节。示例值：gs://image-bucket/output/。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict

请求 JSON 正文：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT"
    }
  ],
  "parameters": {
    "sampleCount": IMAGE_COUNT
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict" | Select-Object -Expand Content

以下示例响应适用于包含 "sampleCount": 2 的请求。响应返回两个预测对象，其中生成的图片字节采用 base64 编码。

{
  "predictions": [
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    }
  ]
}

如果您使用的是支持提示增强功能的模型，则回答中会包含一个额外的 prompt 字段，其中包含用于生成的增强型提示：

{
  "predictions": [
    {
      "mimeType": "MIME_TYPE",
      "prompt": "ENHANCED_PROMPT_1",
      "bytesBase64Encoded": "BASE64_IMG_BYTES_1"
    },
    {
      "mimeType": "MIME_TYPE",
      "prompt": "ENHANCED_PROMPT_2",
      "bytesBase64Encoded": "BASE64_IMG_BYTES_2"
    }
  ]
}

Python

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭证。 如需了解详情，请参阅为本地开发环境设置身份验证。

在此示例中，您将对 ImageGenerationModel（@006 版本）调用 generate_images 方法，并在本地保存生成的图片。然后，您可以选择使用笔记本中的 show() 方法显示生成的图片。如需详细了解模型版本和功能，请参阅模型版本。

import vertexai
from vertexai.preview.vision_models import ImageGenerationModel

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# output_file = "input-image.png"
# prompt = "" # The text prompt describing what you want to see.

vertexai.init(project=PROJECT_ID, location="us-central1")

model = ImageGenerationModel.from_pretrained("imagen-3.0-generate-002")

images = model.generate_images(
    prompt=prompt,
    # Optional parameters
    number_of_images=1,
    language="en",
    # You can't use a seed value and watermark at the same time.
    # add_watermark=False,
    # seed=100,
    aspect_ratio="1:1",
    safety_filter_level="block_some",
    person_generation="allow_adult",
)

images[0].save(location=output_file, include_generation_parameters=False)

# Optional. View the generated image in a notebook.
# images[0].show()

print(f"Created output image using {len(images[0]._image_bytes)} bytes")
# Example response:
# Created output image using 1234567 bytes

提高图片的分辨率

REST

在使用任何请求数据之前，请先进行以下替换：

• LOCATION：您的项目的区域。例如 us-central1、europe-west2 或 asia-northeast3。如需查看可用区域的列表，请参阅 Vertex AI 上的生成式 AI 位置。
• PROJECT_ID：您的 Google Cloud 项目 ID。
• B64_BASE_IMAGE：要修改或放大的基础图片。图片必须指定为 base64 编码的字节字符串。大小上限：10 MB。
• IMAGE_SOURCE：您要修改或放大的图片的 Cloud Storage 位置。例如：gs://output-bucket/source-photos/photo.png。
• UPSCALE_FACTOR：可选。图片的放大系数。如果未指定，系统将根据输入图片的较长边和 sampleImageSize 确定放大系数。可用值：x2 或 x4。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict

请求 JSON 正文：

{
  "instances": [
    {
      "prompt": "",
      "image": {
        // use one of the following to specify the image to upscale
        "bytesBase64Encoded": "B64_BASE_IMAGE"
        "gcsUri": "IMAGE_SOURCE"
        // end of base image input options
      },
    }
  ],
  "parameters": {
    "sampleCount": 1,
    "mode": "upscale",
    "upscaleConfig": {
      "upscaleFactor": "UPSCALE_FACTOR"
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "predictions": [
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "iVBOR..[base64-encoded-upscaled-image]...YII="
    }
  ]
}

后续步骤

• 如需了解详情，请参阅 Imagen on Vertex AI 概览和使用文本提示生成图片。