Ideogram - Background Replacer

Replace the background of an image with a new AI-generated scene described by a text prompt using Ideogram 3.0. The foreground subject is preserved while the surrounding scene is regenerated.

Endpoint

POSThttps://api.1min.ai/api/features

Request Headers

Field	Value
API-KEY	<api-key>
Content-Type	application/json

Parameters

Parameter	Type	Required	Description
type	string	Yes	Feature type identifier. Must be BACKGROUND_REPLACER
model	string	Yes	AI model identifier. Must be ideogram-3
promptObject	object	Yes	Configuration object containing all replacement parameters

Prompt Object Parameters

Parameter	Type	Required	Description	Default
prompt	string	Yes	Description of the new background scene	-
imageUrl	string	Yes	Asset path to the source image	-
num_images	number	Yes	Number of variations to generate (1–8)	-
rendering_speed	string	No	Speed vs quality tradeoff. One of FLASH, TURBO, DEFAULT, QUALITY	DEFAULT
magic_prompt	string	No	Automatically enhance the prompt. One of AUTO, ON, OFF	AUTO
style_type	string	No	Style to apply. One of AUTO, GENERAL, REALISTIC, DESIGN, FICTION	AUTO
style_preset	string	No	Predefined artistic style. Mutually exclusive with style_reference_images. If style_type is provided, must be AUTO or GENERAL.	-
style_reference_images	string[]	No	Up to 5 asset paths used as style references. Each image ≤ 10 MB; total across all references ≤ 10 MB. JPEG, PNG, or WebP. Mutually exclusive with style_preset. If style_type is provided, must be AUTO or GENERAL.	-
negative_prompt	string	No	Elements to exclude from the background	-
seed	number	No	Random seed for reproducibility (0–2147483647)

Image Requirements

• Per-file maximum size: 10 MB
• Total size of style references: ≤ 10 MB across all files
• Formats: JPEG, PNG, WebP

style_preset values

80S_ILLUSTRATION, 90S_NOSTALGIA, ABSTRACT_ORGANIC, ANALOG_NOSTALGIA, ART_BRUT, ART_DECO, ART_POSTER, AURA, AVANT_GARDE, BAUHAUS, BLUEPRINT, BLURRY_MOTION, BRIGHT_ART, C4D_CARTOON, CHILDRENS_BOOK, COLLAGE, COLORING_BOOK_I, COLORING_BOOK_II, CUBISM, DARK_AURA, DOODLE, DOUBLE_EXPOSURE, DRAMATIC_CINEMA, EDITORIAL, EMOTIONAL_MINIMAL, ETHEREAL_PARTY, EXPIRED_FILM, FLAT_ART, FLAT_VECTOR, FOREST_REVERIE, GEO_MINIMALIST, GLASS_PRISM, GOLDEN_HOUR, GRAFFITI_I, GRAFFITI_II, HALFTONE_PRINT, HIGH_CONTRAST, HIPPIE_ERA, ICONIC, JAPANDI_FUSION, JAZZY, LONG_EXPOSURE, MAGAZINE_EDITORIAL, MINIMAL_ILLUSTRATION, MIXED_MEDIA, MONOCHROME, NIGHTLIFE, OIL_PAINTING, OLD_CARTOONS, PAINT_GESTURE, POP_ART, RETRO_ETCHING, RIVIERA_POP, SPOTLIGHT_80S, STYLIZED_RED, SURREAL_COLLAGE, TRAVEL_POSTER, VINTAGE_GEO, VINTAGE_POSTER, WATERCOLOR, WEIRD, WOODBLOCK_PRINT

Code Examples

cURL

curl --location 'https://api.1min.ai/api/features' \
--header 'API-KEY: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"type": "BACKGROUND_REPLACER",
"model": "ideogram-3",
"promptObject": {
  "prompt": "A man standing in a busy coffee shop",
  "imageUrl": "development/images/portrait.png",
  "num_images": 1,
  "rendering_speed": "DEFAULT",
  "magic_prompt": "AUTO",
  "style_type": "AUTO"
}
}'

JavaScript

fetch('https://api.1min.ai/api/features', {
method: 'POST',
headers: {
  'Content-Type': 'application/json',
  'API-KEY': 'YOUR_API_KEY'
},
body: JSON.stringify({
  type: 'BACKGROUND_REPLACER',
  model: 'ideogram-3',
  promptObject: {
    prompt: 'A man standing in a busy coffee shop',
    imageUrl: 'development/images/portrait.png',
    num_images: 1,
    rendering_speed: 'DEFAULT',
    magic_prompt: 'AUTO',
    style_type: 'AUTO'
  }
})
})

Python

import requests

url = "https://api.1min.ai/api/features"
headers = {
"Content-Type": "application/json",
"API-KEY": "YOUR_API_KEY"
}

data = {
"type": "BACKGROUND_REPLACER",
"model": "ideogram-3",
"promptObject": {
  "prompt": "A man standing in a busy coffee shop",
  "imageUrl": "development/images/portrait.png",
  "num_images": 1,
  "rendering_speed": "DEFAULT",
  "magic_prompt": "AUTO",
  "style_type": "AUTO"
}
}

response = requests.post(url, headers=headers, json=data)

Interactive Playground

API Playground

GETPOSTPUTDELETEhttps://api.1min.ai/api/features

AI Model *Ideogram 3.0

Prompt *

Describe the new background scene

A man standing in a busy coffee shop

Source Image *

Number of Images

1–8

Rendering Speed Flash (Fastest)TurboDefaultQuality (Best)

Magic Prompt AutoOnOff

Style Type AutoGeneralRealisticDesignFiction

Style Preset

Mutually exclusive with style_reference_images

Style Reference Images

Comma-separated asset paths for style references (up to 5, ≤10 MB each/total). Mutually exclusive with style_preset.

Negative Prompt

Seed

0–2147483647

Generated cURL Command:

curl -X POST "https://api.1min.ai/api/features" \
  -H "API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "BACKGROUND_REPLACER",
  "model": "ideogram-3",
  "promptObject": {
    "prompt": "A man standing in a busy coffee shop",
    "imageUrl": "development/images/portrait.png",
    "num_images": 1,
    "rendering_speed": "DEFAULT",
    "magic_prompt": "AUTO",
    "style_type": "AUTO"
  }
}'

Response Format

{
"aiRecord": {
  "uuid": "e40dd9ef-0944-4ce5-bc90-1edd2548619a",
  "model": "ideogram-3",
  "type": "BACKGROUND_REPLACER",
  "status": "SUCCESS",
  "aiRecordDetail": {
    "promptObject": {
      "prompt": "A man standing in a busy coffee shop",
      "imageUrl": "development/images/portrait.png",
      "num_images": 1,
      "rendering_speed": "DEFAULT",
      "style_type": "AUTO",
      "magic_prompt": "AUTO"
    },
    "resultObject": [
      "development/images/2026_04_15_bg_replace_result.png"
    ],
    "responseObject": {
      "created": "2026-04-15T10:30:00Z",
      "data": [
        {
          "url": "https://ideogram.ai/.../bg_replace.png",
          "prompt": "A man standing in a busy coffee shop",
          "resolution": "1024x1024",
          "is_image_safe": true,
          "seed": 12345,
          "style_type": "AUTO"
        }
      ]
    }
  }
}
}