For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Manage API keysIdeogram
  • Ideogram API
    • API Overview
    • API Setup
    • Account API Page
    • API Pricing
    • API Status
  • Tutorials
    • Custom Model Training
  • API Reference
    • POSTGenerate with Ideogram 3.0
    • POSTGenerate with Ideogram 3.0 (Transparent Background)
    • POSTInpaint with Ideogram 3.0
    • POSTRemix with Ideogram 3.0
    • POSTReframe with Ideogram 3.0
    • POSTReplace Background with Ideogram 3.0
    • POSTRemove Background
    • POSTLayerize Text
    • POSTEdit images with a prompt
    • POSTUpscale
    • POSTDescribe
    • POSTGenerate (legacy)
    • POSTEdit with Ideogram 3.0 (legacy)
    • POSTEdit (legacy)
    • POSTRemix (legacy)
    • POSTReframe (legacy)
  • Custom Model Training
    • GETList datasets
    • POSTCreate a new dataset
    • GETGet a dataset
    • POSTUpload assets to a dataset
    • POSTTrain a custom Ideogram v3 model
    • GETList models
    • GETGet model details
LogoLogo
LogoLogo
Manage API keysIdeogram
API Reference

Replace Background with Ideogram 3.0

POST
https://api.ideogram.ai/v1/ideogram-v3/replace-background
POST
/v1/ideogram-v3/replace-background
$curl -X POST https://api.ideogram.ai/v1/ideogram-v3/replace-background \
>  -H "Api-Key: <apiKey>" \
>  -H "Content-Type: multipart/form-data" \
>  -F image=@<file1> \
>  -F prompt="Add a forest in the background"
1{
2  "created": "2000-01-23 04:56:07+00:00",
3  "data": [
4    {
5      "prompt": "Add a forest in the background",
6      "resolution": "1280x800",
7      "is_image_safe": true,
8      "seed": 12345,
9      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89",
10      "style_type": "GENERAL"
11    }
12  ]
13}

Replace the background of a given image synchronously using a prompt with Ideogram 3.0. The foreground subject will be identified and kept, while the background is replaced based on the prompt and chosen style. Supported image formats include JPEG, PNG, and WebP. Images links are available for a limited period of time; if you would like to keep the image, you must download it.

Was this page helpful?
Previous

Remove Background

Next
Built with

Authentication

Api-Keystring

API key for access control. Use in the header with the name “Api-Key”

Request

A request to replace the background of an image with Ideogram 3.0.
imagefileRequired

The image whose background is being replaced (max size 10MB); only JPEG, WebP and PNG formats are supported at this time.

promptstringRequired
The prompt describing the desired new background.
magic_promptenumOptional
Determine if MagicPrompt should be used in generating the request or not.
Allowed values:
num_imagesintegerOptional1-8Defaults to 1
The number of images to generate.
seedintegerOptional0-2147483647
Random seed. Set for reproducible generation.
rendering_speedenumOptionalDefaults to DEFAULT
The rendering speed to use.
Allowed values:
style_presetenumOptional
A predefined style preset that applies a specific artistic style to the generated image.
color_paletteobjectOptional

A color palette for generation, must EITHER be specified via one of the presets (name) or explicitly via hexadecimal representations of the color with optional weights (members). Not supported by V_1, V_1_TURBO, V_2A and V_2A_TURBO models.

style_codeslist of stringsOptional

A list of 8 character hexadecimal codes representing the style of the image. Cannot be used in conjunction with style_reference_images or style_type.

style_reference_imagesfilesOptional

A set of images to use as style references (maximum total size 10MB across all style references). The images should be in JPEG, PNG or WebP format.

Response

Background replacement generated successfully.
createddatetime
The time the request was created.
datalist of objects

A list of ImageObjects that contain the generated image(s).

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
429
Too Many Requests Error