Story

Creates a complete video automatically based on your idea prompt. Once the request is submitted, Vimmerse automatically:

1. Generates a storyboard with characters, environments, and scenes
2. Creates element images (characters, objects, environments) for consistency
3. Generates scene images based on the storyboard
4. Creates voice narrations for each scene
5. Generates background music
6. Animates the images into videos
7. Composes all scene videos into a final video

The API returns a story object containing story_id and generation status. You can check progress using GET /story/{story_id} or receive a callback via webhook_url.

Parameters

• idea (required): Text description of your story idea
• scene_count (optional): Number of scenes to generate (default: 3, max: varies by plan)
• aspect_ratio (optional): Video aspect ratio - '16:9', '4:3', '1:1', '3:4', '9:16' (default: '16:9')
• option (optional): Image generation model - 'Seedream', 'FluxKontextPro', etc. (default: 'Seedream')
• motion_type (optional): Animation method - 'Auto', 'KlingAI', 'VeoFast', etc. (default: 'Auto')
• generate_elements (optional): Enable character consistency elements (default: True)
• enhance_image (optional): Apply super-resolution enhancement (default: False)
• audio_option (optional): Audio options - 'has_bg_music', 'has_narration', 'native_audio', 'narrator' (default: 'Rachel')
• elements (optional): Initial elements (e.g. characters, environments, objects) to be included in story. This can be useful to set a hero character in a film or logo of a product.
• language (optional): Narration language (default: 'English')
• duration (optional): Duration per scene in seconds, 1-10 (default: 5)
• webhook_url (optional): URL for completion callback

Example Code

import requests

url = "https://api.vimmerse.net/story/idea-2-video"

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
}
payload = {
    'idea': 'Create a promotional video where cute animals play musical instruments.',
    'title': 'Example Story',
    'aspect_ratio': '9:16',
    'scene_count': 3,
    'audio_option': '{"has_bg_music": True, "has_narration": True, "native_audio": False, "narrator": "Rachel"}',
    'elements': '{"objects": [{"name": "logo","description": "logo of vimmerse","image_url": "https://www.vimmerse.net/Vimmerse-logo.png"}]}',
    'language': 'English'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Generates a story video using both your idea and a set of existing images. This mode is ideal when you want to maintain character consistency or use your own art style as a reference.

The workflow:

1. Takes your provided images and idea
2. Generates appropriate voice narrations for each scene
3. Creates background music
4. Animates each image into a video with motion
5. Composes all scene videos into a final story video

Parameters

• idea (required): Text description of your story idea
• image_urls (required): Array of image URLs to animate (or use image_files for uploads)
• image_files (optional): Upload image files directly
• aspect_ratio (optional): Video aspect ratio (default: '16:9')
• motion_type (optional): Animation method - 'Auto', 'KlingAI', 'VeoFast', etc. (default: 'Auto')
• is_transition (optional): Create transition videos between scenes (default: False)
• audio_option (optional): Audio options - 'has_bg_music', 'has_narration', 'native_audio', 'narrator' (default: 'Rachel')
• language (optional): Narration language (default: 'English')
• duration (optional): Duration per scene in seconds, 1-10 (default: 5)
• loop (optional): Number of motion repetitions, 1-6 (default: 1)
• webhook_url (optional): URL for completion callback

Example Code

import requests

url = "https://api.vimmerse.net/story/images-2-video"

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
}
payload = {
    'idea': 'Create a promotional video showcasing these beautiful landscapes with a cinematic style.',
    'title': 'Landscape Video',
    'aspect_ratio': '16:9',
    'image_urls': [
        'https://example.com/landscape1.png',
        'https://example.com/landscape2.png',
        'https://example.com/landscape3.png',
        'https://example.com/landscape4.png'
    ],
    'motion_type': 'KlingAI',
    'audio_option': {
        'has_bg_music': True,
        'has_narration': True,
        'native_audio': False,
        'narrator': 'Rachel'
    }
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

This API creates a new storyboard (Step 1 of Advanced Mode) based on your idea and/or images.

What it does:

• Generates a complete storyboard with characters, environments, objects, and scenes
• Creates narrations for each scene
• Defines camera movements and lighting for each scene
• Sets up the story structure for subsequent steps

Next steps:

1. POST /story/{story_id}/elements (Optional) - Generate element images for consistency
2. POST /story/{story_id}/scenes - Generate scene images and narrations
3. POST /story/{story_id}/videos - Create videos from the scenes

Generate Story with Idea

import requests

url = "https://api.vimmerse.net/story"

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
}
payload = {
    'idea': 'Create a promotional video where cute animals play musical instruments.',
    'scene_count': 3,
    'title': 'Example Story',
    'language': 'English',
    'audio_option': {
        'has_bg_music': True,
        'has_narration': True,
        'native_audio': False,
        'narrator': 'Rachel'
    }
}

response = requests.request("POST", url, headers=headers, data=payload)

story_data = response.json()
print(story_data)

Parameters:

• idea (required): Your story concept
• scene_count (optional): Number of scenes, default 3
• language (optional): Language for storyboard generation
• audio_option (optional): Audio options - 'has_bg_music', 'has_narration', 'native_audio', 'narrator' (default: 'Rachel')

Generate Story with Idea and Images

import requests

url = "https://api.vimmerse.net/story"

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
}
payload = {
    'idea': 'Create a promotional video where cute animals play musical instruments.',
    'title': 'Example Story',
    'image_urls': [
        'https://example.com/image1.png',
        'https://example.com/image2.png',
        'https://example.com/image3.png',
        'https://example.com/image4.png'
    ],
}

response = requests.request("POST", url, headers=headers, data=payload)

story_data = response.json()
print(story_data)

Note: When providing images, the scene_count will automatically match the number of images provided.

This API generates images of your characters, objects, environments, and background music based on your storyboard.

Send a POST request with or without storyboard to generate element images from your storyboard. If you already have images for your characters, objects, or environments, include the image URLs in the same level as the name and description fields of each scene. if you already have background music, you can just add music_url under music object under storyboard.

If you are generating story with idea and images, you will not need to call this API.

Example Code

import requests

url = "https://api.vimmerse.net/story/{STORY_ID}/elements"

payload = {
    'aspect_ratio': '16:9',
    'option': 'Seedream'
    'seed': 4669,
}
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

This API crafts missing images and narrations of scenes, background music in storyboard.

Send a POST request to generate scene images(if needed), narrations and background music from storyboard.

Example Code

Generate scene images without updating the storyboard.

import requests

url = "https://api.vimmerse.net/story/{STORY_ID}/scenes"

payload = {
    'aspect_ratio': '16:9',
    'option': 'Seedream'
    'seed': '4669',
}
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Generate scene images with updating storyboard.

import requests

url = "https://api.vimmerse.net/story/{STORY_ID}/scenes"

payload = {
    'aspect_ratio': '16:9',
    'seed': '4669',
    'option': 'Seedream'
    'storyboard': json.dumps({...storyboard})
}
headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

This API creates videos from your storyboard and scenes.

You can view the generated media in the response. Once all media are processed, your final story video will be available at the video_url field in the response.

Example Code

Create story video without updating scenes.

import requests

url = "https://api.vimmerse.net/story/{STORY_ID}/videos"

payload = {
    "title": "Example story from vimmerse",
    "motion_type": "KlingAI",
}

headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Create story video with updating storyboard and scenes.

import requests

url = "https://api.vimmerse.net/story/{STORY_ID}/videos"

payload = {
    "title": "Example story video from vimmerse",
    "storyboard": {...storyboard},
    "scenes": {...scenes}
}

headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

This API retrieves a Story object.

status field shows current progressing status of this Story.

if Story is finished, you can get composed video from video_url. Send a GET request to get your story video.

Example Code

Get a new Story example

import requests

url = "http://api.vimmerse.net/story/{STORY_ID}"

headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

Delete story