Media

Creates a new media object and initiates video generation from images, text prompts, or a combination of both.

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 with AI-generated motion
3. Text Prompt Only - Creates video from a text description without images
4. Media Items - Advanced configuration with multiple inputs and precise control

Workflow

Once submitted, the API:

1. Validates input parameters and checks credit availability
2. Creates a media object with unique ID
3. Queues the video generation job
4. Returns immediately with media ID and initial status
5. Processes video generation asynchronously
6. Updates status when complete (poll or webhook)

Parameters

Either prompt, image_files, image_urls, or media_items must be provided.

Example 1: Create Media with Image Files

import requests

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

url = f"{BASE_URL}/media"
headers = {"X-Api-Key": API_KEY}

# Prepare image files
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"))
]

payload = {
    "title": "Morph Animation",
    "description": "Transition between two scenes",
    "motion_type": "Auto",
    "duration": 5,
    "aspect_ratio": "16:9"
}

try:
    response = requests.post(url, headers=headers, data=payload, files=files, timeout=60)
    response.raise_for_status()

    result = response.json()
    media_data = result["data"]

    print(f"Media created! ID: {media_data['id']}")
    print(f"Status: {media_data['processing_status']}")

    # Close file handles
    for _, f in files:
        if hasattr(f[1], 'close'):
            f[1].close()

except requests.exceptions.RequestException as e:
    print(f"Error: {e}")
    # Ensure files are closed on error
    for _, f in files:
        if hasattr(f[1], 'close'):
            f[1].close()

Example 2: Create Media with Media Items (Recommended)

import requests
import json

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

url = f"{BASE_URL}/media"
headers = {"X-Api-Key": API_KEY}

payload = {
    "title": "Product Showcase",
    "prompt": "Smooth camera movement showcasing the product",
    "media_items": json.dumps([
        {
            "type": "image",
            "url": "https://example.com/product-front.png",
            "position": "First"
        },
        {
            "type": "image",
            "url": "https://example.com/product-back.png",
            "position": "Last"
        }
    ]),
    "motion_type": "KlingAI",
    "quantity": 2,
    "duration": 8,
    "camera_control": "HorizontalArc",
    "audio_option": json.dumps({
        "narrator": "Sarah",
        "narration": "Introducing our revolutionary product",
        "bg_music_prompt": "Upbeat, modern background music"
    }),
    "aspect_ratio": "9:16",
    "webhook_url": "https://your-domain.com/webhook/media-complete"
}

try:
    response = requests.post(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    print(f"Media created: {result['data']['id']}")

except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Example 3: Text Prompt Only

import requests
import json

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

url = f"{BASE_URL}/media"
headers = {"X-Api-Key": API_KEY}

payload = {
    "title": "AI Generated Video",
    "prompt": "A cute bunny jumping through a magical forest with sparkling fairy dust and glowing mushrooms",
    "motion_type": "Auto",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio_option": json.dumps({
        "narrator": "Rachel",
        "narration": "In a magical forest, a bunny discovers wonder and adventure",
        "bg_music_prompt": "Gentle, magical background music with chimes and soft melodies"
    }),
    "webhook_url": "https://your-domain.com/webhook/media-complete"
}

try:
    response = requests.post(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    media_data = result["data"]

    print(f"Media created! ID: {media_data['id']}")
    print(f"Status: {media_data['processing_status']}")

except requests.exceptions.HTTPError as e:
    print(f"HTTP Error: {e}")
    if e.response is not None:
        print(f"Response: {e.response.text}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Complete Example with Polling

This complete example creates media, polls for completion, and downloads the final video:

import requests
import json
import time

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

# Step 1: Create media
url = f"{BASE_URL}/media"
headers = {"X-Api-Key": API_KEY}

payload = {
    "title": "Product Animation",
    "prompt": "Smooth camera movement showcasing a sleek smartphone",
    "motion_type": "Auto",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio_option": json.dumps({
        "narrator": "Sarah",
        "narration": "Introducing our latest innovation",
        "bg_music_prompt": "Modern, upbeat background music"
    })
}

print("Creating media...")
try:
    response = requests.post(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    media_data = result["data"]
    media_id = media_data["id"]

    print(f"✓ Media created successfully!")
    print(f"  Media ID: {media_id}")
    print(f"  Status: {media_data['processing_status']}")

except requests.exceptions.HTTPError as e:
    print(f"✗ HTTP Error: {e}")
    if e.response is not None:
        print(f"  Response: {e.response.text}")
    exit(1)
except requests.exceptions.RequestException as e:
    print(f"✗ Request failed: {e}")
    exit(1)

# Step 2: Poll for completion
print("\nPolling for media completion...")
max_attempts = 120  # Maximum 60 minutes
attempt = 0
poll_interval = 30  # Check every 30 seconds

def get_media_status(media_id):
    """Retrieve the current status of a media."""
    url = f"{BASE_URL}/media/{media_id}/processing-status"
    headers = {"X-Api-Key": API_KEY}

    try:
        response = requests.get(url, headers=headers, timeout=30)
        response.raise_for_status()
        return response.json()["data"]
    except requests.exceptions.RequestException as e:
        print(f"  Warning: Error retrieving status: {e}")
        return None

while attempt < max_attempts:
    status_data = get_media_status(media_id)

    if not status_data:
        print(f"  Attempt {attempt + 1}/{max_attempts}: Failed to retrieve status, retrying...")
        time.sleep(poll_interval)
        attempt += 1
        continue

    status = status_data.get("processing_status")
    progress = status_data.get("progress_percentage", 0)

    print(f"  Attempt {attempt + 1}/{max_attempts}: Status={status}, Progress={progress}%")

    if status == "success":
        print(f"\n✓ Media completed successfully!")

        # Get full media details
        url = f"{BASE_URL}/media/{media_id}"
        response = requests.get(url, headers=headers)
        media_data = response.json()["data"]

        # Download video
        download_url = f"{BASE_URL}/media/{media_id}/download"
        print("\nDownloading video...")
        try:
            video_response = requests.get(download_url, headers=headers, stream=True, timeout=60)
            video_response.raise_for_status()

            output_path = "media_video.mp4"
            total_size = int(video_response.headers.get('content-length', 0))
            downloaded = 0

            with open(output_path, "wb") as f:
                for chunk in video_response.iter_content(chunk_size=8192):
                    if chunk:
                        f.write(chunk)
                        downloaded += len(chunk)
                        if total_size > 0:
                            percent = (downloaded / total_size) * 100
                            print(f"  Download progress: {percent:.1f}%", end="\r")

            print(f"\n✓ Video downloaded successfully!")
            print(f"  Saved to: {output_path}")
            print(f"  File size: {downloaded / (1024 * 1024):.2f} MB")

        except Exception as e:
            print(f"\n✗ Error downloading video: {e}")
        break
    elif status == "fail":
        print(f"\n✗ Media generation failed.")
        print(f"  Media ID: {media_id}")
        exit(1)

    time.sleep(poll_interval)
    attempt += 1

if attempt >= max_attempts:
    print(f"\n⚠ Timeout: Media generation is taking longer than expected.")
    print(f"  Media ID: {media_id}")
    print(f"  Please check the status later using: GET {BASE_URL}/media/{media_id}/processing-status")

Error Handling

The API may return the following HTTP status codes:

• 200 - Success. Media creation initiated.
• 400 - Bad Request. Invalid parameters or missing required fields.
• 402 - Payment Required. Insufficient credits in your account.
• 404 - Not Found. Resource not found.
• 429 - Too Many Requests. Rate limit exceeded.
• 500 - Internal Server Error. Please retry or contact support.

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

This lightweight endpoint is optimized for frequent polling and provides minimal response data for efficient status checking.

Response Fields

Status Values

Example Request

import requests

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/media/{MEDIA_ID}/processing-status"
headers = {"X-Api-Key": "YOUR_API_KEY"}

try:
    response = requests.get(url, headers=headers, timeout=30)
    response.raise_for_status()

    result = response.json()
    status_data = result["data"]

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

except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Polling Example

import requests
import time

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"
API_KEY = "YOUR_API_KEY"

def check_media_status(media_id):
    """Check media processing status."""
    url = f"{BASE_URL}/media/{media_id}/processing-status"
    headers = {"X-Api-Key": API_KEY}

    try:
        response = requests.get(url, headers=headers, timeout=30)
        response.raise_for_status()
        return response.json()["data"]
    except requests.exceptions.RequestException as e:
        print(f"Error checking status: {e}")
        return None

# Poll until complete
max_attempts = 120  # Maximum 60 minutes
attempt = 0

while attempt < max_attempts:
    status_data = check_media_status(MEDIA_ID)

    if not status_data:
        print(f"Attempt {attempt + 1}/{max_attempts}: Failed to retrieve status")
        time.sleep(30)
        attempt += 1
        continue

    progress = status_data.get("progress_percentage", 0)
    status = status_data.get("processing_status")

    print(f"Attempt {attempt + 1}/{max_attempts}: Status={status}, Progress={progress}%")

    if status == "success":
        print("\n✓ Media completed successfully!")
        break
    elif status == "fail":
        print("\n✗ Media generation failed.")
        break

    time.sleep(30)  # Check every 30 seconds
    attempt += 1

if attempt >= max_attempts:
    print("\n⚠ Timeout: Processing is taking longer than expected.")

Retrieves detailed information about a specific media object, including processing status, generated videos, and metadata.

Response Fields

Status Values

• queue_bullet - Waiting in queue for processing
• processing_bullet - Currently being processed
• success - Completed successfully
• fail - Failed to process
• cancel - Processing was cancelled

Example Request

import requests

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/media/{MEDIA_ID}"
headers = {"X-Api-Key": "YOUR_API_KEY"}

try:
    response = requests.get(url, headers=headers, timeout=30)
    response.raise_for_status()

    result = response.json()
    media_data = result["data"]

    print(f"Media ID: {media_data['id']}")
    print(f"Status: {media_data['processing_status']}")
    print(f"Progress: {media_data.get('progress_percentage', 0)}%")

    if media_data['processing_status'] == 'success':
        # Access generated videos
        if media_data.get("result"):
            print(f"Generated {len(media_data['result'])} video(s)")
            for idx, video in enumerate(media_data["result"], 1):
                print(f"Video {idx}: {video.get('url', 'N/A')}")
        else:
            # Download URL available
            download_url = f"{BASE_URL}/media/{MEDIA_ID}/download"
            print(f"Download URL: {download_url}")
    elif media_data['processing_status'] == 'fail':
        print("Media generation failed. Check error details.")

except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("Media not found. Please verify the media ID.")
    else:
        print(f"HTTP Error: {e}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Use Cases

• Check Completion: Verify if video generation is complete
• Retrieve URLs: Get download URLs for generated videos
• Inspect History: Review processing history and parameters
• Debug Issues: Examine processing details for troubleshooting
• Field Selection: Use fields query parameter to retrieve specific fields only

Updates media metadata and optionally regenerates the video with new parameters.

Important Notes

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

Fields That Trigger Regeneration (Consumes Credits)

• prompt - Text description
• motion_type - AI model selection
• quantity - Number of variations
• duration - Video length
• loop - Motion repetition count
• camera_control - Camera path
• aspect_ratio - Video dimensions
• audio_option - Audio configuration
• media_items - Input media configuration
• model - Try-on model selection

Fields That Don't Trigger Regeneration (No Credit Cost)

• title - Media title
• description - Media description
• rating - User rating
• visibility_status - Access control
• webhook_url - Webhook URL

Example 1: Update Metadata Only (No Regeneration)

import requests

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/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
}

try:
    response = requests.put(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    print(f"Media updated: {result['data']['id']}")

except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Example 2: Regenerate Video (Uses Credits)

import requests
import json

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/media/{MEDIA_ID}/edit"
headers = {"X-Api-Key": "YOUR_API_KEY"}

payload = {
    "title": "Updated Video",
    "motion_type": "RunwayML",  # Triggers regeneration
    "duration": 9,               # Triggers regeneration
    "camera_control": "HorizontalArc",  # Triggers regeneration
    "audio_option": json.dumps({
        "narrator": "Sarah",
        "narration": "Updated narration text",
        "bg_music_prompt": "Energetic background music"
    })
}

try:
    response = requests.put(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    media_data = result["data"]

    print(f"Media regeneration started!")
    print(f"Media ID: {media_data['id']}")
    print(f"Status: {media_data['processing_status']}")

except requests.exceptions.HTTPError as e:
    if e.response.status_code == 402:
        print("Insufficient credits for regeneration")
    else:
        print(f"HTTP Error: {e}")
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Error Handling

• 400 - Bad Request. Invalid parameters or media not found.
• 402 - Payment Required. Insufficient credits for regeneration.
• 404 - Not Found. Media not found or access denied.

Updates media metadata and optionally regenerates the video with new parameters.

Important Notes

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

Fields That Trigger Regeneration (Consumes Credits)

• prompt - Text description
• motion_type - AI model selection
• quantity - Number of variations
• duration - Video length
• loop - Motion repetition count
• camera_control - Camera path
• aspect_ratio - Video dimensions
• audio_option - Audio configuration
• media_items - Input media configuration
• model - Try-on model selection

Fields That Don't Trigger Regeneration (No Credit Cost)

• title - Media title
• description - Media description
• rating - User rating
• visibility_status - Access control
• webhook_url - Webhook URL

Example 1: Update Metadata Only (No Regeneration)

import requests

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/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
}

try:
    response = requests.put(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    print(f"Media updated: {result['data']['id']}")

except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Example 2: Regenerate Video (Uses Credits)

import requests
import json

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/media/{MEDIA_ID}/edit"
headers = {"X-Api-Key": "YOUR_API_KEY"}

payload = {
    "title": "Updated Video",
    "motion_type": "RunwayML",  # Triggers regeneration
    "duration": 9,               # Triggers regeneration
    "camera_control": "HorizontalArc",  # Triggers regeneration
    "audio_option": json.dumps({
        "narrator": "Sarah",
        "narration": "Updated narration text",
        "bg_music_prompt": "Energetic background music"
    })
}

try:
    response = requests.put(url, headers=headers, data=payload, timeout=60)
    response.raise_for_status()

    result = response.json()
    media_data = result["data"]

    print(f"Media regeneration started!")
    print(f"Media ID: {media_data['id']}")
    print(f"Status: {media_data['processing_status']}")

except requests.exceptions.HTTPError as e:
    if e.response.status_code == 402:
        print("Insufficient credits for regeneration")
    else:
        print(f"HTTP Error: {e}")
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Error Handling

• 400 - Bad Request. Invalid parameters or media not found.
• 402 - Payment Required. Insufficient credits for regeneration.
• 404 - Not Found. Media not found or access denied.

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 using existing parameters.

Use Cases

• Retry Failed Generation: Restart processing after a failure
• Regenerate with Same Parameters: Create a new video with identical settings
• Restart Interrupted Processing: Resume processing that was interrupted

⚠️ Important: This endpoint consumes credits each time it's called, even if the media was previously processed successfully.

How It Works

The endpoint uses the existing media configuration (prompt, motion_type, duration, etc.) and resubmits it for processing. All parameters from the original media creation are preserved.

Example Request

import requests

BASE_URL = "https://api.vimmerse.net"
MEDIA_ID = "your-media-id-here"

url = f"{BASE_URL}/media/{MEDIA_ID}/process"
headers = {"X-Api-Key": "YOUR_API_KEY"}

try:
    # Send POST request with empty body
    response = requests.post(url, headers=headers, timeout=60)
    response.raise_for_status()

    result = response.json()
    print("Media resubmitted successfully")

except requests.exceptions.HTTPError as e:
    if e.response.status_code == 402:
        print("Insufficient credits for resubmission")
    elif e.response.status_code == 404:
        print("Media not found")
    else:
        print(f"HTTP Error: {e}")
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Error Responses

• 400 - Bad Request. Media not found or invalid state.
• 402 - Payment Required. Insufficient credits.
• 404 - Not Found. Media not found or access denied.
• 500 - Internal Server Error. Please retry or contact support.