# Vimmerse Replace Background

> Vimmerse Replace Background is a paid API for AI agents from agents.vimmerse.net, paid per call via MPP, $0.12/call (dynamic — varies by input), status unknown (last checked 2026-10-30).

Removes, replaces, or restyles the background of an image using one of three modes: transparent removal, new background substitution, or style-based restyling.

## Facts

- Endpoint: POST https://agents.vimmerse.net/v2/image/replace-background?utm_source=zero.xyz
- Price: $0.12/call (dynamic — varies by input)
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-30
- Activations on Zero: 0
- Provider: agents.vimmerse.net
- Website: https://agents.vimmerse.net
- Canonical page: https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-replace-background-ef95375f
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_6qgYjgX4TZcjlYVbJ3LX3

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agents-vimmerse-net-vimmerse-replace-background-ef95375f -d '<json body>'
```

Example prompt: Remove the background from this product image at https://media.vimmerse.net/example/product.png and give me a transparent PNG I can use on my website.

## When to prefer this

Choose this endpoint when you need to isolate a foreground subject by removing its background, swap a background with a specific replacement image, or restyle a background using a style reference — all without manual masking. It is ideal for e-commerce product photography, portrait editing, and creative compositing workflows where the input is a URL-addressable image.

## Known failure modes

- Invalid or inaccessible image_url returns an error
- ReplaceBackground or RestyleBackground called without image2_url returns a validation error
- Unsupported image format or corrupt image URL causes processing failure
- Timeout on very large images (default timeout should be set to 300s)
- Invalid API key returns 401 unauthorized
- Exceeding credit balance returns 402 payment required

## How this service works

Removes, replaces, or restyles the background of an image.

| `option` | `image2_url` | Behavior |
|----------|--------------|----------|
| `RemoveBackground` | omit | Transparent PNG foreground |
| `ReplaceBackground` | required | New background image |
| `RestyleBackground` | required | Style reference image |

### Example — remove background

```python
import requests

url = "https://api.vimmerse.net/v2/image/replace-background"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "image_url": "https://media.vimmerse.net/example/product.png",
    "option": "RemoveBackground",
}

response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
print(response.json()["results"])
```

### Example — replace background

```python
payload = {
    "image_url": "https://media.vimmerse.net/example/product.png",
    "image2_url": "https://media.vimmerse.net/example/studio_bg.png",
    "option": "ReplaceBackground",
}
```

## Output

A processed image returned in the 'results' field of the JSON response. For RemoveBackground: a transparent PNG with the foreground subject isolated. For ReplaceBackground: the subject composited onto the provided background image. For RestyleBackground: the background restyled according to the reference image. Async mode jobs return a job ID to poll.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "ReplaceBackgroundRequest",
 "required": [
  "image_url"
 ],
 "properties": {
  "option": {
   "type": "string",
   "title": "Option",
   "default": "RemoveBackground",
   "description": "Option to apply. Available values: `RemoveBackground`, `ReplaceBackground`, `RestyleBackground`."
  },
  "image_url": {
   "type": "string",
   "title": "Base Image URL"
  },
  "async_mode": {
   "type": "boolean",
   "title": "Async Mode",
   "default": false
  },
  "image2_url": {
   "type": "string",
   "title": "Additional Image URL (Optional)",
   "default": "",
   "description": "Optional second image used for background replacement."
  },
  "webhook_url": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "title": "Webhook URL"
  }
 },
 "description": "Request body for POST /v2/image/replace-background. Content-Type: application/json."
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "Response Replace Background Api V2 Image Replace Background Post",
 "additionalProperties": true
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-replace-background-ef95375f/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.vimmerse.net](https://www.zero.xyz/host/agents.vimmerse.net/llms.txt)