Media

Creates a new media object and initiates video generation from images or text prompts.

How It Works

Input Types

1. Two Images: Creates a transition video between start and end frames
2. Single Image: Generates animated video from the image
3. No Image: Creates video from a text prompt alone

Parameters

Basic Information

• title: Media title (optional)
• description: Media description (optional)
• visibility_status: Access control
  • "0": Private
  • "1": Unlisted
  • "2": Public

Input Files

• image_files: Upload image files (array)
• image_urls: Provide image URLs (array)

Video Generation Settings

• prompt: Text description for video generation (optional if images provided)
• motion_type: AI model for motion generation (optional)
  • Available: Auto, LumaAI, KlingAI, RunwayML, etc.
• quantity: Number of videos to generate (1-4)
• duration: Video length in seconds (1-10)
• loop: Number of times to repeat motion (1-6)

Audio Settings

• native_audio: Enable native sound effects and lip sync (True or False)
• narration: Narration text (optional)
• narrator: Voice for narration (optional)
• bg_music_prompt: Description for background music (optional)

Advanced Settings

• aspect_ratio: Video dimensions (e.g., "16:9", "9:16", "1:1")
• webhook_url: URL for completion notifications (optional)

Example: Two Image Files (Transition Video)

import requests

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

payload = {
    'title': 'Morph Animation',
    'description': 'Transition between two scenes'
}

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

Example: Image URLs with Custom Motion

import requests

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

payload = {
    'title': 'Character Animation',
    'image_urls': [
        'https://example.com/character1.png',
        'https://example.com/character2.png'
    ],
    'motion_type': 'KlingAI',
    'quantity': 2,  # Generate 2 variations
    'duration': 8,  # 8 seconds long
    'native_audio': True
}

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

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

Example: Text Prompt Only

import requests

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

payload = {
    'title': 'AI Generated Video',
    'prompt': 'A cute bunny jumping through a magical forest with sparkling fairy dust',
    'native_audio': True,
    'bg_music_prompt': 'Gentle, magical background music with chimes',
    'duration': 5,
    'webhook_url': 'https://your-domain.com/webhook'
}

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

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

Retrieves the current processing status and progress percentage of a media object.

Response Fields

• progress_percentage: Processing progress (0-100)
• processing_status: Current state
  • "queue_bullet": Queued for processing
  • "processing": Currently generating
  • "success": Completed
  • "fail": Failed

Example

import requests
import time

def check_media_status(media_id):
    url = f"https://api.vimmerse.net/media/{media_id}/processing-status"
    headers = {'X-Api-Key': 'YOUR_API_KEY'}

    while True:
        response = requests.request("GET", url, headers=headers)
        status = response.json()['data']

        print(f"Progress: {status['progress_percentage']}%")
        print(f"Status: {status['processing_status']}")

        if status['processing_status'] in ['success', 'fail']:
            break

        time.sleep(10)  # Check every 10 seconds

check_media_status('MEDIA_ID')

Status Codes

Retrieves detailed information about a specific media object.

Response Fields

• id: Unique media identifier
• title: Media title
• processing_status: Current processing state
  • "queue_bullet": Waiting in queue
  • "processing": Currently being processed
  • "success": Completed successfully
  • "fail": Failed to process
• progress_percentage: Processing progress (0-100)
• result: Array of generated video URLs
• video_history: Processing history and details

Example

import requests

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

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

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

# Access the result videos
if media_data['data']['processing_status'] == 'success':
    videos = media_data['data']['result']
    print(f"Generated {len(videos)} video(s)")
    for video in videos:
        print(f"Video URL: {video['url']}")

Use Cases

• Check if video generation is complete
• Retrieve download URLs
• Inspect processing history
• Debug generation issues

Updates media metadata and optionally regenerates the video.

Important Notes

⚠️ Credit Usage: Updating certain fields triggers video regeneration and consumes credits.

• Regeneration triggers: prompt, motion_type, quantity, duration, loop, aspect_ratio, native_audio
• No credit cost: Title, description, rating, visibility_status

Example: Update Metadata (No Regeneration)

import requests

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

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

payload = {
    'title': 'Updated Product Video',
    'description': 'New description text',
    'rating': '5',
    'visibility_status': '2'  # Make public
}

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

Example: Regenerate Video (Uses Credits)

import requests

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

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

payload = {
    'title': 'Updated Video',
    'motion_type': 'RunwayML',  # Triggers regeneration
    'duration': 9,               # Triggers regeneration
    'native_audio': True       # Triggers regeneration
}

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)

Resubmits a media object for video generation.

Use Cases

• Retry failed generation
• Regenerate with updated parameters
• Restart interrupted processing

⚠️ Note: This consumes credits each time it's called.

Example

import requests

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

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

# Send POST request with empty body
response = requests.request("POST", url, headers=headers)
print(response.text)