圖像生成 API

Imagen 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
  • imagegeneration@006
  • imagegeneration@005
  • imagegeneration@002

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

參數
prompt

string

這是必要旗標，圖片的文字提示。
addWatermark

bool

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

預設值為 true，但下列機型除外：

  • imagegeneration@002
  • imagegeneration@005
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 物件中的輸出圖片格式。

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

參數
prompt

string

這是必要旗標，圖片的文字提示。
add_watermark

bool

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

預設值為 true，但下列機型除外：

  • imagegeneration@002
  • imagegeneration@005
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"。
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 會產生新的提示，導致產生新的或不同的圖片。

提高圖片解析度

REST

參數
mode

string

這是必要旗標，必須設為 "upscale"，才能提出升級要求。
upscaleConfig

UpscaleConfig

這是必要旗標，UpscaleConfig 物件。

outputOptions

OutputOptions

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

storageUri

string

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

升級設定物件

參數
upscaleConfig.upscaleFactor

string

這是必要旗標，升頻係數。支援的值為 "x2" 和 "x4"。

回應

REST 要求的回應主體。

參數
predictions VisionGenerativeModelResult 物件陣列，每個要求的 sampleCount 各有一個。如果圖片遭到負責任的 AI 篩除，就不會納入其中，除非 includeRaiReason 設為 true。

範例

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

生成圖像

REST

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

  • PROJECT_ID：您的 Google Cloud 專案 ID。

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

  • LOCATION：專案的區域。例如 us-central1、europe-west2 或 asia-northeast3。如需可用區域的清單，請參閱「Vertex AI 的生成式 AI 服務地區」。
  • TEXT_PROMPT：文字提示，引導模型生成圖片。生成和編輯時都必須填寫這個欄位。
  • IMAGE_COUNT：生成的圖像數量。 可接受的整數值：1 到 8 (imagegeneration@002)，1 到 4 (所有其他模型版本)。 預設值為 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://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
  }
}

如要傳送要求，請選擇以下其中一個選項：

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/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://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"
    }
  ]
}

Python

在試用這個範例之前，請先按照Python使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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

提高圖片解析度

REST

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

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

如要傳送要求，請選擇以下其中一個選項：

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/imagegeneration@002: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/imagegeneration@002:predict" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "predictions": [
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "iVBOR..[base64-encoded-upscaled-image]...YII="
    }
  ]
}

後續步驟

上一頁
使用文字提示來生成圖像