Name: Vimmerse Story – Text to Video | $0.12/call | API.market
Brand: vimmerse
SKU: api-vimmerse-idea-to-video
Availability: InStock
Author: API Market

Vimmerse

# Create Videos: Fast Idea-to-Video with Vimmerse Story

## Overview

The **Vimmerse Story API - Idea to Video API** allows you to generate multi-scene videos from a single text prompt.

Using advanced AI models, the API automatically:

- Creates structured storyboards
- Generates coherent scene visuals
- Produces voice narration and background music (optional)
- Composes a final MP4 video

The API is optimized for performance and scalability and uses asynchronous processing for efficient handling of video generation tasks.

## Features

*   **Text-to-Video Generation:** Transform textual ideas into videos automatically.
*   **Automatic Storyboarding:** Intelligent scene breakdown from your prompt.
*   **Multi-Scene Video Creation:** Generate structured multi-scene stories.
*   **Audio Options:** Add narration, background music, or native audio.
*   **High Performance:** Optimized processing pipeline.
*   **Easy Integration:** Simple REST API.
*   **Asynchronous Workflow:** Designed for long-running video generation tasks.

## Use Cases

*   **Advertising Campaigns:** Generate engaging video ads for social media to promote products or services. Create a series of ads around a specific product or marketing message and visually showcase key features.
*   **E-commerce Product Demos:** Showcase products with compelling video demonstrations. Create videos highlighting the features and benefits of a product to boost conversions.
*   **Restaurant Menu Promotion:** Promote restaurant menu items with visually appealing videos. Ideal for highlighting daily specials, new dishes, or showcasing the dining experience.
*   **Travel Destination Marketing:** Generate stunning videos highlighting travel destinations. Visually showcase key attractions, hotels, and activities for potential travelers.
*   **Entertainment Content Creation:** Produce short, engaging videos for entertainment purposes. Great for creating content for YouTube, TikTok, or other video-sharing platforms.

## Visual Examples

This API takes a text prompt as input and generates a video output. Below are some examples demonstrating the API's capabilities:

**Example 1:**

**Input:** A Halloween video from idea.
```json
{
    "idea": On Halloween evening, a mother gently places a wrapped box on her daughter’s bed — inside, a beautiful new dress shimmering in soft orange light. The girl slips it on and stands before the mirror, her eyes lighting up as she sees herself twirl for the first time. Behind her, the mother watches with a smile — because the most precious gift isn’t the dress itself, but the sparkle it brings to her little girl’s heart.
}
```
**Output:** A multi-scene Halloween-themed story with narration and background music.

![Example of a generated story video from idea](https://media.vimmerse.net/vimmerse-product/batch/6840e95a-75c4-4a39-9608-bc81869896b0/story/3/6840e95a-75c4-4a39-9608-bc81869896b0.mp4)

**Example 2 (Product Placement with Custom Element)**
```json
{
    "idea": Create a realistic winter commercial for SkinRevive Moisturiser set in snowy mountains. Three girls are on a winter camping trip. Show two girls outside the camp, dressed in warm jackets, taking fun photos together in the snowy mountains. Soft snowfall, visible cold breath, playful interaction. Meanwhile, one girl is sitting inside the tent, wrapped in a blanket, looking hesitant and afraid to step outside because of the cold and her dry, irritated hands. She peeks out while the others call her to join, but she hesitates. Then one girl comes inside the tent, sits with her, smiles, and shows SkinRevive Moisturiser. She gently applies it on her friend’s dry hands. Show close-up macro shots: smooth creamy texture, instant hydration, natural skin transformation. The inside girl now feels confident. She steps outside slowly, smiles, and joins her friends. Show them laughing, posing, and taking photos of each other against the beautiful snowy mountain background. Natural warm emotions, winter glow, soft daylight. End with a clean hero shot of SkinRevive Moisturiser placed on a wooden camping table with snowflakes falling softly around it. Cinematic, high-detail, warm winter storytelling mood."
    "scene_count": 5
    "audio_option": {"has_bg_music": true, "has_narration": false, "native_audio": true}
    "elements": {"objects": [{"name": "SkinRevive Moisturiser", "description": "Style:cinematic, In a sleek glass jar with a frosted finish and an elegant silver lid. The luxurious cream has a marbled white color, giving an aura of purity and soothing relief. Its rich formulation is the solution to winter's touch.", "image_url":"https://dev-media.vimmerse.net/vimmerse-product/ai_images/4a6b359a-c347-4453-a6ff-109cd8616dc4/8i9vvs4.png"}]}
}
```

![Example of a marketing video from idea + a product image](https://dev-media.vimmerse.net/vimmerse-product/batch/a2311a04-7f7e-40bc-927d-19a561ab1236/story/2/a2311a04-7f7e-40bc-927d-19a561ab1236.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/idrea-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/idea-to-video
```

### Authentication

Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing

**IMPORTANT**: This API uses asynchronous processing.

#### Standard Flow

1. Submit a `POST `request to create the video.
2. Receive a `story_id`.
3. Poll the `GET `endpoint using that ID.
4. Continue polling until status becomes `success` or `failed`.

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 `"new"` 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 Video from Idea

`POST /story/idea-2-video`

Initiates video generation.

**Request Body (application/json):**

| Field          | Type    | Required | Description                      |
| -------------- | ------- | -------- | -------------------------------- |
| idea           | string  | Yes      | Text prompt for video generation |
| scene_count    | integer | No       | Number of scenes                 |
| scene_duration | integer | No       | Duration per scene (seconds)     |
| audio_option   | object  | No       | Audio configuration              |
| elements       | object  | No       | Custom visual elements           |


**Request Example:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/idea-to-video/story/idea-2-video" \
-H "Content-Type: application/json" \
-H "x-api-market-key: YOUR_API_MARKET_KEY" \
-d '{"idea":"A robot chef preparing a gourmet meal in a futuristic kitchen"}'
```

**Success Response (200 OK)**

```json
{
  "data": {
    "id": "abc123-def456-ghi789",
    "title": "",
    "idea": "A robot chef preparing a gourmet meal in a futuristic kitchen",
    "scene_count": 5,
    "scene_duration": 5,
    "used_credits": 25,
    "progress_percentage": 0,
    "status": "new",
    "video_url": null,
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}

```

**Response (400 Bad Request)**
```json
{
  "detail": "Invalid input: 'idea' parameter missing"
}

```

#### 2. Get Video Creation Status

`GET /story/{story_id}`
Retrieves the current status and result.

**Example Request:**

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

**Processing Response**
```json
{
  "data": {
    "id": "...",
    "title": "",
    "is_transition": false,
    "idea": "...",
    "used_credits": 300,
    "progress_percentage": 50,
    "status": "processing",
    "video_url": "",
    "created_at": "2026-02-06 02:05:40.985431+00:00",
    "updated_at": "2026-02-06 02:05:40.985431+00:00"
  }
}
```

**Success Response**
```json
{
  "data": {
    "id": "...",
    "title": "",
    "is_transition": false,
    "idea": "...",
    "used_credits": 300,
    "progress_percentage": 100,
    "status": "success",
    "video_url": "",
    "created_at": "2026-02-06 02:05:40.985431+00:00",
    "updated_at": "2026-02-06 02:05:40.985431+00:00"
  }
}
```

**404 Not Found**
```json
{
  "detail": "Story not found"
}
```

**Response (422 Unprocessable Entity):**

```json
{
  "detail": [
    {
      "loc": ["path", "story_id"],
      "msg": "value is not a valid uuid",
      "type": "type_error.uuid"
    }
  ]
}
 ```

## Status Codes

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


## Rate Limits

Rate limits depend on your API.market plan.

Exceeding limits returns:
```bash
429 Too Many Requests
```

## Error Handling

Errors are returned in JSON format.

For transient errors (500/503):

*  Retry with exponential backoff.

For client errors (400/401/403):

*  Fix request before retrying.


## Implementation Guide

### Example Code

#### JavaScript

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

async function createAndWaitForVideo(idea) {
  try {
    // Step 1: Create the video
    const response = await fetch(`${baseUrl}/story/idea-2-video`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify({
          idea: idea,
          scene_count: 5
      })
    });

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

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

    // Step 2: Poll for results with timeout
    return await pollForVideo(storyId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

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

async function pollForVideo(storyId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    try {
      // Check video status
      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 videoData = await response.json();
      const status = videoData.data.status;
      const videoUrl = videoData.data.video_url;

      // Check status and return if completed
      if (status === "success") {
        return videoUrl;
      }

      // Handle failure
      if (status === "failed") {
        throw new Error(`Video creation failed`);
      }

       // Wait before next poll
      await delay(POLL_INTERVAL);

    } catch (error) {
        console.error("Error while polling:", error);
        await delay(POLL_INTERVAL); // Wait even on error before retrying
    }


  }

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

// Example usage:
createAndWaitForVideo("A robot chef preparing a gourmet meal in a futuristic kitchen.")
  .then(videoUrl => {
    console.log("Video URL:", videoUrl);
  })
  .catch(error => {
    console.error("Error:", error);
  });
```

#### Python

```python
import requests
import time
import urllib.parse

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


def create_and_wait_for_video(idea):
    """
    Creates a video from an idea and polls for its completion.
    """
    try:
        # Step 1: Create the video
        headers = {
            "Content-Type": "application/json",
            "x-api-market-key": API_KEY,
        }
        data = {
            "idea": idea
        }
        response = requests.post(
            f"{BASE_URL}/story/idea-2-video",
            headers=headers,
            json=data
        )

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

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

        # Step 2: Poll for results with timeout
        return poll_for_video(story_id)

    except Exception as e:
        print(f"Error in create_and_wait_for_video: {e}")
        raise


def poll_for_video(story_id):
    """
    Polls the API for the video's status until it's completed or a timeout is reached.
    """
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks

    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        try:
            # Check video status
            headers = {"x-api-market-key": API_KEY}
            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}")

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

            # Check status and return if completed
            if status == "success":
                return video_url

            # Handle failure
            if status == "failed":
                raise Exception(f"Video creation failed")

            # Wait before next poll
            time.sleep(POLL_INTERVAL)

        except Exception as e:
            print(f"Error in poll_for_video: {e}")
            time.sleep(POLL_INTERVAL) # Wait even on error before retrying
            continue

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


# Example usage:
if __name__ == "__main__":
    try:
        video_url = create_and_wait_for_video("A robot chef preparing a gourmet meal in a futuristic kitchen")
        print(f"Video URL: {video_url}")
    except Exception as e:
        print(f"Error: {e}")
```

#### cURL

```bash
# Step 1: Create a video
curl -X POST "https://prod.api.market/api/v1/magicapi/idea-to-video/story/idea-2-video" \
-H "Content-Type: application/json" \
-H "x-api-market-key: YOUR_API_MARKET_KEY" \
-d '{"idea":"A robot chef preparing a gourmet meal in a futuristic kitchen"}'

# Response will contain a Story ID like:
# {"data": {"id": "story-123", "url": null, "status": "new"}}

# Step 2: Check video creation status (replace story-123 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/idea-to-video/story/story-123" \
-H "x-api-market-key: YOUR_API_MARKET_KEY"

# Note: You need to repeatedly poll this endpoint manually until status is "success"
```

### Performance Optimization

*   Reduce the size and complexity of your input idea prompts to improve processing speed.
*   Implement proper error handling and retry mechanisms to handle transient API errors.
*   Monitor your API usage to ensure you are not exceeding your rate limits.
*   Avoid rapid polling. Adhere to the recommended polling interval of 1 second.

## FAQ

**Q: How long does it take to generate a video?**

A: Video generation time varies depending on the complexity of the input idea and current system load. You can expect it to take anywhere from a few seconds to several minutes. Your code should implement appropriate timeout handling.

**Q: What happens if the video creation fails?**

A: The API will return a `"failed"` status, and the `url` field will be empty. Check your input idea and try again. Review the error message for more information if available.

**Q: Can I generate videos of any length?**

A: The API is optimized for generating short, engaging videos. Longer video lengths might be limited by the model and may result in errors or unexpected behavior.

**Q: What type of video format does the API generate?**

A: The API generates videos in MP4 format.

**Q: Is there any limit to the number of video requests I can make?**

A: Rate limits are in place to ensure fair usage of the API. Please refer to the Rate Limits section for more details. Contact API.market support for questions regarding your specific rate limit.

**Q: What does the `422 Unprocessable Entity` error mean?**

A: This error usually indicates a validation issue with the request. For example, the `story_id` in the `GET /story/{story_id}` endpoint must be a valid UUID.

## 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.
```

Generate multi-scene videos from a single text prompt. With AI storyboarding and optional narration. From $0.12/call. Try it free on API.market.