Media

Creates a new media object and starts asynchronous video generation.

Send a request with Content-Type: application/json. The body may include creative intent (prompt), optional media references (media_items), and generation options such as video_tool, duration, and aspect_ratio.

The API validates the request, checks credits, creates the media record, queues the generation job, and returns immediately with a media object for tracking progress.

Examples

Example Response (200)

Response body uses the same fields as the example below.

{
  "id": "abc123-def456-ghi789",
  "title": "Example Media",
  "description": "Media description",
  "customer_id": "customer123",
  "primary_user_id": "user-abc-123",
  "media_items": null,
  "duration_time": "5",
  "processing_status": "new",
  "pose_preset": {
    "motion_type": "Auto",
    "prompt": "A cinematic shot over mountains at sunrise",
    "quantity": 1,
    "motion_length": 5,
    "loop": 1
  },
  "submit_params": {"native_audio": true, "file_size": "", "scale_factor": "1"},
  "result": [],
  "webhook_url": "",
  "created_at": "2025-04-01T18:57:37.355064+00:00",
  "updated_at": "2025-04-01T18:57:55.502020+00:00",
  "version": "3"
}

Example 1: Create Media (Python)

Copy and run this as-is, then replace only YOUR_API_KEY.

import requests

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

url = f"{BASE_URL}/v2/media"
headers = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "title": "Product Launch Clip",
    "description": "Short cinematic intro for a new product",
    "prompt": "Smooth camera move around a premium smartwatch on a dark studio background with soft rim light",
    "video_tool": "Auto",
    "duration": 5,
    "quantity": 1,
    "loop": 1,
    "aspect_ratio": "16:9",
    "audio_option": {
        "narrator": "Sarah",
        "narration": "Introducing the next generation of smart performance."
    }
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
print(result)

Example 2: Full Flow (Create -> Poll -> Fetch -> Download)

Copy and run this as-is, then replace only YOUR_API_KEY.

import requests
import time

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"
HEADERS = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

# 1) Create media
create_url = f"{BASE_URL}/v2/media"
create_payload = {
    "title": "AI Demo Video",
    "prompt": "A cinematic drone shot over snow mountains at sunrise with dramatic clouds",
    "video_tool": "Auto",
    "duration": 5,
    "quantity": 1,
    "loop": 1,
    "aspect_ratio": "16:9"
}

create_res = requests.post(create_url, headers=HEADERS, json=create_payload, timeout=60)
create_res.raise_for_status()
create_data = create_res.json()
media_id = create_data["id"]
print(f"Created media: {media_id}")

# 2) Poll until processing completes (GET media returns the full media object)
for attempt in range(120):
    detail_res = requests.get(f"{BASE_URL}/v2/media/{media_id}", headers=HEADERS, timeout=30)
    detail_res.raise_for_status()
    status_data = detail_res.json()
    status = status_data.get("processing_status", "")
    print(f"Attempt {attempt + 1}: status={status}")

    if status == "success":
        break
    if status == "failed":
        raise RuntimeError(f"Media generation ended with status: {status}")
    time.sleep(10)
else:
    raise TimeoutError("Media generation is taking longer than expected.")

# 3) Use download URL(s) from the response (result can contain several files)
detail_data = status_data
video_urls = detail_data.get("result", [])
for url in video_urls:
    print(f"Video URL: {url}")
# Use these URLs to download or display the generated file(s).

audio_option

Optional audio configuration object (JSON). When media_items contains audio, those take precedence.

Audio parameters

Examples (application/json)

Narration + background music:

{
  "narrator": "AutoV",
  "narration": "Introducing the next generation of smart performance.",
  "bg_music_prompt": "Modern, cinematic background with subtle electronic elements"
}

Pre-recorded narration only:

{
  "narration_url": "https://example.com/voiceover.mp3"
}

Background music only:

{
  "bg_music_url": "https://example.com/background.mp3"
}

Notes

• Audio URLs must be publicly accessible (no auth). Supported formats: MP3, WAV.
• When both narration_url and narration are provided, narration_url wins.
• If media_items includes audio, audio_option is ignored for those items.

Updates a media object. Request body must be application/json.

• Empty body {}: Valid; means no updates. The API returns the current media unchanged.
• Metadata only (title, description, visibility_status, rating, webhook_url): The record is updated in place; no regeneration is triggered.
• Generation-related fields (prompt, video_tool, duration, media_items, audio_option, etc.): A new asynchronous generation cycle is started and standard credit rules apply.

audio_option

Optional audio configuration object (JSON). When media_items contains audio, those take precedence.

Audio parameters

Examples (application/json)

Narration + background music:

{
  "narrator": "AutoV",
  "narration": "Introducing the next generation of smart performance.",
  "bg_music_prompt": "Modern, cinematic background with subtle electronic elements"
}

Pre-recorded narration only:

{
  "narration_url": "https://example.com/voiceover.mp3"
}

Background music only:

{
  "bg_music_url": "https://example.com/background.mp3"
}

Notes

• Audio URLs must be publicly accessible (no auth). Supported formats: MP3, WAV.
• When both narration_url and narration are provided, narration_url wins.
• If media_items includes audio, audio_option is ignored for those items.

Retrieves a single media object by ID. Response is application/json with the same fields shown in the example above.

Use the optional fields query parameter to request only specific keys (allowed keys are those in the media response body). When omitted, the full media object is returned.