> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developer.ideogram.ai/v2/llms.txt
> - v1: https://developer.ideogram.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

# Replace background with Ideogram 4.5

POST https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5
Content-Type: multipart/form-data

Rebuild the background of an image as the setting shown in a
`background_reference` image, with Ideogram 4.5 at its highest
quality. The people in the source image are kept, people in the
reference are left out, and results keep the source image's aspect
ratio. Returns a `generation_id`; poll
`GET /v2/generations/{generation_id}` or supply a `webhook_url`.

Reference: https://developer.ideogram.ai/api-reference/images/replace-background/ideogram-4-5

## Authentication

- `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\"

## Request

### Query parameters

- `dry_run` (boolean, optional, default: false) — When true, the request is validated and priced but not run: nothing is generated, stored, or billed, and no safety review is performed. The response is a `PriceQuote` object instead of the usual response for this endpoint. Send exactly the request you would send to generate, so the quote reflects the same options.

### Body (multipart/form-data)

This endpoint expects a multipart form with multiple files.

- `image` (file, required) — The source image. JPEG, PNG, WEBP, HEIF, AVIF, GIF, BMP, TIFF, and MPO are supported, up to 50 MB. Its longer side may be at most the model's maximum aspect ratio times its shorter side; a more extreme proportion is rejected with a 400 that states the allowed range. Multipart requests only.
- `background_reference` (file, required) — A photo of the setting the new background should match. Its people are not copied. It is held to the same aspect-ratio limit as `image`. Multipart requests only.
- `num_images` (integer, optional) — The number of images to generate.
- `private` (boolean, optional) — Whether to keep the result private. When omitted, the result is private. Enterprise generations are always private.
- `webhook_url` (string, optional) — HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a JSON POST to this URL once all images for the request have finished generating. The body mirrors the synchronous generate response: `request_id`, `created`, and a `data` array containing every generated image (`url`, `prompt`, `resolution`, `seed`, `is_image_safe`). Each delivery is signed with Ed25519 and verifiable against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS; private and loopback hosts and the cloud metadata service are rejected.

## Response

### 200

Background replacement accepted for asynchronous processing.

- `generation_id` (string, required) — The generation ID to poll with `GET /v2/generations/{generation_id}`.

## Errors

### 400 Bad Request Error

Invalid input provided.

- `any`

### 401 Unauthorized Error

Unauthorized.

- `any`

### 402 Payment Required Error

Insufficient credits or quota.

- `error` (string, required) — A message describing why the generation request was rejected.
- `reject_reason` (enum, required) — The account or usage limit that rejected a generation request.
  - Allowed values: `insufficient_funds`, `subscription_required`, `daily_limit`, `priority_credit_required`, `inflight_limit`, `feature_limit`, `app_user_limit`
- `max_inflight_requests` (integer, optional) — How many generations the account may have in progress at once on the queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
- `task_completion_speed` (enum, optional) — The queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
  - Allowed values: `fast`, `slow`

### 403 Forbidden Error

Not authorized to replace backgrounds.

- `any`

### 404 Not Found Error

An image was not found or is not readable.

- `any`

### 429 Too Many Requests Error

Too many requests.

- `error` (string, required) — A message describing why the generation request was rejected.
- `reject_reason` (enum, required) — The account or usage limit that rejected a generation request.
  - Allowed values: `insufficient_funds`, `subscription_required`, `daily_limit`, `priority_credit_required`, `inflight_limit`, `feature_limit`, `app_user_limit`
- `max_inflight_requests` (integer, optional) — How many generations the account may have in progress at once on the queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
- `task_completion_speed` (enum, optional) — The queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
  - Allowed values: `fast`, `slow`

### 503 Service Unavailable Error

Background replacement is temporarily unavailable.

- `any`

## Examples

**Request**

```json
{
  "background_reference": "<file: background_reference.png>",
  "image": "<file: image.png>"
}
```

**Response**

```json
{
  "generation_id": "generation_id"
}
```

**SDK Code**

```python tool_replaceBackgroundIdeogram45_example
import requests

response = requests.post(
    "https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5",
    headers={"Api-Key": "<apiKey>"},
    files={
        "image": open("image.png", "rb"),
        "background_reference": open("background_reference.png", "rb"),
    },
)
print(response.json())

```

```javascript tool_replaceBackgroundIdeogram45_example
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("image", new Blob([await readFile("image.png")]), "image.png");
form.append("background_reference", new Blob([await readFile("background_reference.png")]), "background_reference.png");

const response = await fetch("https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5", {
  method: "POST",
  headers: { "Api-Key": "<apiKey>" },
  body: form,
});
console.log(await response.json());

```

```go tool_replaceBackgroundIdeogram45_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"background_reference\"; filename=\"background_reference.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"private\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Api-Key", "<apiKey>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby tool_replaceBackgroundIdeogram45_example
require 'uri'
require 'net/http'

url = URI("https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Api-Key"] = '<apiKey>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"background_reference\"; filename=\"background_reference.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"private\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java tool_replaceBackgroundIdeogram45_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5")
  .header("Api-Key", "<apiKey>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"background_reference\"; filename=\"background_reference.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"private\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php tool_replaceBackgroundIdeogram45_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5', [
  'multipart' => [
    [
        'name' => 'background_reference',
        'filename' => 'background_reference.png',
        'contents' => null
    ],
    [
        'name' => 'image',
        'filename' => 'image.png',
        'contents' => null
    ]
  ]
  'headers' => [
    'Api-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp tool_replaceBackgroundIdeogram45_example
using RestSharp;

var client = new RestClient("https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5");
var request = new RestRequest(Method.POST);
request.AddHeader("Api-Key", "<apiKey>");
request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"background_reference\"; filename=\"background_reference.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"private\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift tool_replaceBackgroundIdeogram45_example
import Foundation

let headers = [
  "Api-Key": "<apiKey>",
  "Content-Type": "multipart/form-data; boundary=---011000010111000001101001"
]
let parameters = [
  [
    "name": "background_reference",
    "fileName": "background_reference.png"
  ],
  [
    "name": "image",
    "fileName": "image.png"
  ],
  [
    "name": "num_images",
    "value": 
  ],
  [
    "name": "private",
    "value": 
  ],
  [
    "name": "webhook_url",
    "value": 
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/v2/image/replace-background/ideogram-4-5")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```