Image

Uploads an image file to Vimmerse storage so you can reference it by URL in other POST /v2/image/ routes.

This is the only v2 image route that uses multipart/form-data. All generation and edit routes expect JSON with image_url or image_urls.

Supported formats

JPEG, PNG, WebP (including transparency where supported).

Example

import requests

url = "https://api.vimmerse.net/v2/image"
headers = {"X-Api-Key": "YOUR_API_KEY"}

with open("/path/to/photo.png", "rb") as f:
    response = requests.post(
        url,
        headers=headers,
        files={"image_file": ("photo.png", f, "image/png")},
        timeout=120,
    )

response.raise_for_status()
asset = response.json()
print(asset["results"])  # uploaded file URL(s)

Returns how many credits an image generation request would charge for the given app_name, option, quantity, and optional prompt, without creating an asset.

Uses the same billing rules as POST /v2/image/ generation routes. Send Content-Type: application/json.

Example

import requests

url = "https://api.vimmerse.net/v2/image/estimate-credits"
headers = {"Content-Type": "application/json"}
payload = {
    "app_name": "text-to-image",
    "option": "NanoBanana",
    "quantity": 2,
    "prompt": "Product photo of running shoes on a gradient background",
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())

Generates one or more images from a text prompt.

Send Content-Type: application/json. The response is an asset object; output URLs are in results.

Parameters

Example

import requests

url = "https://api.vimmerse.net/v2/image/text-2-image"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "prompt": "A serene landscape with mountains and a lake at sunset, cinematic lighting",
    "quantity": 2,
    "option": "AutoI",
    "aspect_ratio": "16:9",
    "enhance_image": False,
    "async_mode": False,
}

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

Transforms or reimagines a source image using a text prompt.

Provide image_url (from upload or any public HTTPS URL). Response asset URLs are in results.

Parameters

Example

import requests

url = "https://api.vimmerse.net/v2/image/image-2-image"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "image_url": "https://media.vimmerse.net/example/uploads/shoe.png",
    "prompt": "Make the shoe blue with a sky background",
    "option": "AutoI",
    "aspect_ratio": "16:9",
    "quantity": 1,
}

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

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

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"])

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

Example — remove background

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

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

Edits an image: remove text, upscale, reframe, expand aspect ratio, or inpaint masked regions.

Example — remove text

import requests

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

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

Example — inpaint

payload = {
    "image_url": "https://media.vimmerse.net/example/room.png",
    "mask_url": "https://media.vimmerse.net/example/room_mask.png",
    "option": "Inpaint",
    "prompt": "Add a mountain view through the window",
    "quantity": 1,
}

Swaps faces in a target image using one or more reference face images.

• image_urls[0] — target image containing face(s) to replace
• image_urls[1:] — reference faces
• order_indices — optional mapping of target face indices (left-to-right from 0)

Example

import requests

url = "https://api.vimmerse.net/v2/image/face-swap"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "image_urls": [
        "https://media.vimmerse.net/example/group_photo.png",
        "https://media.vimmerse.net/example/face_a.png",
        "https://media.vimmerse.net/example/face_b.png",
    ],
    "option": "NanoBananaFaceSwap",
    "face_only_mode": True,
    "multi_face_mode": True,
    "order_indices": [0, 1],
}

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

Virtual try-on: composites clothing from clothes_image_url onto the person in human_image_url.

Example

import requests

url = "https://api.vimmerse.net/v2/image/try-on"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "human_image_url": "https://media.vimmerse.net/example/model.png",
    "clothes_image_url": "https://media.vimmerse.net/example/jacket.png",
    "option": "NanoBananaTryOn",
}

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