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)

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.

Header

• 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, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.

    • Auto: Video motion is defined automatically based on input settings.
    • 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.
    • Kling2: Video motion is generated by Kling2.1 model. It takes input images and prompt.
    • MinimaxHailuo: Video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not a transition frame.
    • Seedance: Video motion is generated by ByteDance Seedance. It takes input image and prompt. It does not support a transition frame.
    • Hunyuan: Video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support a transition frame.
    • Wan: Video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support a transition frame.
    • Pixverse: Video motion is generated by PixVerse. It takes input image and prompt. It does not support a transition frame.
    • Veo: Video motion is generated by Google Veo. It takes input image and prompt. It does not support a transition frame.
    • VeoFast: Video motion is generated by Google Veo Fast. It takes input image and prompt. It does not support a transition frame.
    • RunwayML: Video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt.
    • 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": "Yes",
    "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}")

This API creates a new media with prompt under pose_preset data. Include request data in the form data.

Header

• 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, LeonardoMotion, LumaAI, LumaRay2, KlingAI, MinimaxHailuo, Hunyuan, RunwayML, Wan, Pixverse, TryOnVideo and Parallax.

    • Auto: Video motion is defined automatically based on input settings.
    • 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.
    • Kling2: Video motion is generated by Kling2.1 model. It takes input images and prompt.
    • MinimaxHailuo: Video motion is generated by Minimax Hailuo. It takes input image and prompt. It does not a transition frame.
    • Seedance: Video motion is generated by ByteDance Seedance. It takes input image and prompt. It does not support a transition frame.
    • Hunyuan: Video motion is generated by Tencent Hunyuan. It takes input image and prompt. It does not support a transition frame.
    • Wan: Video motion is generated by Alibaba Wan2.1. It takes input image and prompt. It does not support a transition frame.
    • Pixverse: Video motion is generated by PixVerse. It takes input image and prompt. It does not support a transition frame.
    • Veo: Video motion is generated by Google Veo. It takes input image and prompt. It does not support a transition frame.
    • VeoFast: Video motion is generated by Google Veo Fast. It takes input image and prompt. It does not support a transition frame.
    • RunwayML: Video motion is generated by RunwayML Gen3. It takes input images(i.e. optional first and last frames) and prompt.
    • 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}")

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)

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)

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)

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)

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)