logo
Powered by Redocly

Vimmerse Rest API (1.0.0)

Download OpenAPI specification:Download

Welcome to the Vimmerse Platform API. As of June 2024, we are building the REST v2.1.0 API service to be the primary API service for the Vimmerse Platform. All services on the API will continue to be maintained.

Authentication

You will need your Vimmerse API key to make requests to this API. Make sure you never share your API key with anyone, and never commit it to a public repository. Include this key in the X-Api-Key header of your requests. You don't have to worry about authorization tokens if you have your API key. To experience our platform, you can contact us to get a free API key.

Support

If you have any questions or concerns, please reach out to us by sending an email to support@vimmerse.net.

Media

APIs for create media and get detailed information.

Here are the steps to get a new media generated from your image.

1. Create a new Media

Send a POST request to create a new media. This will return newly created media information. The request should include your API key.

import requests

url = "https://api.vimmerse.net/media"

payload = {
  'title': 'New Media example with image upload',
  'prompt': 'Generate a video that make your idea to life.',
  'sound_effects': 'Yes'
}

files=[
  ('image_files',('image.png',open('path/to/your/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)

2. Get Media Processing Status

Send a GET request to get your media processing status.

import requests

url = "https://api.vimmerse.net/media/{MEDIA_ID}/processing-status"

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

response = requests.request("GET", url, headers=headers)

print(response.text)

3. Get Media Detail

Send a GET request to get your media detail.

import requests

url = "https://api.vimmerse.net/media/{MEDIA_ID}"

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

response = requests.request("GET", url, headers=headers)

print(response.text)

Here are API details and examples of Media API.

Create Media

This API creates a new media from your image files, image URLs or text prompt. If you upload 2 images or submit with 2 image URLs, those 2 files are considered as start and end frame of the video. If you upload only 1 file or give 1 image URL, a new video will be generated from uploaded image. If you don't upload or give any image, a new video will be generated from the prompt.

Send a POST request to create a new media. This will return newly created media information. The request should include your API key.

Here are examples of how to create a media with each types of data.

Example Code

Create a new Media with two image files.

import requests

url = "https://api.vimmerse.net/media"

payload = {
  'title': 'New Media example with Two images upload'
}

files=[
  ('image_files',('start_frame.png',open('path/to/your/start_frame.png','rb'),'image/png')),
  ('image_files',('end_frame.png',open('path/to/your/end_frame.png','rb'),'image/png')), ## if you omit this line, a new video is generated by referencing only start_frame.png
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

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

print(response.text)

Create a new Media with image URLs and motion type.

import requests

url = "https://api.vimmerse.net/media"

payload = {
  'title': 'New Media example with 2 image URLs, generate 2 video with motion type.',
  'image_urls': [
      'https://example.com/path/to/your/start_frame.png',
      'https://example.com/path/to/your/end_frame.png',
    ],
  'motion_type': 'KlingAI',
  'quantity': 2
}

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

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

print(response.text)

Create a new Media with text prompt and add sound effect.

import requests

url = "https://api.vimmerse.net/media"

payload = {
  'title': 'New Media example with text prompt and sound effects.',
  'prompt': "Generate a video that bunny jumps into the forest.",
  'sound_effects': 'Yes'
}

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

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

print(response.text)
SecurityAPIKeyHeader
Request
Request Body schema: multipart/form-data
title
string (Title)
Default: ""
description
string (Description)
Default: ""
visibility_status
string (Visibility Status)
Default: "1"

Visibility status of the media. 0: Private, 1: Unlisted, 2: Public.

image_files
Array of strings <binary> (Image Files)
Default: []

Images to upload. If you upload a single image, an auto motion video will be created from that image. If you upload two images, the second image will be treated as the final frame of the video, resulting in motion transitions between the two images. The most recently uploaded image will be considered the last frame.

image_urls
Array of strings (Image URLs)
Default: []

If you upload image files, this field will be ignored.

prompt
string (Text prompt)
Default: ""

Description to generate video.

motion_type
string (Motion Type)
Default: "Auto"

Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.

quantity
integer (Quantity) [ 1 .. 4 ]
Default: 1
duration
integer (Duration of video) [ 1 .. 10 ]
Default: 5
loop
integer (The number of repetitions of the same motion.) [ 1 .. 6 ]
Default: 1
sound_effects
string (Sound Effects)
Default: "No"

Defines if the generated video will include sound effects or not. Available values are: Yes and No(default).

aspect_ratio
string (Aspect ratio)

Available values are '16:9', '4:3', '1:1', '3:4' and '9:16'

Responses
200

New Media

402

Insufficient Credit

404

Not Found

422

Validation Error

post/media
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Create Media from ImageDeprecated
This API creates a new media object with an uploaded image and process the Media with the request body. Include request data in the form data.



    

  • X-Api-Key: Your customer API key.
    • 



Request Object


    

  • image: Images to upload. If you upload a single image, an auto motion video will be created from that image. If you upload two images, the second image will be treated as the final frame of the video, resulting in motion transitions between the two images. The most recently uploaded image will be considered the last frame
    • 



Transition features are not supported for 'LedonadoMotion' and 'StableDiffusionMotion' motion types.


    

  • data: JSON string of your request data.
    • 



Parameters


You can submit the parameters by JSON-stringify the data. All fields are optional, and default values will be set automatically.


    

  • title: Title of the media.
    

    • 

  • description: Description of the media.
    

    • 

  • pose_preset: 
This parameter defines the movement of the pose and consists of MotionType and Params.
    

      

    • MotionType: Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.
      

        

      • Auto: Video motion is defined automatically based on input settings.
        • 

      • LeonardoMotion: Video motion is generated by Leonardo AI image2motion tool. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • StableVideoDiffusion: Video motion is generated by Stability's Stable Video Diffusion v2. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. When LumaAI is used, camera motion can also be defined as part of the prompt by adding "camera orbit left" for instance there. Available camera motions are: Static', 'Move Left', 'Move Right', 'Move Up', 'Move Down', 'Push In', 'Pull Out', 'Zoom In', 'Zoom Out', 'Pan Left', 'Pan Right', 'Orbit Left', 'Orbit Right', 'Crane Up', 'Crane Down'.
        • 

      • LumaRay2: Video motion is generated by Luma AI. It takes input image and prompt.
        • 

      • KlingAI: video motion is generated by Kling AI Professional model. It takes input images(i.e. optional last frames) and prompt.
        • 

      • MinimaxHailuo: video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Hunyuan: video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Wan: video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Pixverse: video motion is generated by PixVerse. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • RunwayML: video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt. It does not support motionAmount.
        • 

      • TryOnVideo: video motion applied on TryOn results with a preset prompt. It takes input images(i.e. human image and clothing image).
        • 

      • Parallax: Video motion is defined by a camera path which is specified in Params.
        • 

      

      • 

    • Params: Contains detailed values for video motion. If you have chosen the Prompt motion type, you will need to provide prompt text under Prompt in Params.
      

        

      • CameraPath: Defines the camera path of the bullet video. Only available when Parallax motion type is chosen. Available values are HorizontalArc, VerticalArc, StepIn, Cross, Circular, StepD, StepU, StepL and StepR.
        • 

      • Prompt: The prompt for movement for the bullet video. Only available when Prompt motion type is chosen.
        • 

      • PromptStrength: Defines prompt strength for video generation. Available values are 1, 2, 3, 4, or 5.
        • 

      • Quantity: The number of bullet videos to generate.
        • 

      • MotionAmount: The amount of motion, ranging from 1 to 10.
        • 

      • MotionLength: The length of the generated bullet video.
        • 

      • Loop: The number of repetitions of the same motion.
        • 

      

      • 

    

    • 

  • submit_params: 
The quality of the bullet video can be adjusted with this parameter. The default value is recommended. To use the default value, you don't need to include this parameter in the request. However, if you want to change this value, please contact us first.
    

      

    • scale_factor: Scale factor of the bullet video. Range is (0 - 2). Default value is "1".
      • 

    • pipeline_preset: Defines media processing preset. Available values are Fast and Normal. Default value is "Fast".
      • 

    • file_size: Defines maximum file size of bullet videos as a string. Unit of the size is MB. Default value is an empty string. Please input value as a string. Ex: "1.6".
      • 

    • sound_effects: Defines if the generated video will include sound effects or not. Values are: "Yes", "No" (default).
      • 

    

    • 



Example Code


This example shows how to generate videos by several motions. They are Horizontal, Cross and StepDown Parallax motions and 2 AI motions.


import requests
import json
import time
import os

API_KEY = 'YOUR_API_KEY'
BASE_URL = "https://api.vimmerse.net"
CREATE_MEDIA_UPLOAD_URL = f"{BASE_URL}/media/upload"
PROCESS_STATUS_URL_TEMPLATE = f"{BASE_URL}/media/{{media_id}}/processing-status"
DOWNLOAD_URL_TEMPLATE = f"{BASE_URL}/media/{{media_id}}/download?object_type=bullet_video_mp4&motion_type=Auto1"

headers = {
    'X-Api-Key': API_KEY,
}

# Create media request data
request_data = {
    "title": "New Media Example1",
    "pose_preset": [
        {"MotionType": "Parallax", "Params": "CameraPath=HorizontalArc|Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"},
        {"MotionType": "Parallax", "Params": "CameraPath=Cross|Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"},
        {"MotionType": "Parallax", "Params": "CameraPath=StepD|Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"},
        {"MotionType": "Auto", "Params": "Prompt=|PromptStrength=1|Quantity=2|MotionAmount=5|MotionLength=5|Loop=1"}
    ]
}

# Select files to upload
file_path = './nike_shoe.png'
files = [
    ('image', ('nike_shoe.png', open(file_path, 'rb'), 'image/png'))
]

try:
    # Send POST request to upload media
    with open(file_path, 'rb') as file:
        files = [('image', ('nike_shoe.png', file, 'image/png'))]
        payload = {"data": json.dumps(request_data)}

        response = requests.post(CREATE_MEDIA_UPLOAD_URL, headers=headers, data=payload, files=files)
        response.raise_for_status()  # Check for HTTP errors
        media_data = response.json()

    media_id = media_data['data']['id']

except requests.exceptions.RequestException as e:
    print(f"Failed to create media: {e}")
    exit()

# Wait for media processing to complete
try:
    percentage = 0
    while percentage != 100:
        time.sleep(5)
        url = PROCESS_STATUS_URL_TEMPLATE.format(media_id=media_id)
        status_response = requests.get(url, headers=headers)
        status_response.raise_for_status()
        progress_data = status_response.json()
        percentage = int(progress_data['data']['progress_percentage'])
        print(f"Media processing: {percentage}%")

except requests.exceptions.RequestException as e:
    print(f"Failed to get media processing status: {e}")
    exit()

# Download the generated bullet video
try:
    download_url = DOWNLOAD_URL_TEMPLATE.format(media_id=media_id)
    download_response = requests.get(download_url, headers=headers)
    download_response.raise_for_status()

    output_dir = "./tmp"
    os.makedirs(output_dir, exist_ok=True)
    output_path = os.path.join(output_dir, "output.mp4")

    with open(output_path, 'wb') as file:
        file.write(download_response.content)
    print(f"Downloaded video saved to {output_path}")

except requests.exceptions.RequestException as e:
    print(f"Failed to download video: {e}")



Example Code


This example shows how to use transition feature. Transition feature lets you generate videos by providing first and last frame of the image.


import requests
import json
import time
import os

API_KEY = 'YOUR_API_KEY'
BASE_URL = "https://api.vimmerse.net"
CREATE_MEDIA_UPLOAD_URL = f"{BASE_URL}/media/upload"
PROCESS_STATUS_URL_TEMPLATE = f"{BASE_URL}/media/{{media_id}}/processing-status"
DOWNLOAD_URL_TEMPLATE = f"{BASE_URL}/media/{{media_id}}/download?object_type=bullet_video_mp4&motion_type=Auto1"

headers = {
    'X-Api-Key': API_KEY,
}

# Create media request data
request_data = {
    "title": "New Media Example With Transition",
    "is_transition": "1",
    "pose_preset": [
        {
        "MotionType": "Auto",
        "Params": "Prompt=|PromptStrength=1|Quantity=2|MotionAmount=5|MotionLength=5|Loop=1"
        }
    ]
}

# Select files to upload

try:
    # Send POST request to upload media
    files=[
        ('image', ('f1.png', open('./f1.png', 'rb'), 'image/png')),
        ('image', ('f2.png', open('./f2.png', 'rb'), 'image/png'))
    ]
    payload = {"data": json.dumps(request_data)}

    response = requests.post(CREATE_MEDIA_UPLOAD_URL, headers=headers, data=payload, files=files)
    response.raise_for_status()  # Check for HTTP errors
    media_data = response.json()

    media_id = media_data['data']['id']

except requests.exceptions.RequestException as e:
    print(f"Failed to create media: {e}")
    exit()

# Wait for media processing to complete
try:
    percentage = 0
    while percentage != 100:
        time.sleep(5)
        url = PROCESS_STATUS_URL_TEMPLATE.format(media_id=media_id)
        status_response = requests.get(url, headers=headers)
        status_response.raise_for_status()
        progress_data = status_response.json()
        percentage = int(progress_data['data']['progress_percentage'])
        print(f"Media processing: {percentage}%")

except requests.exceptions.RequestException as e:
    print(f"Failed to get media processing status: {e}")
    exit()

# Download the generated bullet video
try:
    download_url = DOWNLOAD_URL_TEMPLATE.format(media_id=media_id)
    download_response = requests.get(download_url, headers=headers)
    download_response.raise_for_status()

    output_dir = "./tmp"
    os.makedirs(output_dir, exist_ok=True)
    output_path = os.path.join(output_dir, "output.mp4")

    with open(output_path, 'wb') as file:
        file.write(download_response.content)
    print(f"Downloaded video saved to {output_path}")

except requests.exceptions.RequestException as e:
    print(f"Failed to download video: {e}")



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
required
image
required
Array of strings <binary>  (Image) 
 
data
string (Data) 
 Default:  "{'title':'New media', 'description': 'Description of the new media'}"
Stringified Media Data


 
Responses 
200
New Media Object


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/media/upload
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Create Media from Text PromptDeprecated
This API creates a new media with prompt under pose_preset data. Include request data in the form data.



    

  • X-Api-Key: Your customer API key.
    • 



Request Object


You can submit prompt under pose_preset object. All fields are optional, and default values will be set automatically.


    

  • title: Title of the media.
    

    • 

  • description: Description of the media.
    

    • 

  • pose_preset: 
This parameter defines the movement of the pose and consists of MotionType and Params.
    

      

    • MotionType: Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.
      

        

      • Auto: Video motion is defined automatically based on input settings.
        • 

      • LeonardoMotion: Video motion is generated by Leonardo AI image2motion tool. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • StableVideoDiffusion: Video motion is generated by Stability's Stable Video Diffusion v2. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. When LumaAI is used, camera motion can also be defined as part of the prompt by adding "camera orbit left" for instance there. Available camera motions are: Static', 'Move Left', 'Move Right', 'Move Up', 'Move Down', 'Push In', 'Pull Out', 'Zoom In', 'Zoom Out', 'Pan Left', 'Pan Right', 'Orbit Left', 'Orbit Right', 'Crane Up', 'Crane Down'.
        • 

      • LumaRay2: Video motion is generated by Luma AI. It takes input image and prompt.
        • 

      • KlingAI: video motion is generated by Kling AI Professional model. It takes input images(i.e. optional last frames) and prompt.
        • 

      • MinimaxHailuo: video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Hunyuan: video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Wan: video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Pixverse: video motion is generated by PixVerse. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • RunwayML: video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt. It does not support motionAmount.
        • 

      • TryOnVideo: video motion applied on TryOn results with a preset prompt. It takes input images(i.e. human image and clothing image).
        • 

      • Parallax: Video motion is defined by a camera path which is specified in Params.
        • 

      

      • 

    • Params: Contains detailed values for video motion. If you have chosen the Prompt motion type, you will need to provide prompt text under Prompt in Params.
      

        

      • CameraPath: Defines the camera path of the bullet video. Only available when Parallax motion type is chosen. Available values are HorizontalArc, VerticalArc, StepIn, Cross, Circular, StepD, StepU, StepL and StepR.
        • 

      • Prompt: The prompt for movement for the bullet video. Only available when Prompt motion type is chosen.
        • 

      • PromptStrength: Defines prompt strength for video generation. Available values are 1, 2, 3, 4, or 5.
        • 

      • Quantity: The number of bullet videos to generate.
        • 

      • MotionAmount: The amount of motion, ranging from 1 to 10.
        • 

      • MotionLength: The length of the generated bullet video.
        • 

      • Loop: The number of repetitions of the same motion.
        • 

      

      • 

    

    • 

  • submit_params: 
The quality of the bullet video can be adjusted with this parameter. The default value is recommended. To use the default value, you don't need to include this parameter in the request. However, if you want to change this value, please contact us first.
    

      

    • scale_factor: Scale factor of the bullet video. Range is (0 - 2). Default value is "1".
      • 

    • pipeline_preset: Defines media processing preset. Available values are Fast and Normal. Default value is "Fast".
      • 

    • file_size: Defines maximum file size of bullet videos as a string. Unit of the size is MB. Default value is an empty string. Please input value as a string. Ex: "1.6".
      • 

    • sound_effects: Defines if the generated video will include sound effects or not. Values are: "Yes", "No" (default).
      • 

    

    • 



Example Code


This example shows how to generate videos from prompt.


import requests
import json
import time
import os

API_KEY = 'YOUR_API_KEY'
BASE_URL = "https://api.vimmerse.net"
CREATE_MEDIA_UPLOAD_URL = f"{BASE_URL}/media/prompt"
PROCESS_STATUS_URL_TEMPLATE = f"{BASE_URL}/media/{{media_id}}/processing-status"
DOWNLOAD_URL_TEMPLATE = f"{BASE_URL}/media/{{media_id}}/download?object_type=bullet_video_mp4&motion_type=Auto1"

headers = {
    'X-Api-Key': API_KEY,
}

json_headers = {
    'X-Api-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Create media request data
payload = {
  "title": "New media from prompt",
  "description": "New media from prompt",
  "pose_preset": [
    {
      "MotionType": "Auto",
      "Params": "Prompt=Shot of Nike shoes on colorful background.|PromptStrength=5|MotionAmount=5|MotionLength=5|Loop=1|Quantity=2"
    }
  ]
}

# Select files to upload

try:
    # Send POST request to upload media
    response = requests.post(CREATE_MEDIA_UPLOAD_URL, headers=json_headers, json=payload)
    response.raise_for_status()  # Check for HTTP errors
    media_data = response.json()

    media_id = media_data['data']['id']

except requests.exceptions.RequestException as e:
    print(f"Failed to create media: {e}")
    exit()

# Wait for media processing to complete
try:
    percentage = 0
    while percentage != 100:
        time.sleep(5)
        url = PROCESS_STATUS_URL_TEMPLATE.format(media_id=media_id)
        status_response = requests.get(url, headers=headers)
        status_response.raise_for_status()
        progress_data = status_response.json()
        percentage = int(progress_data['data']['progress_percentage'])
        print(f"Media processing: {percentage}%")

except requests.exceptions.RequestException as e:
    print(f"Failed to get media processing status: {e}")
    exit()

# Download the generated bullet video
try:
    download_url = DOWNLOAD_URL_TEMPLATE.format(media_id=media_id)
    download_response = requests.get(download_url, headers=headers)
    download_response.raise_for_status()

    output_dir = "./tmp"
    os.makedirs(output_dir, exist_ok=True)
    output_path = os.path.join(output_dir, "output.mp4")

    with open(output_path, 'wb') as file:
        file.write(download_response.content)
    print(f"Downloaded video saved to {output_path}")

except requests.exceptions.RequestException as e:
    print(f"Failed to download video: {e}")



SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
Title (string) or Title (null) (Title) 
 
Description (string) or Description (null) (Description) 
 
Primary User ID (string) or Primary User ID (null) (Primary User ID) 
Utilize the primary_user_id parameter to determine the owner of the Media. If the primary_user_id value is not included in the request object, it will default to your customer_id.


 
Rating (string) or Rating (null) (Rating) 
Rated value. If empty, this media is not rated.


 
Webhook URL is called when status of the media has been updated. (string) or Webhook URL is called when status of the media has been updated. (null) (Webhook URL is called when status of the media has been updated.) 
 
Array of Pose Preset (any) or Pose Preset (object) or Pose Preset (null) (Pose Preset) 
Pose preset parameter. Can be either a list or a PosePreset.


 
Submit Parameters (object) or Submit Parameters (null) (Submit Parameters) 
Submitting parameters.


 
Responses 
200
New Text Prompt Media Object


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/media/prompt
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Get Media Processing Status
This API retrieves media processing status in percentage.


Send a GET request to get media processing status.


Example Code


Get processing status of the media.


import requests

url = "https://api.vimmerse.net/media/{MEDIA_ID}/processing-status"

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

response = requests.request("GET", url, headers=headers)

print(response.text)



Responses 
200
Media progress percentage


404
Not Found


422
Validation Error


get/media/{media_id}/processing-status
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Get Media
This API retrieves a media object.


Send a GET request to get your media.


Example Code


Read Media example.


import requests

url = "http://api.vimmerse.net/media/{MEDIA_ID}"

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

response = requests.request("GET", url, headers=headers)

print(response.text)



SecurityAPIKeyHeader 
Responses 
200
Media Object


404
Media Not Found


422
Validation Error


get/media/{media_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Update Media
This API updates media and resubmit again if you update any of prompt, motion_type, quantity, duration, loop, aspect_ratio and sound_effects.
If media is processed again, it will reduce your credit.


Send a PUT request to update your media. This will return updated media. The request should include your API key.


Example Code


Update Media without resubmitting example


import requests

url = "http://api.vimmerse.net/media/{MEDIA_ID}/edit"

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

payload = {
    'title': 'New Updated Title',
    'rating: '5',
    'visibility_status': '2'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)



Update Media with resubmitting example


import requests

url = "http://api.vimmerse.net/media/{MEDIA_ID}/edit"

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

payload = {
    'title': 'New Updated Title',
    'motion_type: 'RunwayML',
    'duration': 9
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/x-www-form-urlencoded
title
string (Title) 
 
description
string (Description) 
 
rating
string (Rating) 
 
visibility_status
string (Visibility Status) 
Visibility status of the media. 0: Private, 1: Unlisted, 2: Public.


 
prompt
string (Text prompt) 
Description to generate video.


 
motion_type
string (Motion Type) 
Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 
duration
integer (Duration of video)   [ 1 .. 10 ] 
 
loop
integer (The number of repetitions of the same motion.)   [ 1 .. 6 ] 
 
aspect_ratio
string (Aspect ratio) 
Available values are '16:9', '4:3', '1:1', '3:4' and '9:16'


 
sound_effects
string (Sound Effects) 
Defines if the generated video will include sound effects or not. Available values are: Yes and No(default).


 
Responses 
200
Media Object


400
Bad Request


402
Insufficient Credit


404
Not Found


422
Validation Error


put/media/{media_id}/edit
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Download FileDeprecated
Downloads file from media.


Example Code


This code shows an example of how to download Bullet Video from Auto motion.


import requests

url = "https://api.vimmerse.net/media/{MEDIA_ID}/download?object_type=bullet_video_mp4&motion_type=Auto"

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

response = requests.request("GET", url, headers=headers)

print(response.text)



This code shows an example of how to download Bullet Video with custom settings


import requests

url = "https://api.vimmerse.net/media/{MEDIA_ID}/download?object_type=bullet_video_mp4&motion_type=Auto&width=1080&file_size=4"

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

response = requests.request("GET", url, headers=headers)

print(response.text)



SecurityAPIKeyHeader 
Responses 
200
Return bullet video, gif or source files.


400
Bad Request


422
Validation Error


get/media/{media_id}/download
Request samples 
Response samples 
null
Process Media
This API resubmit to generate a bullet video.


Example Code


Send a POST request without body to resubmit your media.


import requests

url = "https://api.vimmerse.net/media/{MEDIA_ID}/process"

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

response = requests.request("POST", url, headers=headers)

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
object (Req) 
 
Responses 
200
Media Object


400
Bad Request


402
Insufficient Credit


404
Not Found


422
Validation Error


post/media/{media_id}/process
Request samples 
Response samples 
application/json
{
  • "data": { }
}
Batch
APIs for processing batches and get detailed information.


Create Batch
This API creates a new Batch object and process all given images.


Send a POST request to create a new Batch.


SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
title
string (Title) 
 Default:  ""
 
description
string (Description) 
 Default:  ""
 
visibility_status
string (Visibility Status) 
 Default:  "1"
Visibility status of the batch. 0: Private, 1: Unlisted, 2: Public.


 
image_files
Array of strings <binary>  (Image Files) 
 Default:  []
Images to upload. If you upload a single image, an auto motion video will be created from that image. If you upload two images, the second image will be treated as the final frame of the video, resulting in motion transitions between the two images. The most recently uploaded image will be considered the last frame.


 
image_urls
Array of strings (Image URLs) 
 Default:  []
If you upload image files, this field will be ignored.


 
is_transition
string (Is Transition) 
 Default:  ""
If you set to 1, you will get transition images between given images.


 
prompt
string (Text prompt) 
 Default:  ""
Description to generate video.


 
motion_type
string (Motion Type) 
 Default:  "Auto"
Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 Default:  1
 
duration
integer (Duration of video)   [ 1 .. 10 ] 
 Default:  5
 
loop
integer (The number of repetitions of the same motion.)   [ 1 .. 6 ] 
 Default:  1
 
aspect_ratio
string (Aspect ratio) 
Available values are '16:9', '4:3', '1:1', '3:4' and '9:16'


 
sound_effects
string (Sound Effects) 
 Default:  "No"
Defines if the generated video will include sound effects or not. Available values are: Yes and No(default).


 
Responses 
200
New Batch Object


422
Validation Error


post/batch
Request samples 
Response samples 
application/json
{
  • "id": "",
  • "email": "",
  • "manager_id": "",
  • "customer_id": "vimmerse-product",
  • "title": "",
  • "description": "",
  • "visibility_status": "1",
  • "idea": "",
  • "storyboard": { },
  • "scenes": [ ],
  • "message": "",
  • "note": "",
  • "feedback": "",
  • "is_transition": "",
  • "filenames": [ ],
  • "files": [ ],
  • "medias": [ ],
  • "upload_urls": { },
  • "finished_medias": [ ],
  • "failed_medias": [ ],
  • "pose_preset": [
    ],
  • "submit_params": {
    },
  • "progress_percentage": 0,
  • "status": "new",
  • "generate_type": "GENERATE_VIDEO",
  • "version": "2",
  • "created_at": "",
  • "updated_at": ""
}
Create Batch with UploadDeprecated
This API creates a new Batch object with uploaded images and processes with the uploaded images. To change submit parameters and pose presets, include them in the form data.



    

  • X-Api-Key: Your customer API key.
    • 



Request Object


    

  • images: Images to upload.
    • 

  • data: JSON string of your request data.
    • 



Parameters


You can submit the parameters by JSON-stringify the data. All fields are optional, and default values will be set automatically.


    

  • pose_preset: 
This parameter defines the movement of the pose and consists of MotionType and Params.
    

      

    • MotionType: Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.
      

        

      • Auto: Video motion is defined automatically based on input settings.
        • 

      • LeonardoMotion: Video motion is generated by Leonardo AI image2motion tool. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • StableVideoDiffusion: Video motion is generated by Stability's Stable Video Diffusion v2. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. When LumaAI is used, camera motion can also be defined as part of the prompt by adding "camera orbit left" for instance there. Available camera motions are: Static', 'Move Left', 'Move Right', 'Move Up', 'Move Down', 'Push In', 'Pull Out', 'Zoom In', 'Zoom Out', 'Pan Left', 'Pan Right', 'Orbit Left', 'Orbit Right', 'Crane Up', 'Crane Down'.
        • 

      • LumaRay2: Video motion is generated by Luma AI. It takes input image and prompt.
        • 

      • KlingAI: video motion is generated by Kling AI Professional model. It takes input images(i.e. optional last frames) and prompt.
        • 

      • MinimaxHailuo: video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Hunyuan: video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Wan: video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Pixverse: video motion is generated by PixVerse. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • RunwayML: video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt. It does not support motionAmount.
        • 

      • TryOnVideo: video motion applied on TryOn results with a preset prompt. It takes input images(i.e. human image and clothing image).
        • 

      • Parallax: Video motion is defined by a camera path which is specified in Params.
        • 

      

      • 

    • Params: Contains detailed values for video motion. If you have chosen the Prompt motion type, you will need to provide prompt text under Prompt in Params.
      

        

      • CameraPath: Defines the camera path of the bullet video. Only available when Parallax motion type is chosen. Available values are HorizontalArc, VerticalArc, StepIn, Cross, Circular, StepD, StepU, StepL and StepR.
        • 

      • Prompt: The prompt for movement for the bullet video. Only available when Prompt motion type is chosen.
        • 

      • PromptStrength: Defines prompt strength for video generation. Available values are 1, 2, 3, 4, or 5.
        • 

      • Quantity: The number of bullet videos to generate.
        • 

      • MotionAmount: The amount of motion, ranging from 1 to 10.
        • 

      • MotionLength: The length of the generated bullet video.
        • 

      • Loop: The number of repetitions of the same motion.
        • 

      

      • 

    

    • 

  • submit_params: 
The quality of the bullet video can be adjusted with this parameter. The default value is recommended. To use the default value, you don't need to include this parameter in the request. However, if you want to change this value, please contact us first.
    

      

    • scale_factor: Scale factor of the bullet video. Range is (0 - 2). Default value is "1".
      • 

    • pipeline_preset: Defines media processing preset. Available values are Fast and Normal. Default value is "Fast".
      • 

    • file_size: Defines maximum file size of bullet videos as a string. Unit of the size is MB. Default value is an empty string. Please input value as a string. Ex: "1.6".
      • 

    • sound_effects: Defines if the generated video will include sound effects or not. Values are: "Yes", "No" (default).
      • 

    

    • 



Example Code


This example shows how to create a new Batch with several motions. They are Horizontal, Cross and StepDown Parallax motions and 2 AI motions.


import requests
import json

url = "https://api.vimmerse.net/batch/upload"

batch_data = {
  "title": "New Batch Example1",
  "pose_preset": [
    {
      "MotionType": "Parallax",
      "Params": "CameraPath=HorizontalArc|Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"
    },
    {
      "MotionType": "Parallax",
      "Params": "CameraPath=Cross|Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"
    },
    {
      "MotionType": "Parallax",
      "Params": "CameraPath=StepD|Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"
    },
    {
      "MotionType": "Auto",
      "Params": "Prompt=|PromptStrength=1|Quantity=2|MotionAmount=5|MotionLength=5|Loop=1"
    }
  ]
}

payload = {
  "data": json.dumps(batch_data)
}

files=[
  ('images', ('f1.png', open('/path/to/f1.png', 'rb'), 'image/png')),
  ('images', ('f2.png', open('/path/to/f2.png', 'rb'), 'image/png')),
  ('images', ('f3.png', open('/path/to/f3.png', 'rb'), 'image/png')),
]

headers = {
  'Accept': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

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

print(response.text)



Example Code


This example shows how to create a new Batch with transition features. This code will generate 6 medias and start and stop frame of each media will be like this.
[f1.png -> f2.png], [f2.png -> f3.png], [f3.png -> f4.png], [f4.png -> f5.png], [f5.png -> f6.png], [f6.png -> f1.png]


import requests
import json

url = "https://api.vimmerse.net/batch/upload"

payload = {
  "data": json.dumps({
    "title": "New Batch Example2",
    "is_transition": "1",
    "pose_preset": [
      {
        "MotionType": "Auto",
        "Params": "Prompt=|PromptStrength=1|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"
      }
    ]
  })
}

files=[
  ('images', ('f1.png', open('/path/to/f1.png', 'rb'), 'image/png')),
  ('images', ('f2.png', open('/path/to/f2.png', 'rb'), 'image/png')),
  ('images', ('f3.png', open('/path/to/f3.png', 'rb'), 'image/png')),
  ('images', ('f4.png', open('/path/to/f4.png', 'rb'), 'image/png')),
  ('images', ('f5.png', open('/path/to/f5.png', 'rb'), 'image/png')),
  ('images', ('f6.png', open('/path/to/f6.png', 'rb'), 'image/png'))
]

headers = {
  'Accept': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
required
data
required
string (Data) 
 
images
required
Array of strings <binary>  (Images) 
 
Responses 
200
New Batch Object


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/batch/upload
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Get Batch Detail
This API retrieves a Batch/Story object.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



status field shows current progressing status of this Batch/Story.
if Batch/Story is finished, you can get composed video from video_url.


SecurityAPIKeyHeader 
Responses 
200
Batch Object


400
Bad Request


422
Validation Error


get/batch/{batch_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Update Batch (Legacy)Deprecated
This API updates a Batch object with your request.


Send a PUT request to update your batch.


SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
Title (string) or Title (null) (Title) 
 
Description (string) or Description (null) (Description) 
 
Visibility Status (string) or Visibility Status (null) (Visibility Status) 
 
Array of Storyboard (any) or Storyboard (null) (Storyboard) 
 
Note (string) or Note (null) (Note) 
 
Industry (string) or Industry (null) (Industry) 
 
Message (string) or Message (null) (Message) 
 
Feedback (string) or Feedback (null) (Feedback) 
 
Transition flag (string) or Transition flag (null) (Transition flag) 
Value is '1' if batch is a transition


 
Manager ID (string) or Manager ID (null) (Manager ID) 
Utilize the manager_id parameter to determine the owner of the Batch.


 
Array of Pose Presets (any) or Pose Presets (null) (Pose Presets) 
Pose preset parameter.


 
Submit Parameters (object) or Submit Parameters (null) (Submit Parameters) 
Submitting parameters.


 
Generate Type (string) or Generate Type (null) (Generate Type) 
GENERATE_ALL: Generate video from image.
GENERATE_VIDEO: Regenerate video from previously processed media.


 
Responses 
200
Batch Object


400
Bad Request


422
Validation Error


put/batch/{batch_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Update Batch
This API updates a Batch object with your request.


Send a PUT request to update your batch.


SecurityAPIKeyHeader 
Request 
Request Body schema: application/x-www-form-urlencoded
title
string (Title) 
 
description
string (Description) 
 
visibility_status
string (Visibility Status) 
 Default:  "1"
Visibility status of the batch. 0: Private, 1: Unlisted, 2: Public.


 
prompt
string (Text prompt) 
Description to generate video.


 
motion_type
string (Motion Type) 
Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 
duration
integer (Duration of video)   [ 1 .. 10 ] 
 
loop
integer (The number of repetitions of the same motion.)   [ 1 .. 6 ] 
 
aspect_ratio
string (Aspect ratio) 
Available values are '16:9', '4:3', '1:1', '3:4' and '9:16'


 
sound_effects
string (Sound Effects) 
Defines if the generated video will include sound effects or not. Available values are: Yes and No(default).


 
Responses 
200
Batch Object


400
Bad Request


422
Validation Error


put/batch/{batch_id}/edit
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Concat Batch
This API requests to concat all videos from batch. You can get composed video from batch page after videos are composed.


You can just request with batch_id and empty body.


SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
object (Concat Request) 
 
Responses 
200
Batch Object


422
Validation Error


post/batch/{batch_id}/concat
Request samples 
Response samples 
application/json
{
  • "id": "",
  • "email": "",
  • "manager_id": "",
  • "customer_id": "vimmerse-product",
  • "title": "",
  • "description": "",
  • "visibility_status": "1",
  • "idea": "",
  • "storyboard": { },
  • "scenes": [ ],
  • "message": "",
  • "note": "",
  • "feedback": "",
  • "is_transition": "",
  • "filenames": [ ],
  • "files": [ ],
  • "medias": [ ],
  • "upload_urls": { },
  • "finished_medias": [ ],
  • "failed_medias": [ ],
  • "pose_preset": [
    ],
  • "submit_params": {
    },
  • "progress_percentage": 0,
  • "status": "new",
  • "generate_type": "GENERATE_VIDEO",
  • "version": "2",
  • "created_at": "",
  • "updated_at": ""
}
Story
APIs for generating story video from your idea or from your story and image. APIs from Story are alpha version.


Create Story from Idea
This API creates a story from your idea.


**Name** indicates an object from characters, objects and environments, Please be careful to edit them when you submit content with story.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



Request Object


    

  • idea: Your idea to generate story.
    • 

  • scene_count: Number of scenes to be generated. Optional.
    • 



Generate storyboard example


import requests

url = "https://api.vimmerse.net/story"

payload = {
  "idea": "suited man walking on the street",
  "scene_count": 2,
}
headers = {
  'Content-Type': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
idea
string (Idea) 
 Default:  ""
Your idea to generate story.


 
Number of Scenes (integer) or Number of Scenes (null) (Number of Scenes) 
Number of scenes to be generated. If you don't put any value, scenes will be generated automatically.


 
Responses 
200
New Story Object


400
Bad Request


422
Validation Error


post/story
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Create Scene Images
This API crafts images from your story.


If you give your image URL, new images will be generated by referencing your image url.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



Request Object


    

  • storyboard: Your storyboard.
    • 

  • aspect_ratio: Aspect ratio of your image.
    • 

  • option: AI option to generate image from story. Available options are StableDiffusion3.5, Flux1.1Pro and Flux1.1ProUltra. Default is Flux1.1Pro.
    • 

  • seed: Seed to generate your image.
    • 



Generate image example


import requests

url = "https://api.vimmerse.net/story/story_id/images"

payload = {
  "storyboard": {
    "characters": [
      {
        "name": "John",
        "description": "A tall, middle-aged man standing. He has short, neatly trimmed black hair with a slight sprinkle of grey. His face is clean-shaven, accentuating a strong jawline and deep-set brown eyes. He wears a dark blue tailored suit with a crisp white shirt and a deep red tie. Polished black leather shoes and a silver watch complete his ensemble. Age 45, Male."
      }
    ],
    "environments": [
      {
        "name": "City Street",
        "description": "A busy downtown street lined with tall skyscrapers and filled with a mix of cars, buses, and pedestrians. The pavements are bustling with people in business attire hurrying to their destinations. The street is clean with rays of sunlight casting shadows of the towering buildings. Large billboards and storefronts add a lively and vibrant atmosphere to the scene."
      }
    ],
    "objects": [
      {
        "name": "Briefcase",
        "description": "A sleek black leather briefcase with a matte finish. It has a shiny silver clasp and a monogram with the initials 'J.D.' embossed in one corner. The edges are slightly worn, revealing its frequent use but well-maintained condition."
      }
    ],
    "scenes": [
      {
        "title": "Scene 1: Start of the Day",
        "description": "A medium shot of **John** walking down the **City Street**. He holds a **Briefcase** in his right hand. The morning sun illuminates part of the scene, casting a warm glow on the bustling environment. Pedestrians in the background swarm past him, creating a contrast between movement and his calm stride.",
      },
      {
        "title": "Scene 2: Mid-Day Pause",
        "description": "A medium shot of **John** taking a short break near a small park on the side of the **City Street**. He stands beside a street vendor cart, the greenery of the park and the towering buildings behind him creating a picturesque urban setting.",
      }
    ]
  }
}

headers = {
  'Content-Type': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
object (Storyboard) 
Storyboard object that contains 'characters', 'environments', 'objects' and 'scenes'.


 
AI option to generate image from story. Available options are `StableDiffusion3.5`, `Flux1.1Pro` and `Flux1.1ProUltra`. Default is `Flux1.1Pro`. (string) or AI option to generate image from story. Available options are `StableDiffusion3.5`, `Flux1.1Pro` and `Flux1.1ProUltra`. Default is `Flux1.1Pro`. (null) (AI option to generate image from story. Available options are `StableDiffusion3.5`, `Flux1.1Pro` and `Flux1.1ProUltra`. Default is `Flux1.1Pro`.) 
 Default:  "Flux1.1Pro"
 
Aspect Ratio (string) or Aspect Ratio (null) (Aspect Ratio) 
 Default:  "16:9"
Aspect ratio of generating image.


 
Seed (integer) or Seed (null) (Seed) 
Seed is used to generate image from your story.


 
Responses 
200
Story with generated scene images


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/story/{story_id}/images
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Submit Story Video
This API creates a new Story object.
You can see medias generated from response and once all medias are finished, video_url for your story will be available.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



Request Object


    

  • title: Title of your story.
    

    • 

  • idea: Idea of your story. This field is optional.
    

    • 

  • storyboard: Your story.
    

    • 

  • scenes: List of scenes to generate video. Each scene should contain "image_url" that generated from story.
    

    • 

  • is_transition: You can set '1' if you need transition feature.
    

    • 

  • pose_preset: 
This parameter defines the movement of the pose and consists of MotionType and Params.
    

      

    • MotionType: Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.
      

        

      • Auto: Video motion is defined automatically based on input settings.
        • 

      • LeonardoMotion: Video motion is generated by Leonardo AI image2motion tool. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • StableVideoDiffusion: Video motion is generated by Stability's Stable Video Diffusion v2. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. When LumaAI is used, camera motion can also be defined as part of the prompt by adding "camera orbit left" for instance there. Available camera motions are: Static', 'Move Left', 'Move Right', 'Move Up', 'Move Down', 'Push In', 'Pull Out', 'Zoom In', 'Zoom Out', 'Pan Left', 'Pan Right', 'Orbit Left', 'Orbit Right', 'Crane Up', 'Crane Down'.
        • 

      • LumaRay2: Video motion is generated by Luma AI. It takes input image and prompt.
        • 

      • KlingAI: video motion is generated by Kling AI Professional model. It takes input images(i.e. optional last frames) and prompt.
        • 

      • MinimaxHailuo: video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Hunyuan: video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Wan: video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Pixverse: video motion is generated by PixVerse. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • RunwayML: video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt. It does not support motionAmount.
        • 

      • TryOnVideo: video motion applied on TryOn results with a preset prompt. It takes input images(i.e. human image and clothing image).
        • 

      • Parallax: Video motion is defined by a camera path which is specified in Params.
        • 

      

      • 

    • Params: Contains detailed values for video motion. If you have chosen the Prompt motion type, you will need to provide prompt text under Prompt in Params.
      

        

      • CameraPath: Defines the camera path of the bullet video. Only available when Parallax motion type is chosen. Available values are HorizontalArc, VerticalArc, StepIn, Cross, Circular, StepD, StepU, StepL and StepR.
        • 

      • Prompt: The prompt for movement for the bullet video. Only available when Prompt motion type is chosen.
        • 

      • PromptStrength: Defines prompt strength for video generation. Available values are 1, 2, 3, 4, or 5.
        • 

      • Quantity: The number of bullet videos to generate.
        • 

      • MotionAmount: The amount of motion, ranging from 1 to 10.
        • 

      • MotionLength: The length of the generated bullet video.
        • 

      • Loop: The number of repetitions of the same motion.
        • 

      

      • 

    

    • 



Create Story Example


import requests

url = "https://api.vimmerse.net/story/story_id/videos"

payload = {
  "storyboard": {
    "characters": [
      {
        "name": "John",
        "description": "A tall, middle-aged man standing at 6'2''. He has short, neatly trimmed black hair with a slight sprinkle of grey. His face is clean-shaven, accentuating a strong jawline and deep-set brown eyes. He wears a dark blue tailored suit with a crisp white shirt and a deep red tie. Polished black leather shoes and a silver watch complete his ensemble. Age 45, Male."
      }
    ],
    "environments": [
      {
        "name": "City Street",
        "description": "A busy downtown street lined with tall skyscrapers and filled with a mix of cars, buses, and pedestrians. The pavements are bustling with people in business attire hurrying to their destinations. The street is clean with rays of sunlight casting shadows of the towering buildings. Large billboards and storefronts add a lively and vibrant atmosphere to the scene."
      }
    ],
    "objects": [
      {
        "name": "Briefcase",
        "description": "A sleek black leather briefcase with a matte finish. It has a shiny silver clasp and a monogram with the initials 'J.D.' embossed in one corner. The edges are slightly worn, revealing its frequent use but well-maintained condition."
      }
    ],
    "scenes": [
      {
        "title": "Scene 1: Start of the Day",
        "description": "A medium shot of **John** walking down the **City Street**. He holds a **Briefcase** in his right hand. The morning sun illuminates part of the scene, casting a warm glow on the bustling environment. Pedestrians in the background swarm past him, creating a contrast between movement and his calm stride.",
      },
      {
        "title": "Scene 2: Mid-Day Pause",
        "description": "A medium shot of **John** taking a short break near a small park on the side of the **City Street**. He stands beside a street vendor cart, the greenery of the park and the towering buildings behind him creating a picturesque urban setting.",
      }
    ]
  },
  "scenes": [
    {
      "image_url": "https://dev-media.vimmerse.net/vimmerse-test-user/ai_images/1wa7alz/story2video1.png"
    },
    {
      "image_url": "https://dev-media.vimmerse.net/vimmerse-test-user/ai_images/1wa7alz/story2video2.png"
    }
  ]
}
headers = {
  'Content-Type': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/x-www-form-urlencoded
title
string (Title) 
 Default:  ""
 
idea
string (Story Idea) 
 
storyboard
object (Storyboard) 
 
scenes
Array of any (List of scenes with image urls. Available option of each scene are `image_url` and `image2_url`. If you put both URLs, it will generate transit video.) 
 
is_transition
string (Transition flag) 
 Default:  ""
If you set to 1, you will get transition images between given images.


 
prompt
string (Text prompt) 
 Default:  ""
Description to generate video.


 
motion_type
string (Motion Type) 
 Default:  "Auto"
Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 Default:  1
 
duration
integer (Duration of video)   [ 1 .. 10 ] 
 Default:  5
 
loop
integer (The number of repetitions of the same motion.)   [ 1 .. 6 ] 
 Default:  1
 
sound_effects
string (Sound Effects) 
 Default:  "No"
Defines if the generated video will include sound effects or not. Available values are: Yes and No(default).


 
Responses 
200
Story Object


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/story/{story_id}/videos
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Create Video from Idea
This API creates a new Story object from idea directly.
You can see medias generated from response and once all medias are finished, video_url for your story will be available.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



Request Object


    

  • title: Title of your story.
    

    • 

  • idea: Idea of your story. This field is optional.
    

    • 

  • is_transition: You can set '1' if you need transition feature.
    

    • 

  • aspect_ratio: Aspect ratio of the generating video.
    

    • 

  • option: AI option to generate image from story. Available options are StableDiffusion3.5, Flux1.1Pro and Flux1.1ProUltra. Default is Flux1.1Pro.
    

    • 

  • scene_count: Number of scenes to be generated.
    

    • 

  • seed: Seed to generate image.
    

    • 

  • pose_preset: 
This parameter defines the movement of the pose and consists of MotionType and Params.
    

      

    • MotionType: Defines the type of motion. Available values are: Auto, StableVideoDiffusion, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.
      

        

      • Auto: Video motion is defined automatically based on input settings.
        • 

      • LeonardoMotion: Video motion is generated by Leonardo AI image2motion tool. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • StableVideoDiffusion: Video motion is generated by Stability's Stable Video Diffusion v2. It only takes input image and motionAmount. It doesnot support transition frame, prompt.
        • 

      • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. When LumaAI is used, camera motion can also be defined as part of the prompt by adding "camera orbit left" for instance there. Available camera motions are: Static', 'Move Left', 'Move Right', 'Move Up', 'Move Down', 'Push In', 'Pull Out', 'Zoom In', 'Zoom Out', 'Pan Left', 'Pan Right', 'Orbit Left', 'Orbit Right', 'Crane Up', 'Crane Down'.
        • 

      • LumaRay2: Video motion is generated by Luma AI. It takes input image and prompt.
        • 

      • KlingAI: video motion is generated by Kling AI Professional model. It takes input images(i.e. optional last frames) and prompt.
        • 

      • MinimaxHailuo: video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Hunyuan: video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Wan: video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • Pixverse: video motion is generated by PixVerse. It takes input image and prompt. It does not support motionAmount nor a transition frame.
        • 

      • RunwayML: video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt. It does not support motionAmount.
        • 

      • TryOnVideo: video motion applied on TryOn results with a preset prompt. It takes input images(i.e. human image and clothing image).
        • 

      • Parallax: Video motion is defined by a camera path which is specified in Params.
        • 

      

      • 

    • Params: Contains detailed values for video motion. If you have chosen the Prompt motion type, you will need to provide prompt text under Prompt in Params.
      

        

      • CameraPath: Defines the camera path of the bullet video. Only available when Parallax motion type is chosen. Available values are HorizontalArc, VerticalArc, StepIn, Cross, Circular, StepD, StepU, StepL and StepR.
        • 

      • Prompt: The prompt for movement for the bullet video. Only available when Prompt motion type is chosen.
        • 

      • PromptStrength: Defines prompt strength for video generation. Available values are 1, 2, 3, 4, or 5.
        • 

      • Quantity: The number of bullet videos to generate.
        • 

      • MotionAmount: The amount of motion, ranging from 1 to 10.
        • 

      • MotionLength: The length of the generated bullet video.
        • 

      • Loop: The number of repetitions of the same motion.
        • 

      

      • 

    

    • 



Create Story from Idea Example


import requests

url = "https://api.vimmerse.net/story/idea-2-video"

payload = {
  "title": "Idea 2 Video Example",
  "idea": "suited man walking on the street in 2 scenes"
}
headers = {
  'Content-Type': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
Title (string) or Title (null) (Title) 
 Default:  ""
 
idea
string (Your idea of the Story) 
 Default:  ""
 
Transition flag (string) or Transition flag (null) (Transition flag) 
 Default:  ""
Value is '1' if batch is a transition


 
Array of Pose Presets (any) or Pose Presets (null) (Pose Presets) 
 Default:  [{"MotionType":"Auto","Params":"Prompt=|Quantity=1|MotionAmount=5|MotionLength=5|Loop=1"}]
Pose preset parameter.


 
Submit params (object) or Submit params (null) (Submit params) 
 Default:  {"scale_factor":"1","pipeline_preset":"Fast","file_size":"","sound_effects":"No"}
Submit params parameter.


 
Aspect Ratio (string) or Aspect Ratio (null) (Aspect Ratio) 
 Default:  "16:9"
 
Seed (integer) or Seed (null) (Seed) 
Seed is used to generate image from your story.


 
Number of Scenes (integer) or Number of Scenes (null) (Number of Scenes) 
Number of scenes to be generated. If you don't put any value, scenes will be generated automatically.


 
AI option to generate image from story. Available options are `StableDiffusion3.5`, `Flux1.1Pro` and `Flux1.1ProUltra`. Default is `Flux1.1Pro`. (string) or AI option to generate image from story. Available options are `StableDiffusion3.5`, `Flux1.1Pro` and `Flux1.1ProUltra`. Default is `Flux1.1Pro`. (null) (AI option to generate image from story. Available options are `StableDiffusion3.5`, `Flux1.1Pro` and `Flux1.1ProUltra`. Default is `Flux1.1Pro`.) 
 Default:  "Flux1.1Pro"
 
Responses 
200
Story Object


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/story/idea-2-video
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Get Story Detail
This API retrieves a Batch/Story object.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



status field shows current progressing status of this Batch/Story.
if Batch/Story is finished, you can get composed video from video_url.


SecurityAPIKeyHeader 
Responses 
200
Story Object


400
Bad Request


422
Validation Error


get/story/{story_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Concat Story
This API requests to concat all videos from story. You can get concat video from story page after videos are generated.


You can just request with story_id and empty body.


SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
object (Concat Request) 
 
Responses 
200
Story Object


422
Validation Error


post/story/story/{story_id}/concat
Request samples 
Response samples 
application/json
{
  • "id": "",
  • "email": "",
  • "manager_id": "",
  • "customer_id": "vimmerse-product",
  • "title": "",
  • "description": "",
  • "visibility_status": "1",
  • "idea": "",
  • "storyboard": { },
  • "scenes": [ ],
  • "message": "",
  • "note": "",
  • "feedback": "",
  • "is_transition": "",
  • "filenames": [ ],
  • "files": [ ],
  • "medias": [ ],
  • "upload_urls": { },
  • "finished_medias": [ ],
  • "failed_medias": [ ],
  • "pose_preset": [
    ],
  • "submit_params": {
    },
  • "progress_percentage": 0,
  • "status": "new",
  • "generate_type": "GENERATE_VIDEO",
  • "version": "2",
  • "created_at": "",
  • "updated_at": ""
}
Image
APIs for generating and editing images.


Generate Image from Text Prompt
You can generate and download images from your text prompt.



    

  • X-Api-Key: Your customer API key.
    • 

  • Content-Type: application/json
    • 



Request Object


    

  • prompt: Prompt string that describes on your image. Example: Shot of Nike shoes on colorful background.
    • 

  • quantity: Number of the images that you want to craft. Available values are integers from 1 to 4.
    • 

  • option: Available options are StableDiffusion3.5, LeonardoImage, Flux1, Flux1.1Pro, Flux1.1ProUltra and Auto. If you choose Auto, one of them will be chosen automatically.
    • 

  • aspect_ratio: Aspect ratio of generating image(s).
    • 



Example Code


Generate image from text prompt.


import requests

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

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
  "quantity": 3,
  "prompt": "Shot of Nike shoes on colorful background.",
  "option": "Auto",
  "aspect_ratio": "16:9"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: application/json
required
prompt
string (Text Prompt) 
 Default:  "Shot of Nike shoes on colorful background"
Text prompt to generate image.


 
quantity
integer (Number of Images)   [ 1 .. 4 ] 
 Default:  1
Numbe of Images to generate. Available values are integers from 1 to 4.


 
option
string (Option) 
 Default:  "Auto"
Available options are StableDiffusion3.5, LeonardoImage, Flux1 and Auto. If you choose Auto, one of them will be chosen automatically.


 
aspect_ratio
string (Aspect Ratio) 
 Default:  "16:9"
Aspect ratio of generating image(s).


 
Responses 
200
New Image URLs


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/image/text-2-image
Request samples 
Response samples 
Generate Images from Image
You can generate image(s) from base image and text prompt that describes changes to your base image.
You can upload your base image by using image_file or put public image URL into image_url field.


Example Code


Generate text prompt from image.


import requests

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

payload = {
  'prompt': 'Make shoe blue and look more real like in the shop.',
  'quantity': 2,
  'creativity_strength': 3,
  'aspect_ratio': '4:3',
  'option': 'Flux1'
}
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)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
image
string <binary>  (Base image) 
Upload the base image.


 
image_file
string <binary>  (Base image) 
Upload the base image.


 
image_url
string (Base Image URL) 
 Default:  ""
URL of the base image.


 
prompt
string (Prompt) 
 Default:  ""
Describe what changes to make to the image.


 
creativity_strength
integer (Creativity Strength)   [ 1 .. 10 ] 
 Default:  5
Strength of the creativity effect (1-10).


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 Default:  1
Number of images to generate.


 
aspect_ratio
string (Aspect Ratio) 
 Default:  "16:9"
Aspect ratio of the generated image.


 
option
string (Option) 
 Default:  "Auto"
The image generation option to use. Available values are Flux1, RealisticVision, StableDiffusion3.5, LeonardoImage and Auto.


 
Responses 
200
New Image URLs


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/image/image-2-image
Request samples 
Response samples 
Reimagine
You can reimagine uploaded image and text prompt that describes changes to your uploaded image.



    

  • X-Api-Key: Your customer API key.
    • 



Example Code


import requests

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

payload = {
  'prompt': 'Make shoe blue and change wall to sky.',
  'aspect_ratio': '16:9',
  'option': 'Remake',
  'creativity_strength': 3,
}
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)



Try On Example Code


import requests

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

payload = {'option': 'TryOn'}
files=[
  ('image_file',('human.jpg',open('/path/to/human/image.jpg','rb'),'image/jpeg')),
  ('image2_file',('clothes.png',open('/path/to/clothes/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)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
image
string <binary>  (Base or Human Image.) 
 Deprecated 
Base or human image that you can to use for reimagination.


 
image_file
string <binary>  (Base or Human Image.) 
Base or human image that you can to use for reimagination.


 
image_url
string (Base or Human Image URL) 
 Default:  ""
URL of the base or human image.


 
image2
string <binary>  (Additional Image (Optional)) 
 Deprecated 
Only available for TryOn Option. You can input clothes image.


 
image2_file
string <binary>  (Additional Image (Optional)) 
Only available for TryOn Option. You can input clothes image.


 
image2_url
string (Additional Image URL (Optional)) 
 Default:  ""
Only available for TryOn Option.  You can input clothes image URL.


 
prompt
string (Prompt) 
 Default:  ""
Describe what changes to make to the image. This field will be ignored if image2 is given.


 
creativity_strength
integer (Creativity Strength)   [ 1 .. 10 ] 
 Default:  5
Creativity strength (1-10). This field will be ignored if image2 is given.


 
aspect_ratio
string (Aspect Ratio) 
Aspect ratio of the image. This field will be ignored if image2 is given.


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 Default:  1
Number of images to generate. This field will be ignored if image2 is given.


 
option
string (Option) 
 Default:  "Remake"
Available values are TunedFlux1, Remake, Sketch, Restructure, ReView and TryOn.


 
prompt2
string (Additional Prompt) 
 Default:  ""
Used for FindAndModify option


 
Responses 
200
New Image URLs


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/image/reimagine
Request samples 
Response samples 
Edit Image
You can edit the image with below options. 



    

  • X-Api-Key: Your customer API key.
    • 



Example Code


Remove Background


import requests

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

files=[
  ('image_file', ('image.png', open('/path/to/image.png','rb'), 'image/png'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  "option": "RemoveBackground"
}

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

print(response.text)



Replace Background


import requests

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

files=[
  ('image_file', ('image.png', open('/path/to/image.png','rb'), 'image/png'))
  ('image2_file', ('image2.png', open('/path/to/new/background.png','rb'), 'image/png'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}
payload={
  "option": "ReplaceBackground"
}

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

print(response.text)



Restyle Background


import requests

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

files=[
  ('image_file', ('image.png', open('/path/to/image.png','rb'), 'image/png'))
  ('image2_file', ('image2.png', open('/path/to/new/background.png','rb'), 'image/png'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}
payload={
  "option": "RestyleBackground"
}

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

print(response.text)



Remove Text


import requests

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

files=[
  ('image_file', ('image.png', open('/path/to/image.png','rb'), 'image/png'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  "option": "RemoveText"
}

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

print(response.text)



Upscale Image


import requests

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

files=[
  ('image_file', ('image.png', open('/path/to/image.png','rb'), 'image/png'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  "option": "Upscale"
}

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

print(response.text)



Expand Image


import requests

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

files=[
  ('image_file', ('image.png', open('/path/to/image.png','rb'), 'image/png'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  "option": "ExpandToAspectRatio",
  "aspect_ratio": "16:9"
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
image
string <binary>  (Base Image.) 
 Deprecated 
 
image_file
string <binary>  (Base Image.) 
 
image_url
string (Base Image URL) 
 Default:  ""
URL of the base image.


 
image2
string <binary>  (Additional Image (Optional)) 
 Deprecated 
Upload second image. You can use this option to replace background.


 
image2_file
string <binary>  (Additional Image (Optional)) 
Upload second image. You can use this option to replace background.


 
image2_url
string (Additional Image URL (Optional)) 
 Default:  ""
Upload second image. You can use this option to replace background.


 
option
string (Option) 
 Default:  "EditImage"
Option to apply to your image. Available values RemoveBackground, ReplaceBackground, RestyleBackground, RemoveText, Upscale and ExpandToAspectRatio.


 
aspect_ratio
string (Aspect Ratio) 
 Default:  "16:9"
Aspect ratio of new image


 
expand_method
string (Expand Method) 
 Default:  "outpaint"
 
expand_direction
string (Expand Direction) 
 Default:  "center"
 
Responses 
200
Modified image url.


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/image/edit-image
Request samples 
Response samples 
application/json
{}
Text
APIs for generating and editing prompt.


Generate Text Prompt
You can generate text prompt from uploaded image, refine your prompt or get suggested prompt.


Example Code


Generate text prompt from image.


import requests

url = "https://api.vimmerse.net/text/prompt"

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

files=[
  ('image_file',('file',open('/path/to/file','rb'),'application/octet-stream'))
]

payload = {
  "option": "Image2Prompt", ## "InspireMe" option will also generate refined prompt from image.
}

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

print(response.text)



Generate refined prompt from prompt


import requests

url = "https://api.vimmerse.net/text/prompt"

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

payload = {
  "option": "RefinePrompt", ## "InspireMe" option will also generate refined prompt
  "prompt": "A nurse girl holding an injection and smiling"
}

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

print(response.text)



Generate suggested prompt


import requests

url = "https://api.vimmerse.net/text/prompt"

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

payload = {
  "option": "SuggestPrompt", ## "InspireMe" option will also generate suggested prompt
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
image_file
string <binary>  (Base image) 
 Deprecated 
 
image_url
string (Base Image URL) 
 Default:  ""
 
prompt
string (Prompt) 
 Default:  ""
Your prompt.


 
mode
string (Mode) 
 Default:  "scene"
Your prompt refinement mode.


 
option
string (Option) 
 Default:  "InspireMe"
Available values are Image2Prompt, SuggestPrompt, RefinePrompt and InspireMe. Image2Prompt generates prompt from image, SuggestPrompt is generating an suggested prompt, RefinePrompt refines prompt from your prompt. InspireMe is automatically generating prompt based on your submission.


 
Responses 
200
Generated Text Prompt


400
Bad Request


422
Validation Error


post/text/prompt
Request samples 
Response samples 
application/json
{
  • "data": "Imagine a futuristic cityscape where skyscrapers reach up to touch the stars, illuminated by neon lights and pulsating with energy. In the midst of it all, a sleek and powerful spacecraft hovers effortlessly, casting a beam of light down onto the bustling metropolis below. The scene captures the perfect blend of advanced technology, urban vibrancy, and infinite possibility. Bring this breathtaking vision to life with your creative expertise."
}
Video
APIs for editing video.


Crop Video.
You can change aspect ratio of your input video. 



    

  • X-Api-Key: Your customer API key.
    • 



Request Data


    

  • video_file: Input video file.
    • 

  • aspect_ratio: Aspect ratio of your new video. Example: '1:1', '16:9', '9:16'
    • 

  • offset_x: Offset X-Axis to top left conner from your input video that can be cropped. This value is optional and if you don't give any value, video will be cropped from center.
    • 

  • offset_y: Offset Y-Axis to top left conner from your input video that can be cropped. This value is optional and if you don't give any value, video will be cropped from center.
    • 



Example Code


Crop Video


import requests

url = "https://api.vimmerse.net/video/crop-to-aspect-ratio"

files=[
  ('video', ('video.mp4', open('/path/to/video.mp4','rb'), 'video.mp4'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  "aspect_ratio": "16:9"
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
video_file
string <binary>  (Video input file) 
Input video file.


 
video_url
string (Video input URL) 
 Default:  ""
Input video URL.


 
aspect_ratio
string (Aspect Ratio) 
 Default:  "16:9"
Aspect ratio of the video that you want to get.


 
offset_x
integer (Offset X) 
Offset of the X Axis.


 
offset_y
integer (Offset Y) 
Offset of the Y Axis.


 
Responses 
200
Change Video Aspect Ratio


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/video/crop-to-aspect-ratio
Request samples 
Response samples 
application/json
{}
Enhance Video
You can get upscaled or better quality video. 



    

  • X-Api-Key: Your customer API key.
    • 



Request Data


    

  • video_file: Input video file
    • 

  • option: Available values are 4X, 2X, 4X&DeepClean and 2X&DeepClean and 'DeepClean'.
    • 

  • compression_scale: Compression scale of the video. Range is (0 - 1) and the default value is 0.5.
    • 



Example Code


Enhance video example


import requests

url = "https://api.vimmerse.net/video/enhance"

files=[
  ('video_file', ('video.mp4', open('/path/to/video.mp4','rb'), 'video.mp4'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  'option': '4X&DeepClean'
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
video_file
string <binary>  (Video input file) 
Input video file.


 
video_url
string (Video input URL) 
 Default:  ""
Input video URL.


 
option
string (Option) 
 Default:  "4X&DeepClean"
Available values are 4X, 2X, 4X&DeepClean and 2X&DeepClean and DeepClean.


 
compression_scale
string (Compression Scale) 
 Default:  "0.5"
Compression scale of the video. Range is (0 - 1) and the default value is 0.5.


 
Responses 
200
Enhance video


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/video/enhance
Request samples 
Response samples 
application/json
{}
Add Sound Effect
You can add sound effect to video. 



    

  • X-Api-Key: Your customer API key.
    • 



Request Data


    

  • video_file: Input video file.
    • 

  • prompt: Prompt string that describes on your video. Example: Add ring from phone..
    • 



Example Code


import requests

url = "https://api.vimmerse.net/video/sound-effect"

files=[
  ('video_file', ('video.mp4', open('/path/to/video.mp4','rb'), 'video.mp4'))
]
headers = {
  'X-Api-Key': 'YOUR_API_KEY'
}

payload={
  'prompt': 'Add ringtone from the phone.'
}

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

print(response.text)



SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
video_file
string <binary>  (Video input file) 
Input video file.


 
video_url
string (Video input URL) 
 Default:  ""
Input video URL.


 
prompt
string (Prompt) 
 Default:  ""
Prompt that describes the sound effect.


 
Responses 
200
Video with sound effect


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/video/sound-effect
Request samples 
Response samples 
application/json
{}
Generate a Lip Sync video.
You can generate Lip-Sync video from image, video, audio and prompt. 



    

  • X-Api-Key: Your customer API key.
    • 



You need to upload any of image, image_url or video, video_url to generate Lip-Sync Video.
You also need to upload any of prompt, audio or audio_url to generate Lip-Sync Audio.


SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
image_file
string <binary>  (Image input file) 
Input image file.


 
image_url
string (Image input URL) 
 Default:  ""
Input image URL.


 
video_file
string <binary>  (Video input file) 
Input video file.


 
video_url
string (Video input URL) 
 Default:  ""
Input video URL.


 
audio_file
string <binary>  (Audio input file) 
Input audio file.


 
audio_url
string (Audio input URL) 
 Default:  ""
Input audio URL.


 
prompt
string (Prompt) 
 Default:  ""
Prompt of the speech.


 
voice
string (Voice) 
 Default:  "Rachel"
Voice of the speech. Available voices are "Aria", "Roger", "Sarah", "Laura", "Charlie", "George", "Callum", "River", "Liam", "Charlotte", "Alice", "Matilda", "Will", "Jessica", "Eric", "Chris", "Brian", "Daniel", "Lily" and "Bill". Default is "Rachel".


 
Responses 
200
Lip Sync Video


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/video/lip-sync
Request samples 
Response samples 
application/json
{}
Video Effects
You can generate video effect from image(s) and effect prompt. 



    

  • X-Api-Key: Your customer API key.
    • 



You need to upload any of image, image_url and select teh desired effect to generate video accordingly.


SecurityAPIKeyHeader 
Request 
Request Body schema: multipart/form-data
image
string <binary>  (Base or human image.) 
Base or human image that you want to use for the video effect.


 
image2
string <binary>  (Additional Image(Optional)) 
Additional Image(optional) for specific effect e.g. hug.


 
option
string (Option) 
 Default:  "PikaEffects"
Select the effects tool option. Accepted values are: PikaEffects, KlingEffects, WanEffects


 
effect
string (Effect) 
 Default:  ""
Describe what changes to make to the image.


 
aspect_ratio
string (Aspect Ratio) 
Aspect ratio of the image.


 
quantity
integer (Quantity)   [ 1 .. 4 ] 
 Default:  1
Number of images to generate. This field will be ignored if image2 is given.


 
Responses 
200
Video


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/video/video-effects
Request samples 
Response samples 
application/json
{}
Audio
APIs for generating audios.


Generate speech from prompt
You can generate speech from text prompt. 



    

  • X-Api-Key: Your customer API key.
    • 



Request Data


    

  • prompt: Text prompt of the speech.
    • 

  • voice: Voice of the speech. Available voices are "Aria", "Roger", "Sarah", "Laura", "Charlie", "George", "Callum", "River", "Liam", "Charlotte", "Alice", "Matilda", "Will", "Jessica", "Eric", "Chris", "Brian", "Daniel", "Lily" and "Bill". Default is "Rachel".
    • 



SecurityAPIKeyHeader 
Request 
Request Body schema: application/x-www-form-urlencoded
prompt
string (Prompt) 
 Default:  ""
Prompt of the speech.


 
voice
string (Voice) 
 Default:  "Rachel"
Voice of the speech. Available voices are "Aria", "Roger", "Sarah", "Laura", "Charlie", "George", "Callum", "River", "Liam", "Charlotte", "Alice", "Matilda", "Will", "Jessica", "Eric", "Chris", "Brian", "Daniel", "Lily" and "Bill". Default is "Rachel".


 
Responses 
200
Audio URL


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/audio/text-2-speech
Request samples 
Response samples 
application/json
{}
Generate sound effect from prompt
You can generate audio from text prompt. 



    

  • X-Api-Key: Your customer API key.
    • 



Request Data


    

  • prompt: Text prompt of the audio.
    • 

  • duration: Duration of the audio. Default value is 5 which means 5 second.
    • 



SecurityAPIKeyHeader 
Request 
Request Body schema: application/x-www-form-urlencoded
prompt
string (Prompt) 
 Default:  ""
Prompt that describes the sound effect.


 
duration
integer (Duration) 
 Default:  5
Duration of the audio


 
Responses 
200
Audio URL


400
Bad Request


402
Insufficient Credit


422
Validation Error


post/audio/text-2-audio
Request samples 
Response samples 
application/json
{}
Statistics
APIs for getting statistics data.


Get daily statistics.
You can get daily statistics by providing start and end date. Today's statistics will not be available until the end of the day.
Example URL is https://api.vimmerse.net/customer-statistics/2025-01-01/2025-01-15


SecurityAPIKeyHeader 
Responses 
200
List of statistics


422
Validation Error


get/customer-statistics/{start_time}/{end_time}
Request samples 
Response samples 
application/json
null
Other
Vimmerse health checker service.


Health
Check API health status.


Responses 
200
Successful Response


get/health
Request samples 
Response samples 
application/json
null