Media APIs provide a JSON-first interface for creating and managing AI video media. All request and response bodies use Content-Type: application/json.
prompt and/or media_items (JSON body).processing_status is success.result field from the media response — it contains a list of URLs for the generated file(s); use these URLs to download or display the output (there may be several entries).All error responses use application/json with exactly two fields:
MEDIA_NOT_FOUND, INSUFFICIENT_CREDIT, JOB_CREATE_FAILED).Example: {"message": "The requested media was not found or you do not have access.", "code": "MEDIA_NOT_FOUND"}
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.
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"
}
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 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)
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",
"audio_option": {
"native_audio": true
}
}
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).
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):
"media_items": [
{"type": "image", "url": "https://example.com/start.png", "position": "First"}
]
Start frame and end frame:
"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.
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.
| 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 | true | Enable native audio (e.g. sound effects, lip sync) for compatible tools |
Native audio enabled (with lip sync and sound effects):
{
"native_audio": true
}
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"
}
narration_url and narration are provided, narration_url wins.media_items is ignored. audio_option is the only audio input.Authorization (string) or Authorization (null) (Authorization) | |
Username (string) or Username (null) (Username) | |
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type) |
| title | string (Title) Default: "" Media title. |
| description | string (Description) Default: "" Media description. |
Array of Media Items (objects) or Media Items (null) (Media Items) Array of image or video inputs. Send a JSON array of objects, not a string. Each object is {"type":"image"|"video","url":"https://...","position":"First"|"Last"}. "First" is the start frame. "Last" is the end frame. One picture: [{"type":"image","url":"https://example.com/start.png","position":"First"}]. Start and end: add a second object with position Last. url must be a public https URL. Do not upload a file here and do not put audio in this array. Audio belongs in audio_option. | |
| prompt | string (Prompt) Default: "" Text prompt used for generation. |
| video_tool | string (Video Tool) Default: "Auto" Motion/generation tool option. |
| quantity | integer (Quantity) [ 1 .. 4 ] Default: 1 Number of generated outputs. |
| duration | integer (Scene Duration) [ 1 .. 30 ] Default: 5 Scene duration in seconds. |
| loop | integer (Loop) [ 1 .. 6 ] Default: 1 Loop count for generation. |
MediaAudioOption (object) or Audio Option (null) (Audio Option) JSON object for speech and music. Not a string. Keys: narrator (voice name), narration (script), narration_url (public mp3/wav; wins over narrator and narration), bg_music_prompt (music description), bg_music_url (public mp3/wav; wins over bg_music_prompt), native_audio (boolean). Example: {"narrator":"Sarah","narration":"Introducing the next generation of smart performance."} | |
Aspect Ratio (string) or Aspect Ratio (null) (Aspect Ratio) Optional output aspect ratio. | |
| pipeline_mode | string (Pipeline Mode) Default: "Advanced" Advanced: preprocess input images (fix orientation, rescale, expand to aspect ratio) and run video post-processing (e.g. looping when loop > 1). Quick: use images as-is and skip post-processing; faster, less processing. |
Webhook URL (string) or Webhook URL (null) (Webhook URL) Callback URL to receive status updates. |
New Media
Insufficient Credit
Not Found
Validation Error
{- "id": "abc123-def456-ghi789",
- "title": "Example Media",
- "description": "Media description",
- "customer_id": "customer123",
- "primary_user_id": "user-abc-123",
- "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"
}Returns how many credits a POST /v2/media request would charge for the given video_tool, duration, quantity, and optional audio_option, without creating a job. No authentication required; response is pricing-only (no per-user balance). Uses the same billing rules as create/update regeneration. Prompt text, pipeline_mode, aspect_ratio, and loop do not change credits today (duration is the requested clip length in seconds, not derived from prompt).
Credit estimate and breakdown
Validation Error
{- "total_credits": 0,
- "breakdown": { }
}Updates a media object. Request body must be application/json.
{}: Valid; means no updates. The API returns the current media unchanged.title, description, visibility_status, rating, webhook_url): The record is updated in place; no regeneration is triggered.prompt, video_tool, duration, media_items, audio_option, etc.): A new asynchronous generation cycle is started and standard credit rules apply.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):
"media_items": [
{"type": "image", "url": "https://example.com/start.png", "position": "First"}
]
Start frame and end frame:
"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.
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.
| 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 | true | Enable native audio (e.g. sound effects, lip sync) for compatible tools |
Native audio enabled (with lip sync and sound effects):
{
"native_audio": true
}
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"
}
narration_url and narration are provided, narration_url wins.media_items is ignored. audio_option is the only audio input.Authorization (string) or Authorization (null) (Authorization) | |
Username (string) or Username (null) (Username) | |
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type) |
Title (string) or Title (null) (Title) Media title. | |
Description (string) or Description (null) (Description) Media description. | |
Array of Media Items (objects) or Media Items (null) (Media Items) Array of image or video inputs. Send a JSON array of objects, not a string. Each object is {"type":"image"|"video","url":"https://...","position":"First"|"Last"}. "First" is the start frame. "Last" is the end frame. One picture: [{"type":"image","url":"https://example.com/start.png","position":"First"}]. Start and end: add a second object with position Last. url must be a public https URL. Do not upload a file here and do not put audio in this array. Audio belongs in audio_option. | |
Prompt (string) or Prompt (null) (Prompt) Text prompt used for generation. | |
Video Tool (string) or Video Tool (null) (Video Tool) Motion/generation tool option. | |
Quantity (integer) or Quantity (null) (Quantity) Number of generated outputs. | |
Scene Duration (integer) or Scene Duration (null) (Scene Duration) Scene duration in seconds. | |
Loop (integer) or Loop (null) (Loop) Loop count for generation. | |
MediaAudioOption (object) or Audio Option (null) (Audio Option) JSON object for speech and music. Not a string. Keys: narrator (voice name), narration (script), narration_url (public mp3/wav; wins over narrator and narration), bg_music_prompt (music description), bg_music_url (public mp3/wav; wins over bg_music_prompt), native_audio (boolean). Example: {"narrator":"Sarah","narration":"Introducing the next generation of smart performance."} | |
Aspect Ratio (string) or Aspect Ratio (null) (Aspect Ratio) Optional output aspect ratio. | |
Pipeline Mode (string) or Pipeline Mode (null) (Pipeline Mode) Advanced: preprocess images and run video post-processing. Quick: use images as-is, skip post-processing. | |
Webhook URL (string) or Webhook URL (null) (Webhook URL) Callback URL to receive status updates. |
Media Object (CustomerMediaResponse or ProductMediaResponse)
Bad Request
Insufficient Credit
Not Found
Validation Error
{- "id": "abc123-def456-ghi789",
- "title": "Example Media",
- "description": "Media description",
- "customer_id": "customer123",
- "primary_user_id": "user-abc-123",
- "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"
}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.
Authorization (string) or Authorization (null) (Authorization) | |
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type) | |
Username (string) or Username (null) (Username) |
Media Object (CustomerMediaResponse or ProductMediaResponse by customer_id)
Not Found
Validation Error
{- "id": "abc123-def456-ghi789",
- "title": "Example Media",
- "description": "Media description",
- "customer_id": "customer123",
- "primary_user_id": "user-abc-123",
- "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"
}