Name: Vimmerse Story – Animate Still Images | $0.12/call | API.market
Brand: vimmerse
SKU: api-vimmerse-images-to-video
Availability: InStock
Author: API Market

Vimmerse

# Images to Video: Create compelling stories with Vimmerse Story

## Overview

The **Vimmerse Story – Images to Video API** allows you to transform a series of images into engaging multi-scene MP4 videos complete with voice narration and background music.

This API is built for developers who want to programmatically generate video content for:
- Advertising campaigns
- E-commerce product demos
- Travel storytelling
- Restaurant promotions
- Entertainment content

The API processes requests asynchronously, meaning you submit a job and poll for completion.

## Features

*   **Automated Video Creation:** Convert images into full-fledged videos with minimal effort.
*   **Voice Narration:** Automatically add voice narration to guide viewers through your story.
*   **Background Music:** Enhance the video with background music to create a more engaging experience.
*   **Multi-Scene Support:** Create videos with multiple scenes seamlessly stitched together.
*   **Asynchronous Processing:** Submit your request and check its status later, allowing for large-scale video generation.

## Use Cases

*   **Advertising:** Generate video ads for products or services using a set of product images and descriptions.
*   **E-commerce:** Create product demo videos by showcasing product images and highlighting key features.
*   **Travel:** Transform travel photos into engaging travel stories with voiceovers and music, perfect for sharing experiences or promoting destinations.
*   **Food & Restaurants:** Create appetizing videos of menu items or cooking processes to attract customers.
*   **Entertainment:** Quickly create short animated stories or explainers using image sequences and a script.

## Visual Examples

Here are a few examples that you can generate via this API:

**Example1:**

**Input:** Make marketing ad showing the making of a cocktail drink using images.
```
"idea": "Cinematic product-only smoothie promo: fresh berries, bananas, and oranges falling onto rustic wooden table in slow-motion, glass blender mixing fruits with smoothie swirling inside, smoothie pouring from blender into glass with condensation, pink smoothie glass showcased on wooden table in top-down and angled shots, cinematic lighting, photorealistic textures, colorful and vibrant, no humans, final branding overlay with tagline 'Freshness in Every Sip', 16:9, consistent warm cinematic glow across all scenes"

image_urls:[
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_101637_7c5ygv.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_101654_jpj5wi.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_101711_3tw2er.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_101742_vkcfl9.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_101802_75q49f.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_101837_jhqbhc.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/a979b86e-abf2-476e-b1ec-3a13657caee9/uploads/20250924_102132_s8xzfv.jpg"
]

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

**Output:** A multi-scene video showcasing different ingredients of a cocktail drink, complete with voice narration and background music.

![Example of a cocktail making video from raw ingredients](https://media.vimmerse.net/vimmerse-product/batch/fe4a70fe-69fe-4047-abc5-c8a80251e953/story/2/fe4a70fe-69fe-4047-abc5-c8a80251e953.mp4)

**Example2:**

**Input:** Animated Pixar story from images.
```
idea: "Animated story of Charlie, cheerful young person with short brown hair, casual clothes in morning, festive outfits later, consistent appearance across all scenes, cinematic lighting, high detail, warm festive colors. Make it in 3D Pixar style."
image_urls:[
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/zd2f0q.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/nkeh11.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/c4khlw.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/q1kq79.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/vgpk83.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/xe929j.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/ajqmkf.jpg",
    "https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/obfa5z.jpg"
]
audio_option: {"has_bg_music": true, "has_narration": true, "native_audio": false, "narrator": "Charlie"}
```

**Output:** A multi-scene video showcasing the animated story, complete with voice narration and background music.

![Example of a Christmas spirit](https://media.vimmerse.net/vimmerse-product/batch/2fd523c4-ecef-4301-b407-44550da3a039/story/1/2fd523c4-ecef-4301-b407-44550da3a039.mp4)


## Pricing

*   **1 unit = 1 second of video processed when using standard video tools.**
*    **1 unit = 2 second of video processed when using economy video tools.**
*   Standard video tools: Auto, KlingAI, Seedance, Pixverse, VeoFast, Vidu
*   Economy video tools: AutoT1, VeoLite, PVideo
*   Native audio doubles the unit cost.
*   GET requests to check prediction status (`GET /api/v1/magicapi/idea-to-video/story/{story_id}`) are free.

#### Scene-Based Pricing.

| Configuration                       | Units |
| ----------------------------------- | ----- |
| 5-second scene using economy video tool (no native audio)    | 2.5     |
| 5-second scene using standard video tool (no native audio)  | 5    |
| 10-second scene using economy video tool (with native audio)   | 10    |
| 10-second scene using standard video tool (with native audio) | 20    |


    #### Story Examples

    *   A story with 3 scenes, each 5 seconds long using economy video tool without native audio, costs 7.5 units (3 × 2.5 × 1).
    *   A story with 5 scenes, each 10 seconds long using standard video tool with native audio, costs 100 units (5 × 10 × 2).

#### Get Request
*  GET requests to check prediction status `(GET /api/v1/magicapi/images-to-video/story/{story_id})` are free and do not consume units.

#### Volume Pricing
*  Multiple pricing tiers are available based on overall usage. Reach out to info@vimmerse.net for enterprise deals.


## API Documentation

### Base URL

```bash
https://prod.api.market/api/v1/magicapi/images-to-video
```

### Authentication

Include your API key in the request header:

```bash
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Workflow

**IMPORTANT**: This API uses asynchronous processing for predictions. The typical flow is:

1. Send `POST `/story/images-2-video
2. Receive `story_id`
3. Poll `GET` `/story/{story_id}`
4. Wait until `status = success`

The processing time varies depending on the complexity of the request. Your code should implement:

*   A polling interval of 1 second between status checks.
*   A maximum timeout of 600 seconds (10 minutes).
*   Status checking logic that continues while status is "starting" or "processing".
*   Result handling when status becomes "success".
*   Error handling when status becomes "failed" or timeout is reached.

See the Implementation Guide section for code examples.

### Endpoints

#### 1. Create Images-to-Video Story

`POST /api/v1/magicapi/images-to-video/story/images-2-video`

Creates a new video from images.

**Request Body**

`Content-Type: application/json`


**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/images-to-video/story/images-2-video" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
        "idea": "Cinematic smoothie promo with warm lighting",
        "image_urls": [
            "https://example.com/image1.jpg",
            "https://example.com/image2.jpg"
        ],
        "aspect_ratio": "16:9",
        "scene_duration": "5",
        "is_transition": false,
        "video_tool": "Auto",
        "audio_option": {
            "has_bg_music": true,
            "has_narration": true,
            "native_audio": false,
            "narrator": "Rachel"
        }
      }'

```

**Response Body:** `application/json`

**Example Response:**

```json
{
  "data": {
    "id": "abc123-def456",
    "title": "",
    "is_transition": false,
    "idea": "Cinematic smoothie promo with warm lighting",
    "used_credits": 50,
    "progress_percentage": 0,
    "status": "new",
    "video_url": null,
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}

```

#### 2. Get Story Detail

`GET /api/v1/magicapi/images-to-video/story/{story_id}`

Returns generation status and final video URL.

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/images-to-video/story/abc123-def456" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Body:** `application/json`

**Processing Response**

```json
{
  "data": {
    "id": "abc123-def456",
    "title": "",
    "is_transition": false,
    "idea": "Cinematic smoothie promo with warm lighting",
    "used_credits": 150,
    "progress_percentage": 60,
    "status": "processing",
    "video_url": null,
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}
```

**Success Response**

```json
{
  "data": {
    "id": "abc123-def456",
    "title": "",
    "is_transition": false,
    "idea": "Cinematic smoothie promo with warm lighting",
    "used_credits": 150,
    "progress_percentage": 100,
    "status": "success",
    "video_url": "https://media.vimmerse.net/.../video.mp4",
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}
```


## Status Codes

| Code | Meaning                  |
| ---- | ------------------------ |
| 200  | Request successful       |
| 400  | Invalid request          |
| 401  | Missing/invalid API key  |
| 403  | Insufficient permissions |
| 404  | Story not found          |
| 429  | Rate limit exceeded      |
| 500  | Server error             |
| 503  | Service unavailable      |


## Rate Limits

Rate limits depend on your API.market subscription plan.

If exceeded, the API returns:
```bash
429 Too Many Requests
```
Implement exponential backoff retry logic


## Error Handling

Errors are returned in JSON format.

**Example**
```json
{
    "message": "BAD_REQUEST"
}
```

Here's how to handle common errors:

*   **`invalid_parameter`:** One or more request parameters are invalid. Check the error message for details.
*   **`resource_not_found`:** The requested resource (e.g., story with a given ID) was not found.
*   **`rate_limit_exceeded`:** You have exceeded the API rate limit. Implement retry logic with exponential backoff.
*   **`internal_server_error`:** An unexpected error occurred on the server. Retry the request. If the error persists, contact support.

For 5xx errors, retry with exponential backoff.

For 4xx errors, fix the request before retrying.

## Implementation Guide

### Example Code

#### JavaScript

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/images-to-video";

async function createAndWaitForPrediction(imageUrls) {
    try {
        // Step 1: Create the video
        const response = await fetch(`${baseUrl}/story/images-2-video`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-market-key": apiKey
            },
            body: JSON.stringify({
                idea: "Create a stunning video showcasing these images",
                image_urls: imageUrls,
                aspect_ratio: "16:9",
                scene_duration: "5",
                is_transition: false,
                video_tool: "Auto"
            })
        });

        if (!response.ok) {
            throw new Error(`API error: ${response.status} ${response.statusText}`);
        }

        const story = await response.json();
        const storyId = story.data.id;

        return await pollForResults(storyId);

    } catch (error) {
        console.error("Error creating story:", error);
        throw error;
    }
}

function delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(storyId) {
    const MAX_TIMEOUT = 600000; // 10 minutes
    const POLL_INTERVAL = 1000; // 1 second
    const startTime = Date.now();

    while (Date.now() - startTime < MAX_TIMEOUT) {

        const response = await fetch(`${baseUrl}/story/${storyId}`, {
            headers: {
                "x-api-market-key": apiKey
            }
        });

        if (!response.ok) {
            throw new Error(`API error: ${response.status} ${response.statusText}`);
        }

        const result = await response.json();
        const status = result.data.status;

        if (status === "success") {
            return result.data.video_url;
        }

        if (status === "failed") {
            throw new Error("Video generation failed");
        }

        await delay(POLL_INTERVAL);
    }

    throw new Error("Video creation timed out after 10 minutes");
}

// Usage
createAndWaitForPrediction([
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
])
.then(videoUrl => console.log("Video URL:", videoUrl))
.catch(err => console.error(err));

```

#### Python

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/images-to-video"


def create_and_wait_for_prediction(image_urls):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }

    payload = {
        "idea": "Create a stunning video showcasing these images",
        "image_urls": image_urls,
        "aspect_ratio": "16:9",
        "scene_duration": "5",
        "is_transition": False,
        "video_tool": "Auto"
    }

    response = requests.post(
        f"{BASE_URL}/story/images-2-video",
        headers=headers,
        json=payload
    )

    if response.status_code != 200:
        raise Exception(f"API error: {response.status_code} {response.text}")

    story_id = response.json()["data"]["id"]

    return poll_for_results(story_id)


def poll_for_results(story_id):
    headers = {"x-api-market-key": API_KEY}

    MAX_TIMEOUT = 600  # seconds
    POLL_INTERVAL = 1
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:

        response = requests.get(
            f"{BASE_URL}/story/{story_id}",
            headers=headers
        )

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        data = response.json()["data"]
        status = data["status"]

        if status == "success":
            return data["video_url"]

        if status == "failed":
            raise Exception("Video generation failed")

        time.sleep(POLL_INTERVAL)

    raise Exception("Video creation timed out after 10 minutes")


# Usage
if __name__ == "__main__":
    try:
        video_url = create_and_wait_for_prediction([
            "https://example.com/image1.jpg",
            "https://example.com/image2.jpg"
        ])
        print("Video URL:", video_url)
    except Exception as e:
        print("Error:", e)

```

#### cURL

```bash
# Step 1: Create video
curl -X POST "https://prod.api.market/api/v1/magicapi/images-to-video/story/images-2-video" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
        "idea": "Create a stunning video showcasing these images",
        "image_urls": [
            "https://example.com/image1.jpg",
            "https://example.com/image2.jpg"
        ],
        "aspect_ratio": "16:9",
        "scene_duration": "5",
        "is_transition": false,
        "video_tool": "Auto"
      }'

# Step 2: Poll status
curl -X GET "https://prod.api.market/api/v1/magicapi/images-to-video/story/STORY_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

```

### Performance Optimization

*   **Optimize Images:** Ensure the input images are appropriately sized and optimized for web delivery.
*   **Monitor Usage:** Track your API usage to stay within rate limits and optimize your integration.
*   **Implement Caching:** Cache API responses where appropriate to reduce the number of API calls.
*   **Efficient Polling:** Use a reasonable polling interval to balance responsiveness and API usage.

## FAQ

*   **How long does it take to generate a video?** The processing time varies depending on the complexity of the request. It can range from a few seconds to several minutes.
*   **What image formats are supported?** The API supports common image formats such as JPEG, PNG, and GIF.
*   **Can I customize the voice narration?** *(If the API allows it:)* Yes, you can customize the voice narration by providing a script along with the images. *(If the API doesn't allow it:)* Currently, voice narration customization is not supported.
*   **What is the maximum number of images I can use to create a video?** *(Specify the limit if there is one)*. There is currently no maximum limit.
*   **Can I get the status of the video generation process?** Yes, you can use the `GET /story/{story_id}` endpoint to check the status of a video.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to support@vimmerse.net.


Turn static images into multi-scene videos with narration and background music. From $0.12/call. Try it free on API.market.