# Vimmerse Elements – Multi-Reference Image Generation & Editing

> Vimmerse Elements – Multi-Reference Image Generation & Editing 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-31).

Generates or edits an image by compositing a main image with one or more reference images (characters, objects, environments) using a text prompt.

## Facts

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

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-elements-multi-reference-image-9f63c989 -d '<json body>'
```

Example prompt: Take my main scene image at https://media.vimmerse.net/example/main.png and place the character from https://media.vimmerse.net/example/ref_character.png naturally into it — photorealistic style, 16:9 aspect ratio, using the AutoI model, and give me 1 result.

## When to prefer this

Choose this endpoint when you need to combine a main scene or base image with one or more visual references (characters, objects, or environments) into a single output image. It is distinct from pure text-to-image generation because it anchors the output to real visual inputs. Prefer it over background replacement (which only swaps the background) when you need multi-reference compositing with full-scene control and prompt guidance.

## Known failure modes

- Invalid or inaccessible image URLs return a 4xx error
- Exceeding the model-specific URL limit (e.g. more than 4 URLs for FluxKontextPro) causes a validation error
- Unsupported aspect ratio format returns a pattern mismatch error
- API key missing or invalid returns 401 unauthorized
- Timeout on very large or slow-to-process images (client should set a long timeout, e.g. 300s)
- Invalid option value returns a validation error listing accepted values

## How this service works

Generates or edits an image using a **main** image plus **reference** images (characters, objects, environments).

Pass all images as **`image_urls`**: the first URL is the main image; the rest are references. Limits depend on `option` (see field description in the schema).

### Example

```python
import requests

url = "https://api.vimmerse.net/v2/image/elements"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "image_urls": [
        "https://media.vimmerse.net/example/main.png",
        "https://media.vimmerse.net/example/ref_character.png",
    ],
    "prompt": "Place the character naturally in the scene, photorealistic",
    "option": "AutoI",
    "aspect_ratio": "16:9",
    "quantity": 1,
    "swap_faces": False,
}

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

## Output

A JSON object with a 'results' array containing URLs or base64 data for the generated composite images. The number of images matches the requested quantity (1–4). Optional async mode returns a job ID to poll instead.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "ElementsRequest",
 "required": [
  "image_urls"
 ],
 "properties": {
  "option": {
   "type": "string",
   "title": "Option",
   "default": "AutoI",
   "description": "Available values: `AutoI`, `FluxPro`, `Seedream`, `NanoBananaPro`, `FluxKontextPro`, `NanoBanana`, and `GPTImage`."
  },
  "prompt": {
   "type": "string",
   "title": "Prompt",
   "default": "",
   "examples": [
    "Make image more realistic."
   ]
  },
  "quantity": {
   "type": "integer",
   "title": "Quantity",
   "default": 1,
   "maximum": 4,
   "minimum": 1,
   "description": "Number of images to generate."
  },
  "async_mode": {
   "type": "boolean",
   "title": "Async Mode",
   "default": false
  },
  "image_urls": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "title": "Element Image URLs",
   "minItems": 1,
   "description": "The first image is the main image and the rest are reference images. Max 4 URLs for `FluxKontextPro`, 6 for `Seedream`, 8 for `FluxPro`, and 10 for `GPTImage`, `NanoBanana`, and `NanoBananaPro`."
  },
  "swap_faces": {
   "type": "boolean",
   "title": "Swap Faces",
   "default": false,
   "description": "Swap the resulting faces with the original faces."
  },
  "webhook_url": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "title": "Webhook URL"
  },
  "aspect_ratio": {
   "type": "string",
   "title": "Aspect Ratio",
   "default": "16:9",
   "pattern": "^(\\d+):(\\d+)$",
   "examples": [
    "21:9",
    "16:9",
    "4:3",
    "3:2",
    "1:1",
    "2:3",
    "3:4",
    "9:16",
    "9:21"
   ]
  },
  "enhance_image": {
   "type": "boolean",
   "title": "Enhance Image",
   "default": false,
   "description": "Enhances the image by applying 1× super-resolution during post-processing."
  }
 },
 "description": "Request body for POST /v2/image/elements. Content-Type: application/json."
}
```

## Response schema (JSON Schema)

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

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-elements-multi-reference-image-9f63c989/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)