> [!CAUTION]
> **Caution:** The following table describes image generation endpoints that are deprecated and their replacements. We recommend updating your model endpoints before June 30, 2026, to avoid service disruption.
>
> | Discontinued endpoints | Recommended endpoint migration |
> |---|---|
> | `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` |
>
<br />

This page describes replacing the background of an image. Imagen on Vertex AI
lets you use automatic object segmentation to maintain that content
while modifying other image content. With Imagen 3 you can also
provide your own mask area for more control when editing.

The following models support replacing image backgrounds:

- [`imagen-3.0-capability-001`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/imagen/3-0-generate.md.txt#3.0-capability-001)


[View Imagen for Editing and Customization model card](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/imagen-3.0-capability-001)

## Product image editing example


> [!NOTE]
> To see an example of Imagen 3 Editing,
> run the "Imagen 3 Image Editing" notebook in one of the following
> environments:
>
> [![](https://docs.cloud.google.com/static/vertex-ai/images/colab-logo-32px.png)Open in Colab](https://colab.research.google.com/github/GoogleCloudPlatform/generative-ai/blob/main/vision/getting-started/imagen3_editing.ipynb)
>
>
> \|
>
> [![](https://docs.cloud.google.com/static/vertex-ai/images/colab-enterprise-logo-32px.png)Open in Colab Enterprise](https://console.cloud.google.com/vertex-ai/colab/import/https%3A%2F%2Fraw.githubusercontent.com%2FGoogleCloudPlatform%2Fgenerative-ai%2Fmain%2Fvision%2Fgetting-started%2Fimagen3_editing.ipynb)
>
>
> \|
>
> [![](https://docs.cloud.google.com/static/vertex-ai/images/vertex-ai-workbench-logo-32px.png)Open
> in Vertex AI Workbench](https://console.cloud.google.com/vertex-ai/workbench/deploy-notebook?download_url=https://raw.githubusercontent.com/GoogleCloudPlatform/generative-ai/main/vision/getting-started/imagen3_editing.ipynb)
>
>
> \|
>
> [![](https://docs.cloud.google.com/static/vertex-ai/images/github-logo-32px.png)View on GitHub](https://github.com/GoogleCloudPlatform/generative-ai/blob/main/vision/getting-started/imagen3_editing.ipynb)

<br />

The following use case highlights enhancing a product image by modifying an
image's background, but preserving a product's appearance within the image.
![Sample generated image in the console](https://docs.cloud.google.com/static/vertex-ai/generative-ai/docs/image/images/product-image_bag_v006.png) Image generated with the Imagen product image editing feature from the prompt: *on a table in a boutique store*. Original image source: [Irene Kredenets](https://unsplash.com/photos/brown-leather-handbag-on-white-surface-tcVH_BwHtrc) on [Unsplash](https://unsplash.com/).

## Before you begin

1. Set up authentication for your environment.

   Select the tab for how you plan to use the samples on this page:

   ### Console


   When you use the Google Cloud console to access Google Cloud services and
   APIs, you don't need to set up authentication.

   ### REST


   To use the REST API samples on this page in a local development environment, you use the
   credentials you provide to the gcloud CLI.
   1. [Install](https://docs.cloud.google.com/sdk/docs/install) the Google Cloud CLI.
   2. If you're using an external identity provider (IdP), you must first [sign in to the gcloud CLI with your federated identity](https://docs.cloud.google.com/iam/docs/workforce-log-in-gcloud.md.txt).


   For more information, see
   [Authenticate for using REST](https://docs.cloud.google.com/docs/authentication/rest.md.txt)
   in the Google Cloud authentication documentation.

## Edit with an automatically detected background mask

Use the following instructions to enable and use product image editing with
automatic background detection.

### Console

1.
   In the Google Cloud console, go to the **Vertex AI \> Vertex AI Studio** page.


   [Go to Vertex AI Studio](https://console.cloud.google.com/vertex-ai/studio/media/generate;tab=image)
2.
   Click **Generate media**.

3.
   Click **Image**.

4. From the **Task** list, select **Product-background-editing**.

5. From the **Model** list, select the Imagen model to use.

6. In **Input image** click **Add** and select the image that you are editing
   to upload.

7. In the **Prompt** box, enter a prompt that describes how to edit the image.

8. Select one of the following mask extraction options:

   - **Background elements**: detects the background elements and creates a mask around them.
   - **Foreground elements**: detects the foreground objects and creates a mask around them.
   - background_replace **People**: detects people and creates a mask around them.
9. Click **Run**.

### REST

<br />

For more information, see the [Edit
images](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/imagen-api-edit) API
reference.


Before using any of the request data,
make the following replacements:

- <var translate="no">PROJECT_ID</var>: Your Google Cloud [project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects).
- <var translate="no">LOCATION</var>: Your project's region. For example, `us-central1`, `europe-west2`, or `asia-northeast3`. For a list of available regions, see [Generative AI on Vertex AI locations](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/locations-genai). When a regional API endpoint is used, the region from the endpoint's URL determines where the request is processed, and this `LOCATION` in the resource path is ignored if it conflicts.
- <var translate="no">TEXT_PROMPT</var>: The text prompt that guides what images the model generates. This field is required for both generation and editing.
- `referenceType`: A `ReferenceImage` is an image that provides additional context for image editing. A normal RGB raw reference image (`REFERENCE_TYPE_RAW`) is required for editing use cases. At most one raw reference image may exist in one request. The output image has the same height and width as raw reference image. A mask reference image (`REFERENCE_TYPE_MASK`) is required for masked editing use cases.
- `referenceId`: The integer ID of the reference image. In this example the two reference image objects are of different types, so they have distinct `referenceId` values (`1` and `2`).
- <var translate="no">B64_BASE_IMAGE</var>: The base image to edit or upscale. The image must be specified as a [base64-encoded](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/image/base64-encode.md.txt) byte string. Size limit: 10 MB.
- `maskImageConfig.maskMode`: The mask mode for mask editing. `MASK_MODE_BACKGROUND` is used to automatically mask out background without a user-provided mask.
- <var translate="no">MASK_DILATION</var> - float. The percentage of image width to dilate this mask by. A value of `0.00` is recommended to avoid extending foreground product. Minimum: 0, maximum: 1. Default: 0.03.
- <var translate="no">EDIT_STEPS</var> - integer. The number of sampling steps for the base model. For product image editing, start at `75` steps.
- <var translate="no">EDIT_IMAGE_COUNT</var> - The number of edited images. Accepted integer values: 1-4. Default value: 4.


HTTP method and URL:

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


Request JSON body:

```
{
  "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_BACKGROUND",
            "dilation": MASK_DILATION
          }
        }
      ]
    }
  ],
  "parameters": {
    "editConfig": {
      "baseSteps": EDIT_STEPS
    },
    "editMode": "EDIT_MODE_BGSWAP",
    "sampleCount": EDIT_IMAGE_COUNT
  }
}
```

To send your request, choose one of these options:

#### curl

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Save the request body in a file named `request.json`,
and execute the following command:

```
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

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Save the request body in a file named `request.json`,
and execute the following command:

```
$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
```
The following sample response is for a product background editing request. The response returns four prediction objects, with the generated image bytes base64-encoded.

```
{
  "predictions": [
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    },
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    }
  ]
}
```

<br />

## Edit with a defined mask area

You can choose to mask the area that is replaced, rather than letting
Imagen detect the mask automatically.

### Console

1.
   In the Google Cloud console, go to the **Vertex AI \> Vertex AI Studio** page.


   [Go to Vertex AI Studio](https://console.cloud.google.com/vertex-ai/studio/media/generate;tab=image)
2.
   Click **Generate media**.

3.
   Click **Image**.

4. From the **Task** list, select **Product-background-editing**.

5. From the **Model** list, select the Imagen model to use.

6. In **Input image** click **Add** and select the image that you are editing
   to upload.

7. In the **Prompt** box, enter a prompt that describes how to edit the image.

8. Do one of the following to specify a mask:

   - Upload your own mask:
     1. Create a mask on your computer.
     2. Click upload **Import mask** and select a mask to upload.
   - Define your mask: in the editing toolbar, use the mask tools (**box** , **brush** , or masked_transitions **invert** tool) to specify the area or areas to add content to.
9. Click **Run**.

### REST

<br />

For more information about the Imagen API, see the following:

- [Method:
  `endpoints.predict`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations.endpoints/predict)
- [`VisionGenerativeModelInstance`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/Shared.Types/VisionGenerativeModelInstance)
- [`VisionGenerativeModelParams`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/Shared.Types/VisionGenerativeModelParams)
- [`VisionGenerativeModelResult`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/Shared.Types/VisionGenerativeModelResult)


  Before using any of the request data,
  make the following replacements:
  - <var translate="no">PROJECT_ID</var>: Your Google Cloud [project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects).
  - <var translate="no">LOCATION</var>: Your project's region. For example, `us-central1`, `europe-west2`, or `asia-northeast3`. For a list of available regions, see [Generative AI on Vertex AI locations](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/locations-genai). When a regional API endpoint is used, the region from the endpoint's URL determines where the request is processed, and this `LOCATION` in the resource path is ignored if it conflicts.
  - <var translate="no">TEXT_PROMPT</var>: The text prompt that guides what images the model generates. This field is required for both generation and editing.
  - `referenceId`: The integer ID of the reference image. In this example the two reference image objects are of different types, so they have distinct `referenceId` values (`1` and `2`).
  - <var translate="no">B64_BASE_IMAGE</var>: The base image to edit or upscale. The image must be specified as a [base64-encoded](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/image/base64-encode.md.txt) byte string. Size limit: 10 MB.
  - <var translate="no">B64_MASK_IMAGE</var>: The black and white image you want to use as a mask layer to edit the original image. The image must be specified as a [base64-encoded](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/image/base64-encode.md.txt) byte string. Size limit: 10 MB.
  - <var translate="no">MASK_DILATION</var> - float. The percentage of image width to dilate this mask by. A value of `0.00` is recommended to avoid extending foreground product. Minimum: 0, maximum: 1. Default: 0.03.
  - <var translate="no">EDIT_STEPS</var> - integer. The number of sampling steps for the base model. For product image editing, start at `75` steps.
  - <var translate="no">EDIT_IMAGE_COUNT</var> - The number of edited images. Accepted integer values: 1-4. Default value: 4.


  HTTP method and URL:

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


  Request JSON body:

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

  To send your request, choose one of these options:

  #### curl

  > [!NOTE]
  > **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


  Save the request body in a file named `request.json`,
  and execute the following command:

  ```
  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

  > [!NOTE]
  > **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


  Save the request body in a file named `request.json`,
  and execute the following command:

  ```
  $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
  ```
  The following sample response is for a product background editing request.

  ```
  {
    "predictions": [
      {
        "bytesBase64Encoded": "BASE64_IMG_BYTES",
        "mimeType": "image/png"
      },
      {
        "mimeType": "image/png",
        "bytesBase64Encoded": "BASE64_IMG_BYTES"
      },
      {
        "bytesBase64Encoded": "BASE64_IMG_BYTES",
        "mimeType": "image/png"
      },
      {
        "bytesBase64Encoded": "BASE64_IMG_BYTES",
        "mimeType": "image/png"
      }
    ]
  }
  ```

<br />

## Limitations

Because masks are sometimes incomplete, the model may try to complete the
foreground object when extremely small bits are missing at the boundary. As a
rare side effect, when the foreground object is already complete, the model may
create slight extensions.

A workaround is to segment the model output and then blend. The following is
an example python snippet demonstrating a workaround:

```python
blended = Image.composite(out_images[0].resize(image_expanded.size), image_expanded, mask_expanded)
```

## What's next

Read articles about Imagen and other Generative AI on Vertex AI
products:

- [A developer's guide to getting started with Imagen 3 on
  Vertex AI](https://cloud.google.com/blog/products/ai-machine-learning/a-developers-guide-to-imagen-3-on-vertex-ai?e=0?utm_source%3Dlinkedin)
- [New generative media models and tools, built with and for creators](https://blog.google/technology/ai/google-generative-ai-veo-imagen-3/#veo)
- [New in Gemini: Custom Gems and improved image generation with
  Imagen 3](https://blog.google/products/gemini/google-gemini-update-august-2024/)
- [Google DeepMind: Imagen 3 - Our highest quality
  text-to-image model](https://deepmind.google/technologies/imagen-3/)