Image

Uploads images to the Vimmerse platform for use in API requests.

Benefits

• Store images securely in the cloud
• Reference images by URL in other API calls
• Manage your media assets efficiently

Supported Formats

• JPEG, JPG
• PNG (with transparency support)
• WebP

Usage

After uploading, you'll receive a URL that can be used with the image_url parameter in other endpoints.

Generates high-quality images from text prompts using advanced AI models.

Parameters

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	Text description of the desired image. Be specific about style, composition, colors, and mood.
quantity	integer	No	1	Number of images to generate. Range: 1-4.
option	string	No	"Auto"	AI model to use. "Auto" automatically selects the best model. Other options depend on available models.
aspect_ratio	string	No	"16:9"	Image dimensions. Available: "21:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:21"
creativity_strength	integer	No	5	Control over creativity level. Range: 1-10. Higher values produce more creative variations.
enhance_image	boolean	No	false	Apply 1× super-resolution enhancement during post-processing for higher quality output.
async_mode	boolean	No	false	Enable asynchronous processing mode. Returns immediately with asset_id for polling.
webhook_url	string	No	null	URL to receive completion notification via POST request when processing completes.

Example Request

import requests

url = "https://api.vimmerse.net/image/text-2-image"

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
}
payload = {
    "quantity": 3,  # Number of images to generate (1-4)
    "prompt": "A serene landscape with mountains and a lake at sunset",
    "option": "Auto",  # Image generation model
    "aspect_ratio": "16:9"  # Image aspect ratio
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Error Handling

The API may return the following HTTP status codes:

• 200 - Success. Image generation initiated or completed (depending on async_mode).
• 400 - Bad Request. Invalid parameters or missing required fields.
• 402 - Payment Required. Insufficient credits in your account.
• 500 - Internal Server Error. Please retry or contact support.

Transforms images using text prompts with various editing modes.

Available Options

Remake

• Redesigns the image based on the prompt
• Changes overall composition and elements
• Best for major creative transformations

Restructure

• Completely restructures the image layout
• Maintains visual style while changing composition
• Ideal for dramatic scene changes

Restyle

• Applies artistic style transformations
• Changes visual appearance while keeping content
• Perfect for style transfer and artistic effects

Sketch

• Converts image to sketch/drawing style
• Creates artistic line-based visuals
• Great for illustrations and art styles

ReplaceWith

• Replaces specific objects with others
• Must include "replace" and "with" in prompt
• Perfect for object substitution

RecolorTo

• Changes colors of specific elements
• Must include "recolor" and "to" in prompt
• Ideal for color adjustments

Parameters

• image_file or image_url: Source image (required)
• prompt: Description of desired changes (required)
• option: Edit mode (required)
• aspect_ratio: Desired output ratio (optional)
• creativity_strength: 1-10 scale for creativity (default: 5)
• quantity: Number of variations, 1-4 (default: 1)

Examples

Remake

import requests

url = "https://api.vimmerse.net/image/image-2-image"

payload = {
    'prompt': 'Make the shoe blue and change the wall to a sky background',
    'aspect_ratio': '16:9',
    'option': 'Remake',  # Redesign the image based on prompt
    'creativity_strength': 3,  # 1-10 scale
}
files=[
    ('image_file', ('image.png', open('/path/to/image.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Restructure

import requests

url = "https://api.vimmerse.net/image/image-2-image"

payload = {
    'prompt': 'Transform into a well-manicured shrub in an English garden',
    'aspect_ratio': '16:9',
    'creativity_strength': 3,
    'option': "Restructure"  # Completely restructures the image
}
files=[
    ('image_file', ('image.png', open('/path/to/image.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Restyle

import requests

url = "https://api.vimmerse.net/image/image-2-image"

payload = {
    'prompt': 'Transform into a majestic portrait style',
    'aspect_ratio': '16:9',
    'creativity_strength': 3,
    'option': "Restyle"  # Applies artistic style changes
}
files=[
    ('image_file', ('image.png', open('/path/to每一個.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Sketch

import requests

url = "https://api.vimmerse.net/image/image-2-image"

payload = {
    'prompt': 'Convert to a medieval castle scene',
    'aspect_ratio': '16:9',
    'creativity_strength': 3,
    'option': "Sketch"  # Converts image to sketch style
}
files=[
    ('image_file', ('image.png', open('/path/to/image.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Replace With

import requests

url = "https://api.vimmerse.net/image/image-2-image"

payload = {
    'prompt': 'Replace the shoe with a can of Pepsi',
    'aspect_ratio': '16:9',
    'creativity_strength': 3,
    'option': "ReplaceWith"
}
files=[
    ('image_file', ('image.png', open('/path/to/image.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Recolor To

import requests

url = "https://api.vimmerse.net/image/image-2-image"

payload = {
    'prompt': 'Recolor the green shirt to white',
    'aspect_ratio': '16:9',
    'creativity_strength': 3,
    'option': "RecolorTo"  # Changes colors in the image
}
files=[
    ('image_file', ('image.png', open('/path/to/image.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Generates images with elements or replaces items based on prompts.

Use Cases

• Add new elements to existing images
• Remove unwanted objects
• Replace objects with alternatives

Manipulates the background of images with three modes: remove, replace, or restyle.

Options

RemoveBackground

• Creates a transparent background (PNG format)
• Ideal for product photography and portrait editing
• Output maintains foreground elements perfectly

ReplaceBackground

• Replaces the background with a new image
• Use image2_file or image2_url to provide the replacement background
• Best for changing scenes or environments

RestyleBackground

• Applies artistic style from a reference image
• Use image2_file or image2_url to provide the style reference
• Great for creating unique visual effects

Parameters

Parameter	Type	Required	Default	Description
image_file or image_url	file/string	Yes	-	Main image with background to modify
image2_file or image2_url	file/string	Yes*	-	Background image for ReplaceBackground or RestyleBackground
option	string	Yes	-	Operation mode: "RemoveBackground", "ReplaceBackground", or "RestyleBackground"
async_mode	boolean	No	false	Enable asynchronous processing mode
webhook_url	string	No	null	URL to receive completion notification

*Required for ReplaceBackground and RestyleBackground options

Examples

Remove Background

{REMOVE_BG_EXAMPLE}

Replace Background

{REPLACE_BG_EXAMPLE}

Restyle Background

{RESTYLE_BG_EXAMPLE}

Error Handling

• 400 - Bad Request. Invalid parameters or missing required fields.
• 402 - Insufficient credits.
• 500 - Internal Server Error.

Performs various image editing operations including text removal, upscaling, expansion, and inpainting.

Available Options

RemoveText

• Automatically detects and removes text from images
• Uses AI to intelligently fill removed areas
• Perfect for cleaning up signage, watermarks, or captions

Upscale

• Increases image resolution up to 4x
• Uses super-resolution AI technology
• Maintains image quality and detail

ExpandToAspectRatio

• Expands image to match the specified aspect ratio
• Uses AI to generate realistic extended content
• Requires aspect_ratio parameter

Inpaint

• Fills in masked areas based on a text prompt
• Requires both an image and a mask file
• White areas in the mask indicate regions to fill
• Can generate multiple variations

Parameters

Parameter	Type	Required	Default	Description
image_file or image_url	file/string	Yes	-	Source image to edit
mask_file or mask_url	file/string	Yes*	-	Mask image for inpainting (required for Inpaint option)
option	string	Yes	-	Edit operation: "RemoveText", "Upscale", "ExpandToAspectRatio", or "Inpaint"
aspect_ratio	string	Yes*	-	Desired ratio for ExpandToAspectRatio (e.g., "16:9", "9:16", "1:1")
prompt	string	Yes*	-	Description for Inpaint option (what to generate in masked area)
quantity	integer	No	1	Number of variations for Inpaint. Range: 1-4
expand_method	string	No	"Outpaint"	Method for ExpandToAspectRatio: "Outpaint" or "Pad"
expand_direction	string	No	"center"	Direction for expansion: "center", "top/left", "bottom/right"
reframe_parameters	string (JSON)	No	null	JSON string for reframe parameters (grid_position_x, grid_position_y, x_start, x_end, y_start, y_end)
async_mode	boolean	No	false	Enable asynchronous processing mode
webhook_url	string	No	null	URL to receive completion notification

*Required for specific options only

Examples

Remove Text

{REMOVE_TEXT_EXAMPLE}

Upscale Image

{UPSCALE_IMAGE_EXAMPLE}

Expand Image

{EXPAND_IMAGE_EXAMPLE}

Inpaint Image

{INPAINT_IMAGE_EXAMPLE}

Error Handling

• 400 - Bad Request. Invalid parameters, missing required fields, or invalid option.
• 402 - Insufficient credits.
• 500 - Internal Server Error.

Swaps faces in an image with faces from other uploaded images.

How It Works

• Upload a main image containing the face(s) to be replaced
• Upload one or more images containing the replacement faces
• The API automatically detects and swaps faces matching the order of images

Parameters

• image_files: List of image files to upload (required if not using URLs)
• image_urls: List of image URLs (required if not using files)
• order_indices: Array of face indices to swap (optional, e.g., [0, 1])
• main_image_url: Deprecated - use image_urls instead
• human_image_url: Deprecated - use image_urls instead

Best Practices

• First image: Image containing face(s) to be replaced
• Subsequent images: Images with replacement faces
• Ensure faces are clearly visible and well-lit
• Supported formats: JPG, PNG, WebP

Example: Using File Upload

import requests

url = "https://api.vimmerse.net/image/face-swap"

files=[
    ('image_files', ('main_image.png', open('/path/to/main_image.png', 'rb'), 'image/png')),
    ('image_files', ('human1_image.jpeg', open('/path/to/human_image.jpeg', 'rb'), 'image/jpeg')),
    ('image_files', ('human2_image.jpeg', open('/path/to/second_face.jpeg', 'rb'), 'image/jpeg'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}
payload = {
    'order_indices': [0, 1]  # Optional: specify which faces to swap
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Example: Using URLs

import requests

url = "https://api.vimmerse.net/image/face-swap"

payload = {
    'image_urls': [
        "https://example.com/main_image.png",
        "https://example.com/human_image1.png",
        "https://example.com/human_image2.png"
    ],
    'order_indices': [0, 1]  # Optional
}

headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Generates a virtual try-on image by overlaying clothing onto a human subject.

How It Works

This API combines a human image and a clothing image to create a realistic visualization of how the clothing looks on the person.

Parameters

• human_image_file or human_image_url: Image of a person (required)
• clothes_image_file or clothes_image_url: Image of clothing to try on (required)
• option: Try-on method (default: "Auto")

Requirements

• Human image should feature a person in standing pose, facing forward
• Clothing image should be clear and show the garment on a plain background
• Both images should be well-lit and in focus

Example: Using File Upload

import requests

url = "https://api.vimmerse.net/image/try-on"

files=[
    ('human_image_file', ('human_image.jpeg', open('/path/to/human_image.jpeg', 'rb'), 'image/jpeg')),
    ('clothes_image_file', ('clothes_image.jpeg', open('/path/to/clothes_image.jpeg', 'rb'), 'image/jpeg'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}
payload = {}  # Optional parameters

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

Example: Using URLs

import requests

url = "https://api.vimmerse.net/image/try-on"

payload = {
    "human_image_url": "https://example.com/human_image.png",
    "clothes_image_url": "https://example.com/clothes_image.png"
}

headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Transforms images into various artistic styles using AI-powered stylization.

Available Styles

• realistic_style: Hyper-realistic rendering
• anime_style: Japanese anime aesthetic
• 3d: Three-dimensional rendering
• angel: Ethereal, angelic appearance
• japanese_comics: Manga/comic book style
• princess_style: Fairytale princess aesthetic
• dreamy: Soft, dream-like atmosphere
• ink_style: Ink wash painting effect
• monets_garden: Impressionist painting style
• new_monet_garden: Modern impressionist style
• exquisite_comic: Detailed comic art
• cyber_machinery: Futuristic tech aesthetic
• chinese_style: Traditional Chinese painting
• romantic: Soft, romantic atmosphere
• ugly_clay: Claymation stop-motion style
• cute_doll: Doll-like appearance
• 3d_gaming: Video game 3D style
• animated_movie: Animated film aesthetic
• doll: Character doll style

Parameters

• image_file or image_url: Source image (required)
• style: Artistic style to apply (required)

Example

import requests

url = "https://api.vimmerse.net/image/restyle"

payload = {
    'style': 'anime_style'  # Apply anime style transformation
}
files=[
    ('image_file', ('image.png', open('/path/to/image.png', 'rb'), 'image/png'))
]
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)