自定义图片

借助 Imagen API,您可以使用文本提示和参考图片来引导主题或风格的生成,从而创建高品质的图片。

查看 Imagen for Editing and Customization 模型卡片

本指南介绍了如何使用 Imagen API 模型自定义图片,并涵盖了以下主题:

支持的型号

型号 代码
使用参考图片进行自定义(少量样本) 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

所需枚举:

  • REFERENCE_TYPE_RAW
    • 修改应用场景时必需。
    • 每个请求最多允许一张原始参考图片。
    • 输出图片的尺寸与原始参考图片相同。
  • REFERENCE_TYPE_MASK
    • 蒙版修改必需。
    • 如果提供了原始参考图片,则必须与原始参考图片的尺寸相同。
    • 您可以提供自己的遮罩,也可以让系统根据参考图片生成遮罩。
    • 如果遮罩图片为空,并且 maskMode 不为 MASK_MODE_USER_PROVIDED,则系统会根据原始参考图片计算遮罩。
  • REFERENCE_TYPE_CONTROL
    • 如果提供了原始参考图片,则必须与原始参考图片的尺寸相同。
    • 如果控制图片为空,并且 enableControlImageComputationtrue,则系统会根据原始参考图片计算控制图片。
  • REFERENCE_TYPE_SUBJECT
    • 您可以提供多个具有相同 referenceId 的参考图片,以提高输出质量。
  • REFERENCE_TYPE_STYLE
referenceId

integer 为必需项

参考图片的 ID。在提示中使用此 ID 来引用相应图片。例如,使用 [1] 引用具有 referenceId=1 的图片,使用 [2] 引用具有 referenceId=2 的图片。

referenceImage.bytesBase64Encoded

string 为必需项

参考图片的 Base64 编码字符串。

maskImageConfig.maskMode

可选的枚举。

referenceTypeREFERENCE_TYPE_MASK 时,请使用此参数。

  • MASK_MODE_USER_PROVIDED:如果参考图片是遮罩图片。
  • MASK_MODE_BACKGROUND:使用背景分割自动生成蒙版。
  • MASK_MODE_FOREGROUND:使用前景分割自动生成蒙版。
  • MASK_MODE_SEMANTIC:使用语义分割和给定的遮罩类别自动生成遮罩。
maskImageConfig.dilation

可选 float。范围:[0, 1]

将此蒙版扩大的图像宽度的百分比。

referenceTypeREFERENCE_TYPE_MASK 时,请使用此参数。

maskImageConfig.maskClasses

可选 list[Integer]

MASK_MODE_SEMANTIC 模式遮盖类别

referenceTypeREFERENCE_TYPE_MASK 时,请使用此参数。

controlImageConfig.controlType

必需的枚举。

referenceTypeREFERENCE_TYPE_CONTROL 时,请使用此参数。

  • CONTROL_TYPE_FACE_MESH 用于面部网格(人物自定义)。
  • CONTROL_TYPE_CANNY 表示 Canny 边缘
  • CONTROL_TYPE_SCRIBBLE(针对涂写)。
controlImageConfig.enableControlImageComputation

可选 bool。默认值:false

如果 referenceTypeREFERENCE_TYPE_CONTROL,请将此参数设置为 true,以便让 Imagen 从参考图片计算控制图片。否则,请设置为 false 并提供您自己的控制图片。

language

可选:string(仅限 imagen-3.0-capability-001imagen-3.0.generate-001imagegeneration@006

与文本提示语言对应的语言代码。 支持以下值:

  • auto:自动检测。如果 Imagen 检测到受支持的语言,则提示和可选的否定提示会翻译为英语。如果检测到的语言不受支持,Imagen 会逐字使用输入文本,这可能会导致意外输出。系统不会返回错误代码。
  • en:英语(如果省略,则为默认值)
  • es:西班牙语
  • hi:印地语
  • ja:日语
  • ko:韩语
  • pt:葡萄牙语
  • zh-TW:中文(繁体)
  • zhzh-CN:中文(简体)
subjectImageConfig.subjectDescription

必需 string

图片中主题的简短说明。例如,一位留着棕色短发的女士

referenceTypeREFERENCE_TYPE_SUBJECT 时,请使用此参数。

subjectImageConfig.subjectType

必需的枚举。

referenceTypeREFERENCE_TYPE_SUBJECT 时,请使用此参数。

  • SUBJECT_TYPE_PERSON:人物主题类型。
  • SUBJECT_TYPE_ANIMAL:动物主题类型。
  • SUBJECT_TYPE_PRODUCT:产品主题类型。
  • SUBJECT_TYPE_DEFAULT:默认主题类型。
styleImageConfig.styleDescription

可选 string

样式的简短说明。

referenceTypeREFERENCE_TYPE_STYLE 时,请使用此参数。

响应正文

下表介绍了响应正文中的字段。

参数
predictions

VisionGenerativeModelResult 对象的数组,每个对象对应一个请求的 sampleCount。如果有任何图片被 Responsible AI 过滤掉,则不包括这些图片。

视觉生成模型结果对象

下表介绍了 VisionGenerativeModelResult 对象中的字段。

参数
bytesBase64Encoded

base64 编码的生成图片。如果输出图片未通过 Responsible AI 的过滤机制,则不存在该字段。

mimeType

生成的图片的 MIME 类型。如果输出图片未通过 Responsible AI 的过滤机制,则不存在该字段。

示例

以下示例展示了如何使用 Imagen 模型自定义图片。

REST

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

  • PROJECT_ID:您的 Google Cloud 项目 ID
  • LOCATION:您的项目的区域。 例如 us-central1europe-west2asia-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_id) 对象
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 百叶窗

后续步骤