圖像生成 API

Imagen API 可讓你使用文字提示引導生成作業，在幾秒內生成高品質圖片。

查看 Imagen for Generation 模型資訊卡

支援的模型版本

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

如要進一步瞭解各模型支援的功能，請參閱 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

參數
addWatermark

bool

(選用步驟) 在生成的圖片中加入隱形浮水印。

預設值為 true。

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

(選用步驟) 描述要避免在生成圖片中出現的內容。

negativePrompt 不支援 imagen-3.0-generate-002 和更新型號。
outputOptions

outputOptions

(選用步驟) 說明 outputOptions 物件中的輸出圖片格式。

prompt

string

這是必要旗標，圖片的文字提示。
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 各有一個。如果負責任的 AI 篩選掉任何圖片，系統就不會納入這些圖片，除非 includeRaiReason 設為 true。

Vision 生成模型結果物件

模型結果的相關資訊。

參數
bytesBase64Encoded

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

生成的圖像類型。如果輸出圖片未通過負責任的 AI 篩選器，就不會顯示這項資訊。
raiFilteredReason

負責任的 AI 技術篩選器原因。只有在啟用 includeRaiReason 且系統已濾除這張圖片時，才會傳回這項屬性。
safetyAttributes.categories

安全屬性名稱。只有在啟用 includeSafetyAttributes，且輸出圖片通過負責任的 AI 篩選器時，才會傳回這項資訊。
safetyAttributes.scores

安全屬性分數。只有在啟用 includeSafetyAttributes，且輸出圖片通過負責任的 AI 篩選器時，才會傳回這項資訊。

Python

參數
add_watermark

bool

(選用步驟) 為生成的圖片加上浮水印。

預設值為 true。

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

(選用步驟) 描述要避免在生成圖片中出現的內容。

negative_prompt 不支援 imagen-3.0-generate-002 和更新型號。
number_of_images

int

這是必要旗標，要生成的圖片數量。預設值為 1。

output_gcs_uri

string

(選用步驟) 儲存生成圖片的 Cloud Storage URI。
output_mime_type

string

(選用步驟) 輸出內容應儲存的圖片格式。支援的值如下：

  • "image/png"：另存為 PNG 圖片
  • "image/jpeg"：儲存為 JPEG 圖片

預設值為 "image/png"。
prompt

string

這是必要旗標，圖片的文字提示。
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 會產生新的提示，導致產生新的或不同的圖片。

範例

下列範例說明如何使用 Imagen 模型生成圖片。

生成圖像

REST

使用任何要求資料之前，請先替換以下項目：

  • REGION：專案所在的區域。如要進一步瞭解支援的區域，請參閱「Vertex AI 的生成式 AI 服務地區」。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

  • MODEL_VERSION：要使用的 Imagen 模型版本。如要進一步瞭解可用模型，請參閱「Imagen 模型」。

  • TEXT_PROMPT：文字提示，引導模型生成圖片。生成和編輯時都必須填寫這個欄位。
  • IMAGE_COUNT：要生成的圖片數量。可接受的值範圍為 1 至 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，可用於驗證含有浮水印的圖片。如果省略這個欄位，系統會使用預設值 true；如要停用這項功能，請將值設為 false。只有在將這個欄位設為 false 時，才能使用 seed 欄位取得確定性輸出內容。
    • ASPECT_RATIO：字串。(選用步驟) 控制長寬比的生成模式參數。支援的比例值及其用途：
      • 1:1 (預設，正方形)
      • 3:4 (廣告、社群媒體)
      • 4:3 (電視、攝影)
      • 16:9 (橫向)
      • 9:16 (直向)
    • ENABLE_PROMPT_REWRITING：布林值。(選用步驟) 這項參數可使用以 LLM 為基礎的提示重寫功能，提供更能反映原始提示意圖的高畫質圖像。停用這項功能可能會影響影像品質和提示遵循率。預設值為 true。
    • INCLUDE_RAI_REASON：布林值。(選用步驟) 是否要在輸入或輸出內容遭到封鎖的回覆中，啟用「負責任的 AI 技術篩選理由」代碼。預設值： true。
    • INCLUDE_SAFETY_ATTRIBUTES：布林值。(選用步驟) 是否要在未經過濾的輸入內容和輸出內容的回覆中，啟用一系列安全屬性的四捨五入負責任 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 bucket。如果未提供，回應中會傳回 base64 編碼的圖片位元組。範例值： gs://image-bucket/output/。

HTTP 方法和網址：

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

JSON 要求內文：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT"
    }
  ],
  "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://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_VERSION: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://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/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

後續步驟