借助 Imagen API,您可以使用文本提示和参考图片来引导主题或风格的生成,从而创建高品质的图片。
查看 Imagen for Editing and Customization 模型卡片
本指南介绍了如何使用 Imagen API 模型自定义图片,并涵盖了以下主题:
- HTTP 方法和网址:了解图片自定义的 API 端点。
- 语法示例:查看用于自定义图片的 REST API 请求的结构。
- 选择参考图片类型:了解使用参考图片的不同方式。
- 参数列表:查看可用于自定义请求的参数。
- 示例:查看有关如何自定义图片的完整示例。
- 类别 ID:查找用于根据特定对象创建图片遮罩的类别 ID。
支持的型号
型号 | 代码 |
---|---|
使用参考图片进行自定义(少量样本) | imagen-3.0-capability-001 |
如需详细了解每个模型支持的功能,请参阅 Imagen 模型。
HTTP 方法和网址
POST https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/imagen-3.0-capability-001:predict
示例语法
以下示例展示了通过文本提示和参考图片自定义图片的语法。
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/imagen-3.0-capability-001:predict \ -d '{ "instances": [ { // Use [1] to refer to the reference images with referenceId=1 // [2] to refer to the reference images with referenceId=2, // following the same format for all reference IDs that you provide. "prompt": "${TEXT_PROMPT}", "referenceImages": [ // A list of at most 4 reference image objects. [...] ] } ], "parameters": { [...] } }'
请求正文示例:
此示例请求正文展示了一个人物自定义请求,其中使用了人脸网格控制图片和 3 张参考图片。
{ "instances": [ { "prompt": "Create an image about a man with short hair [1] in the pose of control image [2] to match the description: A pencil style sketch of a full-body portrait of a man with short hair [1] with hatch-cross drawing, hatch drawing of portrait with 6B and graphite pencils, white background, pencil drawing, high quality, pencil stroke, looking at camera, natural human eyes", "referenceImages": [ { "referenceType": "REFERENCE_TYPE_CONTROL", "referenceId": 2, "referenceImage": { "bytesBase64Encoded": "${IMAGE_BYTES_1}" }, "controlImageConfig": { "controlType": "CONTROL_TYPE_FACE_MESH", "enableControlImageComputation": true } }, { "referenceType": "REFERENCE_TYPE_SUBJECT", "referenceId": 1, "referenceImage": { "bytesBase64Encoded": "${IMAGE_BYTES_2}" }, "subjectImageConfig": { "subjectDescription": "a man with short hair", "subjectType": "SUBJECT_TYPE_PERSON" } }, { "referenceType": "REFERENCE_TYPE_SUBJECT", "referenceId": 1, "referenceImage": { "bytesBase64Encoded": "${IMAGE_BYTES_3}" }, "subjectImageConfig": { "subjectDescription": "a man with short hair", "subjectType": "SUBJECT_TYPE_PERSON" } }, { "referenceType": "REFERENCE_TYPE_SUBJECT", "referenceId": 1, "referenceImage": { "bytesBase64Encoded": "${IMAGE_BYTES_4}" }, "subjectImageConfig": { "subjectDescription": "a man with short hair", "subjectType": "SUBJECT_TYPE_PERSON" } } ] } ], "parameters": { "negativePrompt": "wrinkles, noise, Low quality, dirty, low res, multi face, rough texture, messy, messy background, color background, photo realistic, photo, super realistic, signature, autograph, sign, text, characters, alphabet, letter", "seed": 1, "language": "en", "sampleCount": 4 } }
选择参考图片类型
如需自定义图片,您需要提供一张或多张参考图片。每张参考图片都必须具有 referenceType
,用于指定模型应如何使用该图片。下表介绍了可用的参考类型。
参考类型 | 说明 | 使用场景 |
---|---|---|
REFERENCE_TYPE_SUBJECT |
提供要纳入生成的图片中的主题(例如人物、动物或商品)的图片。您可以为同一主题提供多张图片,以提高生成质量。 | 将特定人物或物体放置到新的场景或风格中。 |
REFERENCE_TYPE_STYLE |
提供一张图片,用于定义生成图片的艺术风格(例如水彩、素描、波普艺术)。 | 根据源样式图片,将一致的艺术风格应用于生成的图片。 |
REFERENCE_TYPE_CONTROL |
使用控制图片(如 Canny 边缘、涂鸦或人脸网格)来引导生成的图片的结构、姿势或构图。 | 控制角色或对象轮廓的确切姿势。 |
REFERENCE_TYPE_RAW |
提供用于编辑任务的基础映像。输出图片的尺寸与此原始图片相同。 | 修改现有图片,例如图像修复或扩绘。 |
REFERENCE_TYPE_MASK |
提供蒙版以指定原始图片的哪些部分应进行编辑(去除多余内容)或保留。蒙版可以是用户提供的,也可以是自动生成的。 | 修改图片的特定区域,同时保持其余部分不变。 |
参数列表
以下部分介绍了请求参数和响应字段。如需了解实现详情,请参阅示例。
请求参数
REST
参数 | |
---|---|
referenceType |
所需枚举:
|
referenceId |
参考图片的 ID。在提示中使用此 ID 来引用相应图片。例如,使用 |
referenceImage.bytesBase64Encoded |
参考图片的 Base64 编码字符串。 |
maskImageConfig.maskMode |
可选的枚举。 当
|
maskImageConfig.dilation |
可选 将此蒙版扩大的图像宽度的百分比。 当 |
maskImageConfig.maskClasses |
可选 为 当 |
controlImageConfig.controlType |
必需的枚举。 当
|
controlImageConfig.enableControlImageComputation |
可选 如果 |
language |
可选: 与文本提示语言对应的语言代码。 支持以下值:
|
subjectImageConfig.subjectDescription |
必需 图片中主题的简短说明。例如,一位留着棕色短发的女士。 当 |
subjectImageConfig.subjectType |
必需的枚举。 当
|
styleImageConfig.styleDescription |
可选 样式的简短说明。 当 |
响应正文
下表介绍了响应正文中的字段。
参数 | |
---|---|
predictions |
|
视觉生成模型结果对象
下表介绍了 VisionGenerativeModelResult
对象中的字段。
参数 | |
---|---|
bytesBase64Encoded |
base64 编码的生成图片。如果输出图片未通过 Responsible AI 的过滤机制,则不存在该字段。 |
mimeType |
生成的图片的 MIME 类型。如果输出图片未通过 Responsible AI 的过滤机制,则不存在该字段。 |
示例
以下示例展示了如何使用 Imagen 模型自定义图片。
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID。
- LOCATION:您的项目的区域。 例如
us-central1
、europe-west2
或asia-northeast3
。如需查看可用区域的列表,请参阅 Vertex AI 上的生成式 AI 位置。 - TEXT_PROMPT:文本提示可用于指导模型生成的图片。如需使用 Imagen 3 自定义,请以 [$referenceId] 格式添加您提供的参考图片的
referenceId
。例如:- 以下文本提示适用于包含两张包含
"referenceId": 1
的参考图片的请求。这两张图片都包含可选的"subjectDescription": "man with short hair"
说明: Create an image about a man with short hair to match the description: A pencil style sketch of a full-body portrait of a man with short hair [1] with hatch-cross drawing, hatch drawing of portrait with 6B and graphite pencils, white background, pencil drawing, high quality, pencil stroke, looking at camera, natural human eyes
- 以下文本提示适用于包含两张包含
"referenceId"
:参考图片的 ID,或与同一主体或风格对应的一系列参考图片的 ID。 在此示例中,这两张参考图片均为同一人,因此它们共享相同的referenceId
(1
)。- BASE64_REFERENCE_IMAGE:用于引导图片生成的参考图片。图片必须指定为 base64 编码的字节字符串。
- SUBJECT_DESCRIPTION:可选。您随后可以用于
prompt
字段的参考图片的文本说明。例如:"prompt": "a full-body portrait of a man with short hair [1] with hatch-cross drawing", [...], "subjectDescription": "man with short hair"
- IMAGE_COUNT:生成的图片数量。 接受的整数值:1-4。 默认值:4。
HTTP 方法和网址:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagen-3.0-capability-001:predict
请求 JSON 正文:
{ "instances": [ { "prompt": "TEXT_PROMPT", "referenceImages": [ { "referenceType": "REFERENCE_TYPE_SUBJECT", "referenceId": 1, "referenceImage": { "bytesBase64Encoded": "BASE64_REFERENCE_IMAGE" }, "subjectImageConfig": { "subjectDescription": "SUBJECT_DESCRIPTION", "subjectType": "SUBJECT_TYPE_PERSON" } }, { "referenceType": "REFERENCE_TYPE_SUBJECT", "referenceId": 1, "referenceImage": { "bytesBase64Encoded": "BASE64_REFERENCE_IMAGE" }, "subjectImageConfig": { "subjectDescription": "SUBJECT_DESCRIPTION", "subjectType": "SUBJECT_TYPE_PERSON" } } ] } ], "parameters": { "sampleCount": IMAGE_COUNT } }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 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/imagen-3.0-capability-001:predict"
PowerShell
将请求正文保存在名为 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/imagen-3.0-capability-001:predict" | Select-Object -Expand Content
"sampleCount": 2
的请求。响应返回两个预测对象,其中生成的图片字节采用 base64 编码。
{ "predictions": [ { "bytesBase64Encoded": "BASE64_IMG_BYTES", "mimeType": "image/png" }, { "mimeType": "image/png", "bytesBase64Encoded": "BASE64_IMG_BYTES" } ] }
类别 ID
使用以下对象类别 ID,根据特定对象自动创建图片遮罩。
类别 ID (class_ ) |
对象 |
---|---|
0 | 背包 |
1 | 雨伞 |
2 | 包 |
3 | 领带 |
4 | 手提箱 |
5 | 箱子 |
6 | 鸟 |
7 | 猫 |
8 | 狗 |
9 | 马 |
10 | 绵羊 |
11 | 奶牛 |
12 | 大象 |
13 | 熊 |
14 | 斑马 |
15 | 长颈鹿 |
16 | 动物(其他) |
17 | 微波炉 |
18 | 散热器 |
19 | 烤箱 |
20 | 吐司炉 |
21 | 存储箱 |
22 | 传送带 |
23 | 接收器 |
24 | 冰箱 |
25 | 洗衣机 |
26 | 风扇 |
27 | 洗碗机 |
28 | 卫生间 |
29 | 浴缸 |
30 | 淋浴喷头 |
31 | 隧道 |
32 | 桥 |
33 | 码头 |
34 | 帐篷 |
35 | 建筑物 |
36 | 天花板 |
37 | 笔记本电脑 |
38 | 键盘 |
39 | 鼠标 |
40 | 遥控器 |
41 | 手机 |
42 | 电视机 |
43 | 楼层 |
44 | 舞台 |
45 | 香蕉 |
46 | 苹果 |
47 | 三明治 |
48 | 橙色 |
49 | 西兰花 |
50 | carrot |
51 | 热狗 |
52 | 披萨 |
53 | 甜甜圈 |
54 | 蛋糕 |
55 | 水果(其他) |
56 | 食品(其他) |
57 | 椅子(其他) |
58 | 扶手椅 |
59 | 转椅 |
60 | 凳子 |
61 | 席位 |
62 | 长沙发 |
63 | 垃圾桶 |
64 | 盆栽植物 |
65 | 床头柜 |
66 | 床 |
67 | 表格 |
68 | 台球 |
69 | 桶 |
70 | 办公桌 |
71 | 软垫凳 |
72 | 衣柜 |
73 | 婴儿床 |
74 | 篮子 |
75 | 抽屉柜 |
76 | bookshelf |
77 | 柜台(其他) |
78 | 浴室柜 |
79 | 厨房岛台 |
80 | 门 |
81 | 灯具(其他) |
82 | 灯 |
83 | 壁灯台 |
84 | 枝形吊灯 |
85 | 镜子 |
86 | 白板 |
87 | 架子 |
88 | 楼梯 |
89 | 自动扶梯 |
90 | 柜子 |
91 | 壁炉 |
92 | 火炉 |
93 | 街机 |
94 | 碎石 |
95 | 平台 |
96 | 运动场 |
97 | 铁路 |
98 | 道路 |
99 | 雪 |
100 | 人行道 |
101 | 跑道 |
102 | 地形 |
103 | 书 |
104 | 盒子 |
105 | 时钟 |
106 | 花瓶 |
107 | 剪刀 |
108 | 玩具(其他) |
109 | 泰迪熊 |
110 | 吹风机 |
111 | 牙刷 |
112 | 绘画 |
113 | 海报 |
114 | 布告栏 |
115 | 瓶子 |
116 | 茶杯 |
117 | 葡萄酒杯 |
118 | 刀 |
119 | 叉子 |
120 | 勺子 |
121 | 碗 |
122 | 托盘 |
123 | 油烟机 |
124 | 盘子 |
125 | 人 |
126 | 骑乘人员(其他) |
127 | 骑自行车的人 |
128 | 摩托车手 |
129 | 纸张 |
130 | 路灯 |
131 | 路障 |
132 | 邮箱 |
133 | 闭路电视摄像头 |
134 | 接线盒 |
135 | 交通标志 |
136 | 红绿灯 |
137 | 消防栓 |
138 | 停车计时器 |
139 | 长椅 |
140 | 自行车架 |
141 | 广告牌 |
142 | 天空 |
143 | 杆 |
144 | 篱笆 |
145 | 栏杆 |
146 | 护栏 |
147 | 山丘 |
148 | 岩石 |
149 | 飞盘 |
150 | 双板滑雪板 |
151 | 滑雪板 |
152 | 运动球类 |
153 | 风筝 |
154 | 棒球棍 |
155 | 棒球手套 |
156 | 滑板 |
157 | 冲浪板 |
158 | 网球拍 |
159 | 网 |
160 | 底座 |
161 | 雕塑 |
162 | 列 |
163 | 喷泉 |
164 | 遮篷 |
165 | 服饰 |
166 | 横幅 |
167 | 旗帜 |
168 | 毯子 |
169 | 窗帘(其他) |
170 | 浴帘 |
171 | pillow |
172 | 毛巾 |
173 | 地毯 |
174 | 植被 |
175 | 自行车 |
176 | 汽车 |
177 | 三轮车 |
178 | 摩托车 |
179 | 飞机 |
180 | 公交车 |
181 | 火车 |
182 | 卡车 |
183 | 拖车 |
184 | 船只 |
185 | 慢速物体 |
186 | 河湖 |
187 | 大海 |
188 | 水体(其他) |
189 | 游泳池 |
190 | 瀑布 |
191 | 墙 |
192 | 窗户 |
193 | 百叶窗 |
后续步骤
- 如需了解详情,请参阅 Imagen on Vertex AI。