Media

Media APIs provide a JSON-first interface for creating and managing AI video media. All request and response bodies use Content-Type: application/json.

Recommended flow

  1. POST /v2/media — Create media with prompt and/or media_items (JSON body).
  2. Poll GET /v2/media/{media_id} until processing_status is success.
  3. Use the 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).

Error response format

All error responses use application/json with exactly two fields:

  • message: Detailed error message for the client to display to the user.
  • code: Machine-readable error code so the client can identify the reason (e.g. 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"}

Create 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 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.

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).

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):

"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.

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 true Enable native audio (e.g. sound effects, lip sync) for compatible tools

Examples (application/json)

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"
}

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.
SecurityAPIKeyHeader
Request
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Username (string) or Username (null) (Username)
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type)
Request Body schema: application/json
required
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.

Enum: "Auto" "AutoT3" "AutoT1" "HappyHorse" "Grok" "KlingAI" "KlingT3" "KlingPro" "GoogleOmni" "VeoLite" "VeoFast" "Veo" "MinimaxHailuo" "MinimaxTurbo" "Seedance" "SeedanceFast" "SeedanceT6" "Pixverse" "PixverseT3" "Hunyuan" "Vidu" "PVideo" "StaticMotion" "Wan" "TryOnVideo"
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.

Enum: "Advanced" "Quick"
Webhook URL (string) or Webhook URL (null) (Webhook URL)

Callback URL to receive status updates.

Responses
200

New Media

402

Insufficient Credit

404

Not Found

422

Validation Error

post/v2/media
Request samples
Response samples
application/json
{
  • "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": {
    },
  • "submit_params": {
    },
  • "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"
}

Estimate Credits

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).

Request
Request Body schema: application/json
required
video_tool
string (Video Tool)
Default: "Auto"

Motion/generation tool option (same as create media).

Enum: "Auto" "AutoT3" "AutoT1" "HappyHorse" "Grok" "KlingAI" "KlingT3" "KlingPro" "GoogleOmni" "VeoLite" "VeoFast" "Veo" "MinimaxHailuo" "MinimaxTurbo" "Seedance" "SeedanceFast" "SeedanceT6" "Pixverse" "PixverseT3" "Hunyuan" "Vidu" "PVideo" "StaticMotion" "Wan" "TryOnVideo"
quantity
integer (Quantity) [ 1 .. 4 ]
Default: 1

Number of generated outputs.

duration
integer (Scene Duration) [ 1 .. 15 ]
Default: 5

Target clip duration in seconds (same as create media).

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."}

Responses
200

Credit estimate and breakdown

422

Validation Error

post/v2/media/estimate-credits
Request samples
Response samples
application/json
{
  • "total_credits": 0,
  • "breakdown": { }
}

Update Media

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.

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):

"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.

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 true Enable native audio (e.g. sound effects, lip sync) for compatible tools

Examples (application/json)

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"
}

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.
SecurityAPIKeyHeader
Request
path Parameters
media_id
required
string (Media ID)

Unique identifier of the media

header Parameters
Authorization (string) or Authorization (null) (Authorization)
Username (string) or Username (null) (Username)
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type)
Request Body schema: application/json
required
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.

Responses
200

Media Object (CustomerMediaResponse or ProductMediaResponse)

400

Bad Request

402

Insufficient Credit

404

Not Found

422

Validation Error

put/v2/media/{media_id}
Request samples
Response samples
application/json
{
  • "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": {
    },
  • "submit_params": {
    },
  • "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"
}

Get Media

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.

SecurityAPIKeyHeader
Request
path Parameters
media_id
required
string (Media ID)

Unique identifier of the media

query Parameters
fields
string (Field Selection)
Default: ""

Comma-separated list of specific fields to retrieve from the media object. Example: 'title,description,processing_status,progress_percentage'. If not provided, all fields are returned. Useful for reducing response size when only specific information is needed.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type)
Username (string) or Username (null) (Username)
Responses
200

Media Object (CustomerMediaResponse or ProductMediaResponse by customer_id)

404

Not Found

422

Validation Error

get/v2/media/{media_id}
Request samples
Response samples
application/json
{
  • "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": {
    },
  • "submit_params": {
    },
  • "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"
}