自訂圖片

Imagen API 可讓您在幾秒內生成高品質圖像，並使用文字提示和參考圖像引導主題或風格生成。

查看「Imagen for Editing and Customization」模型資訊卡

支援的機型

模型 程式碼
使用參考圖片自訂 (少量樣本) 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": {
        [...]
    }
}'

要求主體範例：

這項要求是使用臉部網格控制圖片和三張參考圖片，進行個人化設定。

{
  "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
  }
}

參數清單

如需實作詳情，請參閱範例。

自訂圖片

REST

參數
referenceType 必要列舉：
  • REFERENCE_TYPE_RAW
    • 編輯用途必須提供原始參照圖片。
    • 其他用途則不需要原始參考圖像。
    • 一項要求最多只能有一個原始參照圖片。
    • 輸出圖片的大小與原始參考輸入圖片相同。
  • REFERENCE_TYPE_MASK
    • 如要使用遮罩編輯功能，必須提供遮罩參照圖片。
    • 其他用途則不需要遮罩參考圖像。
    • 如有原始參考圖片，遮罩圖片的大小必須與原始參考圖片相同。
    • 使用者可以提供自己的遮罩，也可以讓 Imagen 從提供的參考圖片計算遮罩。
    • 如果遮罩參照圖片為空白，且 maskMode 未設為 MASK_MODE_USER_PROVIDED，系統會根據原始參照圖片計算遮罩。
  • REFERENCE_TYPE_CONTROL
    • 如果提供原始參考圖片，則控制圖片的尺寸必須與原始參考圖片相同。
    • 如果未以 `bytesBase64Encoded` 格式提供 `REFERENCE_TYPE_CONTROL` 類型的圖片，模型會根據以 `REFERENCE_TYPE_RAW` 格式提供的圖片計算控制圖片。
  • REFERENCE_TYPE_SUBJECT
    • 使用者可以提供多張參考圖像，但必須使用相同的參考 ID。舉例來說，同一主題的多張圖片可以有相同的參照 ID。這或許能提升輸出內容品質。
  • REFERENCE_TYPE_STYLE
    • 模型會使用樣式參考圖像，引導生成圖像的樣式。
referenceId 必要integer

參考 ID。在提示中使用這個參照 ID。舉例來說，使用 [1] 參照 referenceId=1 的參考圖片，使用 [2] 參照 referenceId=2 的參考圖片。
referenceImage.bytesBase64Encoded 必要 string

編碼參考圖片的 Base64 字串。
maskImageConfig.maskMode 選用列舉：
  • MASK_MODE_USER_PROVIDED (如果參考圖片是遮罩圖片)。
  • MASK_MODE_BACKGROUND，系統就會使用背景區隔功能自動生成遮罩。
  • MASK_MODE_FOREGROUND，系統就會使用前景分割功能自動生成遮罩。
  • ，使用語意區隔自動生成遮罩，以及指定的遮罩類別。MASK_MODE_SEMANTIC

當 referenceType 設為 REFERENCE_TYPE_MASK 時，必須指定此值。
maskImageConfig.dilation
 選填 float。範圍：[0, 1]

用來擴大這個遮罩的圖片寬度百分比。

當 referenceType 設為 REFERENCE_TYPE_MASK 時，必須指定此值。
maskImageConfig.maskClasses
 選填 list[Integer]。

MASK_MODE_SEMANTIC 模式的遮罩類別。

當 referenceType 設為 REFERENCE_TYPE_MASK 時，必須指定此值。
controlImageConfig.controlType
 必要列舉：
  • CONTROL_TYPE_FACE_MESH，用於臉部網格 (個人化)。
  • CONTROL_TYPE_CANNY，適用於Canny 邊緣。
  • CONTROL_TYPE_SCRIBBLE即可手寫。

當 referenceType 設為 REFERENCE_TYPE_CONTROL 時，必須指定此值。
controlImageConfig.enableControlImageComputation
 選填 bool。
預設值：false。

  • 如果您提供自己的控制項圖片，請設為 false。
  • 如要讓 Imagen 從參照圖片計算控制圖片，請設為 true。

當 referenceType 設為 REFERENCE_TYPE_CONTROL 時，必須指定此值。
language

選用：string (僅限 imagen-3.0-capability-001、imagen-3.0.generate-001 和 imagegeneration@006)

與文字提示語言對應的語言代碼。 支援的值如下：

  • auto：自動偵測。如果 Imagen 偵測到支援的語言，系統會將提示和選填的負面提示翻譯成英文。如果系統偵測到的語言不支援，Imagen 會直接使用輸入文字，這可能會導致輸出結果不符預期。未傳回錯誤代碼。
    • en：英文 (如省略，則為預設值)
  • es：西班牙文
  • hi：北印度文
  • ja：日文
  • ko：韓文
  • pt：葡萄牙文
  • zh-TW：中文 (繁體)
  • zh 或 zh-CN：中文 (簡體)
subjectImageConfig.subjectDescription
 必要 string。

圖片中主體的簡短說明。例如短棕髮女子。

當 referenceType 設為 REFERENCE_TYPE_SUBJECT 時，必須指定此值。
subjectImageConfig.subjectType
 必要列舉：
  • SUBJECT_TYPE_PERSON：人員主體類型。
  • SUBJECT_TYPE_ANIMAL：動物主題類型。
  • SUBJECT_TYPE_PRODUCT：產品主題類型。
  • SUBJECT_TYPE_DEFAULT：預設主體類型。

當 referenceType 設為 REFERENCE_TYPE_SUBJECT 時，必須指定此值。
styleImageConfig.styleDescription
 選填 string。
樣式的簡短說明。

當 referenceType 設為 REFERENCE_TYPE_STYLE 時，必須指定此值。

回應

REST 要求的回應主體。

參數
predictions

VisionGenerativeModelResult 物件陣列，每個要求的 sampleCount 各有一個物件。如果圖片遭到負責任的 AI 技術篩除，就不會納入其中。

Vision 生成模型結果物件

模型結果的相關資訊。

參數
bytesBase64Encoded

以 Base64 編碼的生成圖片。如果輸出圖片未通過負責任的 AI 篩選器，就不會顯示這項資訊。
mimeType

生成的圖像類型。如果輸出圖片未通過負責任的 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"說明：根據說明製作圖片：以鉛筆風格繪製全身肖像，man with short hair [1]採用交叉陰影繪圖，以 6B 和石墨鉛筆繪製肖像陰影，白色背景，鉛筆繪圖，高品質，鉛筆筆觸，看著鏡頭，自然的人眼
  • "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 cat
8 狗
9 馬
10 綿羊
11 母牛
12 大象
13 熊
14 斑馬
15 長頸鹿
16 動物 (其他)
17 微波爐
18 散熱器
19 烤箱
20 烤麵包機
21 儲存槽
22 輸送帶
23 接收器
24 冰箱
25 洗衣烘乾機
26 風扇
27 洗碗機
28 馬桶
29 浴缸
30 shower (蓮蓬頭)
31 通道
32 橋梁
33 碼頭
34 帳篷
35 建構中
36 ceiling
37 筆記型電腦
38 鍵盤
39 老鼠
40 遠端
41 手機
42 電視機
43 floor
44 在此流程的各個階段
45 香蕉
46 apple
47 三明治
48 orange
49 花椰菜
50 紅蘿蔔
51 熱狗
52 披薩
53 甜甜圈
54 蛋糕
55 水果 (其他)
56 食物 (其他)
57 椅子 (其他)
58 扶手椅
59 旋轉椅
60 凳子
61 帳戶名額
62 沙發
63 垃圾桶
64 盆栽
65 nightstand (床頭櫃)
66 床
67 資料表
68 撞球桌
69 槍管
70 辦公桌
71 腳凳
72 衣櫃
73 嬰兒床
74 籃子
75 抽屜櫃
76 書架
77 計數器 (其他)
78 浴室檯面
79 廚房中島
80 門
81 光線 (其他)
82 燈具
83 壁燈
84 吊燈
85 鏡像
86 透過行動裝置在 Meet 設備裝置上
87 專區
88 樓梯
89 電扶梯
90 櫃子
91 壁爐
92 火爐
93 大型電玩機台
94 砂礫
95 platform
96 playingfield
97 鐵路
98 道路
99 snow
100 人行道鋪面
101 跑道
102 地形
103 書
104 box
105 時鐘
106 花瓶
107 剪刀
108 玩具 (其他)
109 泰迪熊
110 吹風機
111 牙刷
112 繪畫
113 海報
114 公布欄
115 瓶子
116 杯子
117 葡萄酒杯
118 刀子
119 分支
120 湯匙
121 碗
122 托盤
123 抽油煙機
124 盤子
125 使用者圖示
126 rider (other)
127 自行車騎士
128 機車騎士
129 報告
130 路燈
131 路障
132 信箱
133 監視器
134 接線盒
135 交通號誌
136 紅綠燈
137 消防栓
138 停車收費計時器
139 長椅
140 自行車架
141 看板
142 Sky
143 桿子
144 籬笆
145 欄杆扶手
146 護欄
147 山丘
148 搖滾
149 飛盤
150 滑雪板
151 滑雪板
152 運動用球
153 風箏
154 球棒
155 棒球手套
156 滑板
157 衝浪板
158 網球拍
159 淨
160 base
161 雕塑
162 欄
163 噴泉
164 遮篷
165 服飾
166 橫幅
167 旗標
168 毯子
169 窗簾 (其他)
170 浴簾
171 pillow
172 毛巾
173 地毯地墊
174 植被
175 腳踏車
176 汽車
177 autorickshaw
178 摩托車
179 飛機
180 公車
181 火車
182 卡車
183 預告片
184 船隻
185 緩慢移動的輪狀物體
186 河湖
187 海洋
188 水 (其他)
189 游泳池
190 瀑布
191 牆
192 window
193 百葉窗簾

後續步驟