Vimmerse Create Media (Video Generation)

by agents.vimmerse.net·Website ↗API ↗

Vimmerse Create Media (Video Generation) is a paid API for AI agents from agents.vimmerse.net, paid per call via MPP, $1.2/call (dynamic — varies by input), status unknown (last checked 2026-10-30).

Submits a text-prompt and optional media references to asynchronously generate a video clip, returning a trackable media job object.

How this service works

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. ```json { "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`. ```python 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 from the product photo to the lifestyle photo", "media_items": [ { "type": "image", "url": "https://example.com/watch-front.png", "position": "First" }, { "type": "image", "url": "https://example.com/watch-lifestyle.png", "position": "Last" } ], "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`. ```python 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). ``` ## media_items How to pass images or videos. `media_items` is a **JSON array of objects**, not a string and not a file upload. Each object has three fields: | Field | Values | Meaning | |-------|--------|---------| | `type` | `"image"` or `"video"` | `"image"` is a still (png, jpg, webp). `"video"` is an mp4; a frame is taken from it. | | `url` | public https URL | The server downloads this URL with no cookies and no Authorization header. | | `position` | `"First"` or `"Last"` | `"First"` is the start frame. `"Last"` is the end frame. | One picture (image-to-video): ```json "media_items": [ {"type": "image", "url": "https://example.com/start.png", "position": "First"} ] ``` Start frame and end frame: ```json "media_items": [ {"type": "image", "url": "https://example.com/start.png", "position": "First"}, {"type": "image", "url": "https://example.com/end.png", "position": "Last"} ] ``` Do not put audio in `media_items`. Audio items are ignored. Use `audio_option` for speech and music. ## audio_option Optional audio configuration object (JSON). This is a JSON object, not a string. Pass speech and music here. Do not put audio files in `media_items`. ## Audio parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `narrator` | string | AutoV | Voice for text-to-speech. **Available voices**: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill | | `narration` | string | null | Text to convert to speech with the chosen narrator | | `narration_url` | string | null | URL to pre-recorded narration (MP3/WAV). If set, `narrator` and `narration` are ignored | | `bg_music_prompt` | string | null | Description for AI-generated background music | | `bg_music_url` | string | null | URL to an external background music track | | `native_audio` | boolean | false | Enable native audio (e.g. sound effects, lip sync) for compatible tools | ## Examples (application/json) **Narration + background music:** ```json { "narrator": "AutoV", "narration": "Introducing the next generation of smart performance.", "bg_music_prompt": "Modern, cinematic background with subtle electronic elements" } ``` **Pre-recorded narration only:** ```json { "narration_url": "https://example.com/voiceover.mp3" } ``` **Background music only:** ```json { "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. - Audio inside `media_items` is ignored. `audio_option` is the only audio input.

Output

Returns a media object immediately with a unique job ID, processing_status (initially 'new'), pose_preset config, duration, and timestamps. The actual video is generated asynchronously and must be polled by ID until completion.