Story

Creates a complete video from a text idea in one call. Send Content-Type: application/json.

The pipeline runs automatically: storyboard → elements → scenes → narrations/music → video animation → composition. Poll GET /v2/story/{story_id} until status is success, then use video_url.

Example: Idea-to-Video (Python)

import requests

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

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

payload = {
    "idea": "Create a promotional video where cute animals play musical instruments in a sunny meadow",
    "title": "Musical Animals Story",
    "aspect_ratio": "9:16",
    "scene_count": 4,
    "image_tool": "Seedream",
    "video_tool": "Auto",
    "scene_duration": 5,
    "audio_option": {
        "has_bg_music": True,
        "has_narration": True,
        "native_audio": False,
        "narrator": "AutoV",
    },
    "language": "English",
    "webhook_url": "https://your-domain.com/webhook/callback",
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
story_id = result["id"]
print(f"Story ID: {story_id}, Status: {result['status']}")

elements

Optional JSON object of pre-defined story elements you already have in mind for this automatic flow. The API uses these to guide the internal storyboard generation (e.g. character names, environments, and props). Only characters, environments, and objects are accepted; scenes must not be included (scenes are generated from the idea and timing).

Each key in elements must be a list of dictionaries (JSON objects), matching the storyboard structure:

Key	Type	Description
characters	array of objects	Optional. Each item is a JSON object with name, description, and optionally image_url.
environments	array of objects	Optional. Each item is a JSON object with name, description, and optionally image_url.
objects	array of objects	Optional. Each item is a JSON object with name, description, and optionally image_url.

Example (partial):

{
  "idea": "Create a promotional video where cute animals play musical instruments in a sunny meadow",
  "scene_count": 4,
  "elements": {
    "characters": [
      {
        "name": "Whiskers the Squirrel",
        "description": "Style:Pixar-style 3D, a small, nimble squirrel with rusty-red fur and a bushy tail.",
        "image_url": ""
      },
      {
        "name": "Pip the Rabbit",
        "description": "Style:Pixar-style 3D, a plump, creamy white rabbit with long floppy ears.",
        "image_url": ""
      }
    ],
    "environments": [
      {
        "name": "Sunny Meadow",
        "description": "Style:Pixar-style 3D, a vibrant meadow in golden afternoon light with wildflowers.",
        "image_url": ""
      }
    ],
    "objects": [
      {
        "name": "Acorn Flute",
        "description": "Style:Pixar-style 3D, a small polished acorn hollowed as a flute with three finger holes.",
        "image_url": ""
      },
      {
        "name": "Carrot Drum",
        "description": "Style:Pixar-style 3D, a miniature hollow carrot with a leaf membrane as drumhead.",
        "image_url": ""
      }
    ]
  }
}

audio_option

Audio configuration for story generation (JSON object). Used in idea-2-video, url-2-video, images-2-video, and advanced Step 1 (Create Storyboard).

Audio parameters

Parameter	Type	Default	Description
narrator	string	AutoV	Voice for narration. Available voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill
has_narration	boolean	true	Include narration. Ignored when native_audio is true
has_bg_music	boolean	true	Include background music
native_audio	boolean	false	Include native sound effects and lip sync. When true, narration is disabled

Usage examples (application/json)

Background music only:

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": false
}

Narration with background music:

{
  "has_bg_music": true,
  "has_narration": true,
  "native_audio": false,
  "narrator": "Rachel"
}

Native audio (sound effects + lip sync):

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": true
}

No audio:

{
  "has_bg_music": false,
  "has_narration": false,
  "native_audio": false
}

Notes

• When native_audio is true, has_narration is ignored (effectively false).
• narrator is only used when has_narration is true and native_audio is false.
• Send audio_option as a JSON object in the request body (Content-Type: application/json).

Creates a complete video from a website URL and idea. Send Content-Type: application/json.

The API uses the URL content plus your idea to generate a story and then runs the full pipeline. Poll GET /v2/story/{story_id} until status is success.

Example: URL-to-Video (Python)

import requests

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

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

payload = {
    "idea": "Create a cool, modern commercial-style video for this brand https://www.example.com/",
    "title": "Brand Commercial",
    "aspect_ratio": "16:9",
    "scene_count": 3,
    "image_tool": "AutoI",
    "video_tool": "Auto",
    "scene_duration": 5,
    "audio_option": {"has_bg_music": True, "has_narration": False, "native_audio": False},
    "language": "English",
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
print(f"Story ID: {result['id']}")

audio_option

Audio configuration for story generation (JSON object). Used in idea-2-video, url-2-video, images-2-video, and advanced Step 1 (Create Storyboard).

Audio parameters

Parameter	Type	Default	Description
narrator	string	AutoV	Voice for narration. Available voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill
has_narration	boolean	true	Include narration. Ignored when native_audio is true
has_bg_music	boolean	true	Include background music
native_audio	boolean	false	Include native sound effects and lip sync. When true, narration is disabled

Usage examples (application/json)

Background music only:

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": false
}

Narration with background music:

{
  "has_bg_music": true,
  "has_narration": true,
  "native_audio": false,
  "narrator": "Rachel"
}

Native audio (sound effects + lip sync):

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": true
}

No audio:

{
  "has_bg_music": false,
  "has_narration": false,
  "native_audio": false
}

Notes

• When native_audio is true, has_narration is ignored (effectively false).
• narrator is only used when has_narration is true and native_audio is false.
• Send audio_option as a JSON object in the request body (Content-Type: application/json).

Generates a story video from an idea and a list of image URLs. Send Content-Type: application/json.

Pipeline: narrations/music → animate each image → compose final video. Poll GET /v2/story/{story_id} until status is success.

Example: Images-to-Video (Python)

import requests

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

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

payload = {
    "idea": "Cinematic product-only smoothie promo: fresh berries, bananas, oranges on a wooden table, blender mixing, smoothie pouring into glass, 16:9, photorealistic.",
    "image_urls": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg",
        "https://example.com/image3.jpg",
    ],
    "title": "Smoothie Promo",
    "aspect_ratio": "16:9",
    "video_tool": "Auto",
    "is_transition": True,
    "scene_duration": 5,
    "audio_option": {"has_bg_music": True, "has_narration": True, "native_audio": False},
    "language": "English",
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
print(f"Story ID: {result['id']}, Scenes: {len(payload['image_urls'])}")

audio_option

Audio configuration for story generation (JSON object). Used in idea-2-video, url-2-video, images-2-video, and advanced Step 1 (Create Storyboard).

Audio parameters

Parameter	Type	Default	Description
narrator	string	AutoV	Voice for narration. Available voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill
has_narration	boolean	true	Include narration. Ignored when native_audio is true
has_bg_music	boolean	true	Include background music
native_audio	boolean	false	Include native sound effects and lip sync. When true, narration is disabled

Usage examples (application/json)

Background music only:

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": false
}

Narration with background music:

{
  "has_bg_music": true,
  "has_narration": true,
  "native_audio": false,
  "narrator": "Rachel"
}

Native audio (sound effects + lip sync):

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": true
}

No audio:

{
  "has_bg_music": false,
  "has_narration": false,
  "native_audio": false
}

Notes

• When native_audio is true, has_narration is ignored (effectively false).
• narrator is only used when has_narration is true and native_audio is false.
• Send audio_option as a JSON object in the request body (Content-Type: application/json).

Step 1 (Advanced): Creates a storyboard from an idea and/or image URLs.

Example: Create Storyboard (Python)

import requests

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

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

payload = {
    "idea": "Create a promotional video where cute animals play musical instruments in a sunny meadow",
    "scene_count": 3,
    "title": "Musical Animals",
    "language": "English",
    "aspect_ratio": "16:9",
    "audio_option": {
        "has_bg_music": True,
        "has_narration": True,
        "native_audio": False,
        "narrator": "AutoV",
    },
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
story_id = result["id"]
print(f"Storyboard created: {story_id}, Scenes: {len(result.get('storyboard', {}).get('scenes', []))}")

Example: Storyboard with image_urls

payload = {
    "idea": "Create a promotional video showcasing these landscapes",
    "title": "Landscape Story",
    "image_urls": [
        "https://example.com/landscape1.jpg",
        "https://example.com/landscape2.jpg",
        "https://example.com/landscape3.jpg",
    ],
}
response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
print(f"Story ID: {result['id']}")

elements

Optional JSON object of pre-defined story elements you already have in mind. The API uses these to guide storyboard generation (e.g. character names, environments, and props). Only characters, environments, and objects are accepted; scenes must not be included (scenes are generated from the idea).

Each key in elements must be a list of dictionaries (JSON objects), matching the storyboard structure (see example below).

Key	Type	Description
characters	array of objects	Optional. Each item is a JSON object with name, description, and optionally image_url.
environments	array of objects	Optional. Each item is a JSON object with name, description, and optionally image_url.
objects	array of objects	Optional. Each item is a JSON object with name, description, and optionally image_url.

Example (partial): Providing characters, one environment, and two objects so the storyboard uses them:

{
  "idea": "Create a promotional video where cute animals play musical instruments in a sunny meadow",
  "scene_count": 3,
  "elements": {
    "characters": [
      {
        "name": "Whiskers the Squirrel",
        "description": "Style:Pixar-style 3D, A small, nimble squirrel with rusty-red fur, bright eyes, bushy tail.",
        "image_url": ""
      },
      {
        "name": "Pip the Rabbit",
        "description": "Style:Pixar-style 3D, A plump, creamy white rabbit with long floppy ears, large blue eyes.",
        "image_url": ""
      }
    ],
    "environments": [
      {
        "name": "Sunny Meadow",
        "description": "Style:Pixar-style 3D, A vibrant meadow in golden afternoon light, lush grass, wildflowers, clear blue sky.",
        "image_url": ""
      }
    ],
    "objects": [
      {
        "name": "Acorn Flute",
        "description": "Style:Pixar-style 3D, A small polished acorn hollowed as a flute with three finger holes.",
        "image_url": ""
      },
      {
        "name": "Carrot Drum",
        "description": "Style:Pixar-style 3D, A miniature hollow carrot with a leaf membrane as drumhead.",
        "image_url": ""
      }
    ]
  }
}

If you omit elements or leave it empty, the storyboard is generated from the idea alone. When provided, the generated storyboard will reference these names and descriptions; you can later generate or replace images via POST /v2/story/{story_id}/elements.

audio_option

Audio configuration for story generation (JSON object). Used in idea-2-video, url-2-video, images-2-video, and advanced Step 1 (Create Storyboard).

Audio parameters

Parameter	Type	Default	Description
narrator	string	AutoV	Voice for narration. Available voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill
has_narration	boolean	true	Include narration. Ignored when native_audio is true
has_bg_music	boolean	true	Include background music
native_audio	boolean	false	Include native sound effects and lip sync. When true, narration is disabled

Usage examples (application/json)

Background music only:

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": false
}

Narration with background music:

{
  "has_bg_music": true,
  "has_narration": true,
  "native_audio": false,
  "narrator": "Rachel"
}

Native audio (sound effects + lip sync):

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": true
}

No audio:

{
  "has_bg_music": false,
  "has_narration": false,
  "native_audio": false
}

Notes

• When native_audio is true, has_narration is ignored (effectively false).
• narrator is only used when has_narration is true and native_audio is false.
• Send audio_option as a JSON object in the request body (Content-Type: application/json).

Step 1.5 (Advanced): Generates images for storyboard elements (characters, objects, environments).

Example: Create Element Images (Python)

import requests

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

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

payload = {
    "image_tool": "Seedream",
    "aspect_ratio": "16:9"
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
storyboard = result.get("storyboard", {})
for char in storyboard.get("characters", []):
    url_val = char.get("URL") or char.get("image_url")
    if url_val:
        print(f"Character '{char.get('name')}' image: {url_val}")

Step 2 (Advanced): Generates scene images and narrations from the storyboard. Send Content-Type: application/json.

Example: Create Scenes (Python)

import requests

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

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

payload = {
    "image_tool": "Seedream",
    "aspect_ratio": "16:9"
}

response = requests.post(url, headers=headers, json=payload, timeout=180)
response.raise_for_status()
result = response.json()
scenes = result.get("storyboard", {}).get("scenes", [])
print(f"Generated {len(scenes)} scenes")

audio_option

Audio configuration for story generation (JSON object). Used in idea-2-video, url-2-video, images-2-video, and advanced Step 1 (Create Storyboard).

Audio parameters

Parameter	Type	Default	Description
narrator	string	AutoV	Voice for narration. Available voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill
has_narration	boolean	true	Include narration. Ignored when native_audio is true
has_bg_music	boolean	true	Include background music
native_audio	boolean	false	Include native sound effects and lip sync. When true, narration is disabled

Usage examples (application/json)

Background music only:

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": false
}

Narration with background music:

{
  "has_bg_music": true,
  "has_narration": true,
  "native_audio": false,
  "narrator": "Rachel"
}

Native audio (sound effects + lip sync):

{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": true
}

No audio:

{
  "has_bg_music": false,
  "has_narration": false,
  "native_audio": false
}

Notes

• When native_audio is true, has_narration is ignored (effectively false).
• narrator is only used when has_narration is true and native_audio is false.
• Send audio_option as a JSON object in the request body (Content-Type: application/json).

Step 3 (Advanced): Creates videos from scene images and composes the story. Send Content-Type: application/json.

Example: Create Videos (Python)

import requests

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

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

payload = {
    "title": "My Amazing Story",
    "video_tool": "Auto",
    "duration": 5,
    "is_transition": True,
    "webhook_url": "https://your-domain.com/webhook/video-complete",
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
print(f"Video generation started: {result['id']}, Status: {result['status']}")

Retrieves a story by ID. Use this to poll until status is success and then read video_url.

Example: Get Story (Python)

import requests

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

url = f"{BASE_URL}/v2/story/{STORY_ID}"
headers = {"X-Api-Key": API_KEY}

response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
result = response.json()
print(f"Story ID: {result['id']}, Status: {result['status']}, Progress: {result.get('progress_percentage', 0)}%")
if result.get("status") == "success" and result.get("video_url"):
    print(f"Video URL: {result['video_url']}")

Permanently deletes a story. Returns the last snapshot of the deleted story. Requires authentication and ownership.