Imagen API 使用文本提示来引导生成过程,可让您在几秒钟内创建高品质图片。您还可以使用 Imagen API 放大图片。
支持的模型
模型 | 代码 |
---|---|
图片生成 | imagen-3.0-generate-002 imagen-3.0-generate-001 imagen-3.0-fast-generate-001 imagegeneration@006 imagegeneration@005 imagegeneration@002 |
如需详细了解每个模型支持的功能,请参阅模型版本控制。
示例语法
用于通过文本提示创建图片的语法。
语法
用于生成图片的语法。
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":... } }'
generation_model = ImageGenerationModel.from_pretrained("imagen-3.0-generate-001") response = generation_model.generate_images( prompt="... ", negative_prompt="... ", aspect_ratio=... , ) response.images[0].show()
参数列表
如需了解实现详情,请参阅示例。
生成图片
参数 | |
---|---|
prompt |
必需: 图片的文本提示。
|
sampleCount |
必需: 要生成的图片数量。默认值为 4。
|
seed |
可选: 用于生成图片的随机种子。当 如果 |
enhancePrompt |
可选: 一个可选参数,用于使用基于 LLM 的提示重写功能来提供更高质量的图片,以便更好地反映原始提示的意图。停用此功能可能会影响图片质量和提示遵循度。
|
negativePrompt |
可选: 用于说明在生成的图片中不建议的内容。
|
aspectRatio |
可选: 图片的宽高比。默认值为“1:1”。
|
outputOptions |
可选: 在 |
sampleImageStyle |
可选: 描述生成的图片的风格。支持以下值:
|
personGeneration |
可选: 允许模型生成人物。支持以下值:
默认值为 |
safetySetting |
可选: 为安全性过滤策略添加过滤级别。支持以下值:
默认值为 |
addWatermark |
可选: 向生成的图片添加不可见水印。 |
storageUri |
可选: 用于存储生成的图片的 Cloud Storage URI。 |
输出选项对象
outputOptions
对象描述图片输出。
参数 | |
---|---|
outputOptions.mimeType |
可选: 输出应另存为的图片格式。支持以下值:
默认值为 |
outputOptions.compressionQuality |
可选: 如果输出类型为 |
响应
REST 请求的响应正文。
参数 | |
---|---|
predictions |
|
视觉生成模型结果对象
模型结果的相关信息。
参数 | |
---|---|
bytesBase64Encoded |
base64 编码的生成图片。如果输出图片未通过 Responsible AI 的过滤机制,则不存在该参数。 |
mimeType |
生成的图片的类型。如果输出图片未通过 Responsible AI 的过滤机制,则不存在该参数。 |
raiFilteredReason |
Responsible AI 过滤原因。仅在启用了 |
safetyAttributes.categories |
安全性属性的名称。仅在启用了 |
safetyAttributes.scores |
安全性属性的得分。仅在启用了 |
参数 | |
---|---|
prompt |
必需: 图片的文本提示。
|
number_of_images |
必需: 要生成的图片数量。默认值为 1。
|
seed |
可选: 用于生成图片的随机种子。当 如果 |
negative_prompt |
可选: 用于说明在生成的图片中不建议的内容。
|
aspect_ratio |
可选: 图片的宽高比。默认值为“1:1”。
|
output_mime_type |
可选: 输出应另存为的图片格式。支持以下值:
默认值为 |
compression_quality |
可选: 如果输出 MIME 类型为 |
language |
可选: 图片的文本提示采用的语言。支持以下值:
默认值为 |
output_gcs_uri |
可选: 用于存储生成的图片的 Cloud Storage URI。 |
add_watermark |
可选: 为生成的图片添加水印。 |
safety_filter_level |
可选: 为安全性过滤策略添加过滤级别。支持以下值:
默认值为 |
person_generation |
可选: 允许模型生成人物。支持以下值:
默认值为 |
提高图片的分辨率
参数 | |
---|---|
mode |
必需: 对于分辨率提升请求,必须设置为 |
upscaleConfig |
必需: |
outputOptions |
可选: 在 |
storageUri |
可选: 用于存储生成的图片的 Cloud Storage URI。 |
分辨率提升配置对象
参数 | |
---|---|
upscaleConfig.upscaleFactor |
必需: 分辨率提升系数。支持的值为 |
响应
REST 请求的响应正文。
参数 | |
---|---|
predictions |
|
示例
以下示例展示了如何使用 Imagen 模型生成图片。
生成图片
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- MODEL_VERSION:要使用的
imagegeneration
模型版本。可用的值:-
Imagen 3:
imagen-3.0-generate-002
(最新模型)imagen-3.0-generate-001
imagen-3.0-fast-generate-001
- 低延迟模型版本。
-
默认模型版本:
imagegeneration
- 使用默认模型版本 v.006。最佳实践是应始终指定模型版本,尤其是在生产环境中。
如需详细了解模型版本和功能,请参阅模型版本。
-
Imagen 3:
- LOCATION:您的项目的区域。 例如
us-central1
、europe-west2
或asia-northeast3
。如需查看可用区域的列表,请参阅 Vertex AI 上的生成式 AI 位置。 - TEXT_PROMPT:用于指导模型生成什么图片的文本提示。生成和修改都需要此字段。
- IMAGE_COUNT:生成的图片数量。
接受的整数值:1-8 (
imagegeneration@002
)、1-4(所有其他模型版本)。 默认值:4。 - ADD_WATERMARK:布尔值。可选。是否为生成的图片启用水印。
将该字段设置为
true
时生成的任何图片都包含数字 SynthID,您可以使用该数字 SynthID 来验证带水印的图片。如果您省略此字段,则系统会使用默认值true
;您必须将其值设置为false
才能停用此功能。仅当此字段设置为false
时,您才可以使用seed
字段来获取确定性输出。 - ASPECT_RATIO:字符串。可选。用于控制宽高比的生成模式参数。支持的宽高比值及其预期用途:
1:1
(默认,方形)3:4
(广告、社交媒体)4:3
(电视、摄影)16:9
(横向)9:16
(纵向)
- ENABLE_PROMPT_REWRITING:布尔值。可选。一个参数,用于使用基于 LLM 的提示重写功能来提供更高质量的图片,以便更好地反映原始提示的意图。停用此功能可能会影响图片质量和提示遵循度。默认值:
true
。 - INCLUDE_RAI_REASON:布尔值。可选。是否在输入或输出被屏蔽的回答中启用 Responsible AI 过滤的原因代码。默认值:
false
。 - 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/
。
其他可选参数
根据您的应用场景,使用以下可选变量。在 "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 " }
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 } }
如需发送请求,请选择以下方式之一:
将请求正文保存在名为 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"
将请求正文保存在名为 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 " } ] }
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Python 设置说明执行操作。 如需了解详情,请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
在此示例中,您将对 ImageGenerationModel
(@006
版本)调用 generate_images
方法,并在本地保存生成的图片。然后,您可以选择使用笔记本中的 show()
方法显示生成的图片。如需详细了解模型版本和功能,请参阅模型版本。
提高图片的分辨率
在使用任何请求数据之前,请先进行以下替换:
- 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 " } } }
如需发送请求,请选择以下方式之一:
将请求正文保存在名为 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"
将请求正文保存在名为 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 概览和使用文本提示生成图片。