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-stringifying 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', 'DynamiCrafter', 'HaiperVideo', 'LumaAI', and 'Parallax'.

    • Auto: Video motion is defined automatically based on input settings.
    • LeonardoMotion: Video motion is generated by Ledonado 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.
    • DynamiCrafter: Video motion is generated by DynamiCrafter-Interpolation. It takes input image, transition frame, motionAmount, prompt.
    • HaiperVideo: Video motion is generated by Haiper AI v2.0. It takes input image and prompt. It doesnot support motionAmount and transition frame.
    • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. It doesn't support motionAmount and motionLength. 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'.
    • KlingAI: video motion is generated by Kling AI v1.5 Professional model. It takes input images(i.e. optional last frames) and prompt.
    • MinimaxHailuo: video motion is generated by Minimax Hailuo video-01 model. It takes input image and prompt. It doesnot 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 doesnot support motionAmount.
    • 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".

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

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', 'StableVideoDiffusion', 'LeonardoMotion', 'DynamiCrafter', 'HaiperVideo', 'LumaAI', and 'Parallax'.

    • Auto: Video motion is defined automatically based on input settings.
    • LeonardoMotion: Video motion is generated by Ledonado 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.
    • DynamiCrafter: Video motion is generated by DynamiCrafter-Interpolation. It takes input image, transition frame, motionAmount, prompt.
    • HaiperVideo: Video motion is generated by Haiper AI v2.0. It takes input image and prompt. It doesnot support motionAmount and transition frame.
    • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. It doesn't support motionAmount and motionLength. 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'.
    • KlingAI: video motion is generated by Kling AI v1.5 Professional model. It takes input images(i.e. optional last frames) and prompt.
    • MinimaxHailuo: video motion is generated by Minimax Hailuo video-01 model. It takes input image and prompt. It doesnot 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 doesnot support motionAmount.
    • 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".

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 a media object.

Header

• X-Api-Key: Your customer API key.
• Content-Type: application/json

This API updates the media object based on your request. The bullet video will be regenerated if you modify the pose_preset, or submit_params.

Header

• X-Api-Key: Your customer API key.
• Content-Type: application/json

Request Object

You can include only the fields you want to update.

• 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', 'DynamiCrafter', 'HaiperVideo', 'LumaAI', and 'Parallax'.

    • Auto: Video motion is defined automatically based on input settings.
    • LeonardoMotion: Video motion is generated by Ledonado 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.
    • DynamiCrafter: Video motion is generated by DynamiCrafter-Interpolation. It takes input image, transition frame, motionAmount, prompt.
    • HaiperVideo: Video motion is generated by Haiper AI v2.0. It takes input image and prompt. It doesnot support motionAmount and transition frame.
    • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. It doesn't support motionAmount and motionLength. 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'.
    • KlingAI: video motion is generated by Kling AI v1.5 Professional model. It takes input images(i.e. optional last frames) and prompt.
    • MinimaxHailuo: video motion is generated by Minimax Hailuo video-01 model. It takes input image and prompt. It doesnot 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 doesnot support motionAmount.
    • 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".

Downloads file from media.

Header

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

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 retrieves media progress in percentage.

Header

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

Example Code

This code shows how to 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 creates a story from your idea.

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

Header

• X-Api-Key: Your customer API key.
• Content-Type: application/json

Request Object

• idea: Your idea to generate story.

Generate storyboard example

import requests

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

payload = {
  "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)

This API crafts images from your story.

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

Header

• X-Api-Key: Your customer API key.
• Content-Type: application/json

Request Object

• story: Your story object.
• image_url: URL of the Image to be referenced.

Generate image example

import requests

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

payload = {
  "story": {
    "characters": [
      {
        "name": "John",
        "form": "human",
        "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.",
        "action": "**John** walks confidently, holding his **Briefcase** firmly in his right hand while navigating through the **City Street**. His eyes remain focused ahead, unaffected by the fast-paced surroundings. His polished shoes click steadily on the pavement."
      },
      {
        "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.",
        "action": "**John** pauses for a moment to check the time on his silver watch. He then takes a deep breath, momentarily shutting out the bustle of the **City Street**, before continuing his walk, now with a more determined look on his face."
      }
    ]
  }
}

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

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

print(response.text)

Generate image example with referencing image

import requests

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

payload = {
  "story": {
    "characters": [
      {
        "name": "John",
        "form": "human",
        "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.",
        "action": "**John** walks confidently, holding his **Briefcase** firmly in his right hand while navigating through the **City Street**. His eyes remain focused ahead, unaffected by the fast-paced surroundings. His polished shoes click steadily on the pavement."
      },
      {
        "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.",
        "action": "**John** pauses for a moment to check the time on his silver watch. He then takes a deep breath, momentarily shutting out the bustle of the **City Street**, before continuing his walk, now with a more determined look on his face."
      }
    ]
  },
  "image_url", "https://dev-media.vimmerse.net/vimmerse-test-user/ai_images/1wa7alz/story2video1.png"
}

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

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

print(response.text)

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.

Header

• 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.

• story: 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', 'DynamiCrafter', 'HaiperVideo', 'LumaAI', and 'Parallax'.

    • Auto: Video motion is defined automatically based on input settings.
    • LeonardoMotion: Video motion is generated by Ledonado 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.
    • DynamiCrafter: Video motion is generated by DynamiCrafter-Interpolation. It takes input image, transition frame, motionAmount, prompt.
    • HaiperVideo: Video motion is generated by Haiper AI v2.0. It takes input image and prompt. It doesnot support motionAmount and transition frame.
    • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. It doesn't support motionAmount and motionLength. 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'.
    • KlingAI: video motion is generated by Kling AI v1.5 Professional model. It takes input images(i.e. optional last frames) and prompt.
    • MinimaxHailuo: video motion is generated by Minimax Hailuo video-01 model. It takes input image and prompt. It doesnot 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 doesnot support motionAmount.
    • 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/scenes-2-video"

payload = {
  "story": {
    "characters": [
      {
        "name": "John",
        "form": "human",
        "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.",
        "action": "**John** walks confidently, holding his **Briefcase** firmly in his right hand while navigating through the **City Street**. His eyes remain focused ahead, unaffected by the fast-paced surroundings. His polished shoes click steadily on the pavement."
      },
      {
        "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.",
        "action": "**John** pauses for a moment to check the time on his silver watch. He then takes a deep breath, momentarily shutting out the bustle of the **City Street**, before continuing his walk, now with a more determined look on his face."
      }
    ]
  },
  "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)

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.

Header

• 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.

• 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', 'DynamiCrafter', 'HaiperVideo', 'LumaAI', and 'Parallax'.

    • Auto: Video motion is defined automatically based on input settings.
    • LeonardoMotion: Video motion is generated by Ledonado 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.
    • DynamiCrafter: Video motion is generated by DynamiCrafter-Interpolation. It takes input image, transition frame, motionAmount, prompt.
    • HaiperVideo: Video motion is generated by Haiper AI v2.0. It takes input image and prompt. It doesnot support motionAmount and transition frame.
    • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. It doesn't support motionAmount and motionLength. 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'.
    • KlingAI: video motion is generated by Kling AI v1.5 Professional model. It takes input images(i.e. optional last frames) and prompt.
    • MinimaxHailuo: video motion is generated by Minimax Hailuo video-01 model. It takes input image and prompt. It doesnot 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 doesnot support motionAmount.
    • 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)

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.

Header

• 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-stringifying 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', 'DynamiCrafter', 'HaiperVideo', 'LumaAI', and 'Parallax'.

    • Auto: Video motion is defined automatically based on input settings.
    • LeonardoMotion: Video motion is generated by Ledonado 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.
    • DynamiCrafter: Video motion is generated by DynamiCrafter-Interpolation. It takes input image, transition frame, motionAmount, prompt.
    • HaiperVideo: Video motion is generated by Haiper AI v2.0. It takes input image and prompt. It doesnot support motionAmount and transition frame.
    • LumaAI: Video motion is generated by Luma AI. It takes input images(i.e. optional first and last frames) and prompt. It doesn't support motionAmount and motionLength. 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'.
    • KlingAI: video motion is generated by Kling AI v1.5 Professional model. It takes input images(i.e. optional last frames) and prompt.
    • MinimaxHailuo: video motion is generated by Minimax Hailuo video-01 model. It takes input image and prompt. It doesnot 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 doesnot support motionAmount.
    • 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".

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 = {
  'Content-Type': 'multipart/form-data',
  'Accept': 'application/json',
  'X-Api-Key': 'YOUR_API_KEY'
}

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

print(response.text)