使用修復功能在圖片中插入物件

注意：下表說明已淘汰的圖像生成端點及其替代項目。建議您在 2026 年 6 月 30 日前更新模型端點，以免服務中斷。

已停用的端點	建議的端點遷移方式
imagegeneration@002	gemini-2.5-flash-image
imagegeneration@003	gemini-2.5-flash-image
imagegeneration@004	gemini-2.5-flash-image
imagegeneration@005	gemini-2.5-flash-image
imagegeneration@006	gemini-2.5-flash-image
imagetext@001	gemini-2.5-flash-image
imagen-3.0-capability-001	gemini-2.5-flash-image
imagen-3.0-capability-002	gemini-2.5-flash-image
imagen-3.0-fast-generate-001	gemini-2.5-flash-image
imagen-3.0-generate-001	gemini-2.5-flash-image
imagen-3.0-generate-002	gemini-2.5-flash-image
imagen-4.0-fast-generate-001	gemini-2.5-flash-image
imagen-4.0-generate-001	gemini-2.5-flash-image
imagen-4.0-ultra-generate-001	gemini-2.5-flash-image

本頁說明如何將物件插入圖片，這個程序也稱為「修復」。在 Vertex AI 中使用 Imagen 時，您可以指定遮罩區域，將物件插入圖片。你可以自備遮罩，也可以讓 Imagen 為你生成遮罩。

下列模型支援在圖片中插入物件：

• imagen-3.0-capability-001

內容插入範例

如要查看 Imagen 3 編輯功能的範例，請在下列任一環境中執行「Imagen 3 Image Editing」筆記本：

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Vertex AI Workbench 中開啟 | 在 GitHub 上查看

使用修復功能時，您可以運用基礎圖片、圖片遮罩和文字提示，在現有圖片中加入內容。

輸入內容

要編輯的基本圖片^*	使用 Google Cloud 控制台中的工具遮蓋指定區域	文字提示
		草莓

^{* 圖片來源：Alex Lvrs (Unsplash)。}

在 Google Cloud 控制台中指定遮罩區域後的輸出內容

查看 Imagen 編輯與自訂模型資訊卡

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，能用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. 為環境設定驗證機制。

   請根據您打算如何使用本頁範例，選取對應的分頁標籤：

   控制台

   使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，不需要設定驗證。

   REST

   如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

   安裝 Google Cloud CLI。

   如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

   詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。

插入時定義遮罩區域

請使用下列範例，透過 Imagen 3 模型傳送修復要求。

控制台

1. 在 Google Cloud 控制台中，依序前往「Vertex AI」 >「Vertex AI Studio」 頁面。

   前往 Vertex AI Studio

2. 按一下「生成媒體」。

3. 按一下「圖片」。

4. 從「Task」(工作) 清單中選取「Inpaint-add」(修復 - 新增)。

5. 從「模型」清單中，選取要使用的 Imagen 模型。

6. 在「輸入圖片」中，按一下「新增」，然後選取要編輯的圖片以上傳。

7. 在「提示」方塊中輸入提示詞，說明如何編輯圖片。

8. 請執行下列任一操作來指定遮罩：

   • 上傳自己的遮罩：
     1. 在電腦上建立遮罩。
     2. 按一下「上傳」 「匯入遮罩」，然後選取要上傳的遮罩。
   • 定義遮罩：在編輯工具列中，使用遮罩工具 (方塊、筆刷、masked_transitions、反轉 工具) 指定要新增內容的區域。

9. 按一下「執行」。

REST

如要進一步瞭解 Imagen API，請參閱下列資源：

• 方法： endpoints.predict
• VisionGenerativeModelInstance
• VisionGenerativeModelParams
• VisionGenerativeModelResult

使用任何要求資料之前，請先修改下列項目的值：

• REGION：專案所在的區域。如要進一步瞭解支援的地區，請參閱「Vertex AI 的生成式 AI 服務地區」。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• TEXT_PROMPT： 選用。文字提示詞，用於引導模型生成圖像。為獲得最佳效果，請使用遮蓋區域的說明，並避免使用單字提示。例如，使用「一隻可愛的柯基犬」而非「柯基犬」。
• B64_BASE_IMAGE： 經過 Base64 編碼的編輯中圖片，大小上限為 10 MB。如要進一步瞭解 Base64 編碼，請參閱「Base64 編碼及解碼檔案」。
• B64_MASK_IMAGE： 採用 Base64 編碼的黑白遮罩圖片，大小為 10 MB 以下。
• MASK_DILATION： 選用。介於 0 到 1 (含) 之間的浮點值，代表遮罩要擴大的圖片寬度百分比。使用 dilation 有助於補償不精確的遮罩。建議您將值設為 0.01。

• EDIT_STEPS： 選用。代表取樣步數的整數。值越高，圖片品質越好；值越低，延遲時間越短。

  建議你一開始先嘗試 35 步，如果品質不符合需求，建議將值調高至上限 75。

• SAMPLE_COUNT： 選用。整數，說明要生成的圖片數量。可接受的值範圍為 1 至 4。預設值為 4。

HTTP 方法和網址：

POST https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/imagen-3.0-capability-001:predict

JSON 要求內文：

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      "referenceImages": [
        {
          "referenceType": "REFERENCE_TYPE_RAW",
          "referenceId": 1,
          "referenceImage": {
            "bytesBase64Encoded": "B64_BASE_IMAGE"
          }
        },
        {
          "referenceType": "REFERENCE_TYPE_MASK",
          "referenceImage": {
            "bytesBase64Encoded": "B64_MASK_IMAGE"
          },
          "maskImageConfig": {
            "maskMode": "MASK_MODE_USER_PROVIDED",
            "dilation": MASK_DILATION
          }
        }
      ]
    }
  ],
  "parameters": {
    "editConfig": {
      "baseSteps": EDIT_STEPS
    },
    "editMode": "EDIT_MODE_INPAINT_INSERTION",
    "sampleCount": SAMPLE_COUNT
  }
}

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

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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/imagen-3.0-capability-001:predict"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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/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"
    }
  ]
}

插入圖片並自動偵測遮罩

請使用下列範例指定修復功能，插入內容。在這些範例中，您會指定基本圖片和文字提示詞。Imagen 會自動偵測並建立遮罩區域，以修改基礎圖片。

控制台

1. 在 Google Cloud 控制台中，依序前往「Vertex AI」 >「Vertex AI Studio」 頁面。

   前往 Vertex AI Studio

2. 按一下「生成媒體」。

3. 按一下「圖片」。

4. 從「Task」(工作) 清單中選取「Inpaint-add」(修復 - 新增)。

5. 從「模型」清單中，選取要使用的 Imagen 模型。

6. 在「輸入圖片」中，按一下「新增」，然後選取要編輯的圖片以上傳。

7. 在「提示」方塊中輸入提示詞，說明如何編輯圖片。

8. 在編輯工具列中，按一下 background_replace「擷取遮罩」。

9. 選取其中一個遮罩擷取選項：

   • 背景元素：偵測背景元素，並在周圍建立遮罩。

   • 前景元素：偵測前景物件，並在周圍建立遮罩。

   • background_replace People： 偵測人物並建立周圍的遮罩。

10. 按一下「執行」。

REST

如要進一步瞭解 Imagen API，請參閱下列資源：

• 方法： endpoints.predict
• VisionGenerativeModelInstance
• VisionGenerativeModelParams
• VisionGenerativeModelResult

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：您的 Google Cloud 專案 ID。
• LOCATION：專案的區域。例如：us-central1、europe-west2 或 asia-northeast3。如需可用區域的清單，請參閱「Vertex AI 的生成式 AI 服務地區」。使用區域 API 端點時，系統會根據端點網址中的區域，決定要求處理位置，並忽略資源路徑中衝突的 LOCATION。
• TEXT_PROMPT：文字提示詞會引導模型生成圖片。使用提示詞插入 inpainting 時，請描述遮罩區域，以獲得最佳結果。避免使用單字提示。例如，請使用「a cute corgi」，而非「corgi」。
• B64_BASE_IMAGE：要編輯或放大解析度的基本圖片。圖片必須指定為 Base64 編碼的位元組字串。大小限制：10 MB。
• MASK_MODE - 一個字串，用於設定模型使用的自動遮蓋建立類型。 可用值：
  • MASK_MODE_BACKGROUND：使用背景區隔功能自動生成遮罩。
  • MASK_MODE_FOREGROUND：使用前景分割功能自動生成遮罩。
  • MASK_MODE_SEMANTIC：根據您在 maskImageConfig.maskClasses 陣列中指定的區隔類別，使用語意區隔自動產生遮罩。例如：

              "maskImageConfig": {
                "maskMode": "MASK_MODE_SEMANTIC",
                "maskClasses": [175, 176], // bicycle, car
                "dilation": 0.01
              }
            

• MASK_DILATION - 浮點值。這個遮罩要擴張的圖片寬度百分比。建議使用 0.01 值，補償不完美的輸入遮罩。
• EDIT_STEPS - 整數。基礎模型的取樣步驟數。如要插入修復內容，請從 35 步驟開始。如果品質不符合需求，請將步驟數調高至上限 75。增加步驟也會增加要求延遲時間。
• EDIT_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_RAW",
          "referenceId": 1,
          "referenceImage": {
            "bytesBase64Encoded": "B64_BASE_IMAGE"
          }
        },
        {
          "referenceType": "REFERENCE_TYPE_MASK",
          "referenceId": 2,
          "maskImageConfig": {
            "maskMode": "MASK_MODE",
            "dilation": MASK_DILATION
          }
        }
      ]
    }
  ],
  "parameters": {
    "editConfig": {
      "baseSteps": EDIT_STEPS
    },
    "editMode": "EDIT_MODE_INPAINT_INSERTION",
    "sampleCount": EDIT_IMAGE_COUNT
  }
}

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

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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"
    }
  ]
}

限制

以下各節說明 Imagen 物件移除功能的限制。

修改過的像素

模型會以自己的解析度 (例如 1024x1024) 生成像素，這可能與輸入圖片的解析度不同。也就是說，生成的圖片可能會出現原始圖片沒有的細微變化。

為完美保留圖片，建議使用遮罩將生成的圖片與輸入圖片混合。一般來說，如果輸入圖片解析度為 2K 以上，就必須混合生成圖像和輸入圖片。

插入限制

插入的物體通常會與基礎圖片的風格相符，但某些關鍵字可能會產生類似卡通的結果，而非相片擬真的輸出內容。

舉例來說，如果提示是「黃色長頸鹿」，系統可能會生成卡通風格的圖片，因為長頸鹿的自然顏色是棕色和黃褐色。生成色彩不自然的寫實圖像可能很困難。

後續步驟

閱讀有關 Imagen 和其他 Vertex AI 生成式 AI 產品的文章：

• 開發人員指南：開始在 Vertex AI 使用 Imagen 3
• 專為創作者打造的全新生成式媒體模型和工具
• Gemini 新功能：自訂 Gem 和 Imagen 3 圖像生成功能升級
• Google DeepMind：Imagen 3 - Google 品質最高的文字轉圖像模型