Name: Vimmerse URL – Web Page to Video | $0.12/call | API.market
Brand: vimmerse
SKU: api-vimmerse-url-to-video
Availability: InStock
Author: API Market

Vimmerse

# Vimmerse Story - Url to Video

## Overview

The **Vimmerse Story - Url to Video API** allows you to automatically generate multi-scene videos from a website URL.

Simply provide a URL, and the API handles:
*   Content extraction
*   Storyboard generation
*   Scene design
*   Voice narration
*   Background music
*   Animation
*   Final video composition

The entire process is asynchronous and requires polling for completion.

## Features

*   **Automatic Storyboard Generation:** Extracts meaningful content from the webpage and builds a structured multi-scene narrative.
*   **Consistent Visual Elements:** Generates coherent characters, objects, environments, and scene compositions.
*   **Voice Narration & Audio:** Optional AI narration and/or native audio with background music.
*   **Scene Transitions:** Optional smooth transitions between scenes.
*   **Fully Composed Final Video:** Returns a downloadable video URL upon completion.


## Use Cases

*   **E-commerce Product Demos:** Quickly create engaging product demo videos from product page URLs to boost sales and conversions.
*   **Restaurant Menu Promotion:** Turn your restaurant's menu URL into a visually appealing video showcasing your dishes and ambiance.
*   **Travel Destination Highlights:** Generate compelling travel videos from destination websites to attract potential tourists.
*   **Advertising Video Production:** Easily create advertising videos from landing page URLs for various campaigns.
*   **Entertainment Content Creation:** Automate video creation for entertainment websites, turning articles or blog posts into engaging video content.

## Visual Examples

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

**Example1:**

**Input:** Website URL of a travel blog article about Rome.
`"idea": https://www.rome.net/`

**Output:** A multi-scene video showcasing various attractions in Rome, complete with voice narration and background music.

![Example of a generated video about Rome](https://media.vimmerse.net/vimmerse-product/batch/cfca713e-2d22-4108-be45-c132c60759cc/story/2/cfca713e-2d22-4108-be45-c132c60759cc.mp4)

**Example2:**

**Input:** Website URL of the world bank composed of 5 scenes transitioning in a continuous manner.
```
"idea": "https://www.worldbank.org/ext/en/home",
"scene_count": 5,
"is_transition": true
```

**Output:** A multi-scene video showcasing various initatives by the bank with scenes transitioning together, complete with voice narration and background music.

![Example of a generated video about World Bank](https://media.vimmerse.net/vimmerse-product/batch/83125048-8139-44ea-83fb-2e69c57769c9/story/1/83125048-8139-44ea-83fb-2e69c57769c9.mp4)

**Example3:**

**Input:** Website URL of a Pizza company along with a curated marketing message + usage of a logo as an element in the story. Story is made with native audio!
```
"idea": https://www.dominos.com/ Create a cool, modern commercial-style video. Keep the Domino’s logo accurate and consistent in every scene. Do not add any extra graphics, text, or elements.Cinematic lighting, smooth camera motion, premium ad look.Maintain the same characters and product throughout all scenes.
"scene_count": 3
"audio_option": {"has_bg_music": true, "has_narration": false, "native_audio": true}
"elements": {"objects": [{"name": "logo", "description": "logo of dominos", "image_url":"https://m.dominos.co.in/postorder-ui/images/appLogo@2x.png"}]}
```

**Output:** A 3-scene video showcasing Dominos pizza, complete with native audio and background music.

![Example of a generated video about Dominos Pizza](https://media.vimmerse.net/vimmerse-product/batch/ed135a5f-1a2b-43fe-902c-e27561345241/story/3/ed135a5f-1a2b-43fe-902c-e27561345241.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/url-to-video/story/{story_id})` are free.

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


## API Documentation

### Base URL
```
https://prod.api.market/api/v1/magicapi/url-to-video
```

### Authentication

Include your API key in the request header:

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

### Status Lifecycle

| Status       | Description                        |
| ------------ | ---------------------------- |
| `new`        | Request accepted             |
| `starting`   | Processing initialized       |
| `processing` | Video generation in progress |
| `success`    | Video completed successfully |
| `failed`     | Video generation failed      |


### Typical Workflow (Asynchronous)

1. Send a `POST` request to create the video
2. Receive a `story_id`
3. Poll the `GET `endpoint
4. Continue polling until `status = success`
5. Retrieve `video_url`

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 video generation is in progress
*   Result handling when the video has been generated and is ready
*   Error handling when an issue arises during video generation or timeout is reached

### Endpoints

#### 1. Create a Video from URL

`POST /story/url-2-video`

Creates a new multi-scene video generation task.

**Request Body:**
| Field            | Type    | Required | Default | Description                                                |
| ---------------- | ------- | -------- | ------- | ---------------------------------------------------------- |
| `idea`           | string  | ✔        | —       | Website URL (may include additional creative instructions) |
| `scene_count`    | integer | ✖        | 3| Number of scenes to generate                               |
| `scene_duration` | integer | ✖        | 5       | Duration per scene (seconds)                               |
| `is_transition`  | boolean | ✖        | false   | Enable smooth transitions between scenes                   |
| `aspect_ratio`   | string  | ✖        | 16:9    | Output video aspect ratio                                  |
| `audio_option`   | object  | ✖        | null    | Audio configuration                                        |
| `elements`       | object  | ✖        | null    | Custom visual elements (logos, objects, etc.)              |

**Audio Option Object**
| Field           | Type    | Description                                  |
| --------------- | ------- | -------------------------------------------- |
| `has_bg_music`  | boolean | Add background music                         |
| `has_narration` | boolean | Add AI voice narration                       |
| `native_audio`  | boolean | Use native website audio (doubles unit cost) |
| `narrator`  | string| Voice of the narration (**Available voices:** Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill) |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/url-to-video/story/url-2-video" \
-H "Content-Type: application/json" \
-H "x-api-market-key: YOUR_API_MARKET_KEY" \
-d '{
  "idea": "https://www.vimmerse.net/",
  "scene_count": 5,
  "scene_duration": 5,
  "is_transition": true,
  "aspect_ratio": "16:9",
  "audio_option": {
      "has_bg_music": true,
      "has_narration": false,
      "native_audio": true
  }
}'
```

**Success Response (200 OK)**

```json
{
  "data": {
    "id": "story_abc123",
    "title": "",
    "idea": "https://www.vimmerse.net/",
    "scene_count": 5,
    "scene_duration": 5,
    "used_credits": 250,
    "progress_percentage": 0,
    "status": "new",
    "video_url": null,
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}
```

**Example Response (Error - 400 Bad Request):**

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "idea"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

#### 2. Get Video Generation Status

`GET /story/{story_id}`

Retrieves current status and video result.

**Example Request:**

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

**Response While Processing**

```json
{
  "data": {
    "id": "story_abc123",
    "title": "",
    "idea": "https://www.vimmerse.net/",
    "scene_count": 5,
    "scene_duration": 5,
    "used_credits": 250,
    "progress_percentage": 60,
    "status": "processing",
    "video_url": null,
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}
```

**Response When Complete**

```json
{
  "data": {
    "id": "story_abc123",
    "title": "",
    "idea": "https://www.vimmerse.net/",
    "scene_count": 5,
    "scene_duration": 5,
    "used_credits": 250,
    "progress_percentage": 100,
    "status": "success",
    "video_url": "https://media.vimmerse.net/....mp4",
    "created_at": "2026-02-06T02:05:40Z",
    "updated_at": "2026-02-06T02:05:40Z"
  }
}
```

**Example Response (Not Found - 404 Not Found):**

```json
{
  "detail": "Story not found"
}
```

## Status Codes

*   200 OK: Request successful.
*   400 Bad Request: Invalid input parameters or malformed request. Review the request and ensure all required fields are present and valid.
*   402 Payment Required: Payment is required to proceed. Please check your payment method on API.Market.
*   404 Not Found: Resource not found. The requested resource, such as the `story_id`, does not exist.
*   422 Unprocessable Entity: Input validation failed. Review the error details in the response body for specific validation errors.
*   500 Internal Server Error: Server-side error. Contact support if the issue persists.

## Rate Limits

If rate limits are exceeded, the API returns:
```bash
429 Too Many Requests
```
Recommended handling:

- Retry with exponential backoff
- Do not retry 400/401/403 errors
- Safe to retry 500-level errors

Specific rate limits depend on your API.market plan.


## Error Handling

Validation errors follow structured format:
```json
{
  "detail": [
    {
      "loc": ["body", "idea"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

```

*   `loc`: Indicates the location of the error (e.g., the parameter that caused the error).
*   `msg`: A human-readable error message.
*   `type`: The type of error.

For transient errors (e.g., 500 Internal Server Error), implement a retry mechanism with exponential backoff.

## Implementation Guide

#### Javascript (Node.js)
```javascript
const fetch = require("node-fetch");

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

async function createAndWait(url) {

  const createRes = await fetch(`${baseUrl}/story/url-2-video`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ idea: url })
  });

  const createData = await createRes.json();
  const storyId = createData.data.id;

  return await poll(storyId);
}

async function poll(storyId) {
  const MAX_TIMEOUT = 600000;
  const INTERVAL = 1000;
  const start = Date.now();

  while (Date.now() - start < MAX_TIMEOUT) {
    const res = await fetch(`${baseUrl}/story/${storyId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    const data = await res.json();
    const status = data.data.status;

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

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

    await new Promise(r => setTimeout(r, INTERVAL));
  }

  throw new Error("Timeout waiting for video generation");
}
```

#### Python Example

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

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

def create_and_wait_for_video(url):
    """
    Creates a video from a URL and waits for it to be generated.
    """
    try:
        # Step 1: Create the video request
        headers = {
            "Content-Type": "application/json",
            "x-api-market-key": API_KEY
        }
        data = {
            "idea": url,
            "scene_count": 5
        }

        create_response = requests.post(f"{BASE_URL}/story/url-2-video", headers=headers, json=data)
        create_response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)

        create_data = create_response.json()
        story_id = create_data["data"]["id"]

        # Step 2: Poll for the video
        return poll_for_video(story_id)

    except requests.exceptions.RequestException as e:
        print(f"Error during request: {e}")
        raise
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
        raise

def poll_for_video(story_id):
    """
    Polls the API until the video is generated or a timeout is reached.
    """
    MAX_TIMEOUT = 600  # Seconds (10 minutes)
    POLL_INTERVAL = 1  # Seconds

    start_time = time.time()
    while time.time() - start_time < MAX_TIMEOUT:
        try:
            headers = {"x-api-market-key": API_KEY}
            get_response = requests.get(f"{BASE_URL}/story/{story_id}", headers=headers)
            get_response.raise_for_status()
            get_data = get_response.json()

            if get_data["data"].get("video_url"):
                print(f"Video URL: {get_data["data"]['video_url']}")
                return get_data["data"]["video_url"]
            else:
                print(f"Video not yet ready: {get_data}")
        except requests.exceptions.RequestException as e:
            print(f"Error during request: {e}")
            raise
        except Exception as e:
            print(f"An unexpected error occurred: {e}")
            raise

        time.sleep(POLL_INTERVAL)

    raise TimeoutError("Timeout waiting for video generation")

# Example Usage
if __name__ == "__main__":
    website_url = "https://www.example.com/article"  # Replace with a real URL
    try:
        video_url = create_and_wait_for_video(website_url)
        print(f"Video generated successfully: {video_url}")
    except Exception as e:
        print(f"Video generation failed: {e}")
```
#### Bash
```bash
# cURL example (can be simpler, just show the basic commands)
# Step 1: Create a video request
curl -X POST "https://prod.api.market/api/v1/magicapi/url-to-video/story/url-2-video" \
-H "Content-Type: application/json" \
-H "x-api-market-key: YOUR_API_MARKET_KEY" \
-d '{"idea": "https://www.vimmerse.net"}'

# Response will contain a Story ID like:
# {"data": {"id": "your_story_id", "message": "URL has been submitted"}}

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

# Note: You need to repeatedly poll this endpoint manually until video_url is populated in the response
```

## FAQ

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

A: The video generation time depends on the complexity of the URL and the content to be processed. It typically takes a few minutes, but can take longer for complex websites. The polling mechanism ensures you get the video when it's ready.

**Q: What happens if the API returns an error?**

A: The API will return an appropriate HTTP status code and a JSON response with error details. Refer to the Error Handling section for more information.

**Q: How do I handle rate limits?**

A: If you exceed the rate limit, you will receive a 429 Too Many Requests error. Reduce the frequency of your requests or upgrade your plan to increase your rate limit.

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


Convert any web page URL into an AI-generated video automatically. Ideal for content repurposing and social clips. Try it free on API.market.