# Vimmerse Idea-to-Video

> Vimmerse Idea-to-Video is a paid API for AI agents from agents.vimmerse.net, paid per call via MPP, $4.5/call (dynamic — varies by input), status unknown (last checked 2026-10-31).

Converts a plain-text idea into a fully produced multi-scene video with narration and background music in a single API call

## Facts

- Endpoint: POST https://agents.vimmerse.net/v2/story/idea-2-video?utm_source=zero.xyz
- Price: $4.5/call (dynamic — varies by input)
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-31
- Activations on Zero: 0
- Provider: agents.vimmerse.net
- Website: https://agents.vimmerse.net
- Canonical page: https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-idea-to-video-934a0a00
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_H8ET776HciNcXQTfqAeNb

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agents-vimmerse-net-vimmerse-idea-to-video-934a0a00 -d '<json body>'
```

Example prompt: Can you create a 4-scene vertical (9:16) promotional video from this idea: 'Three friends discover a hidden waterfall in a jungle and celebrate with a picnic'? Use Cinematic Narrative style, 5 seconds per scene, with background music and English narration.

## When to prefer this

Choose this endpoint when you want a fully automated, hands-off pipeline that takes a single text idea all the way to a finished composed video with audio, narration, and multiple scenes — without needing to manually manage storyboarding, scene generation, or audio assembly. Prefer it over Create Media when you need a multi-scene narrative video rather than a single clip, and over manual workflows when speed and automation matter more than fine-grained per-scene control.

## Known failure modes

- Insufficient credits — 402 payment required before generation begins
- Invalid or missing 'idea' field — 422 validation error
- Unsupported style or tool enum value — 422 validation error
- Pipeline timeout on long or complex ideas — status may stay 'processing' indefinitely
- Video tool unavailable — falls back to Auto or returns error
- Webhook delivery failure if webhook_url is unreachable

## How this service works

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)

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

`elements` is a **JSON object**, not a string and not a list of `{type, url, position}` (that shape is `media_items` on the media API).

Each key is a list of objects. To pass an existing picture, set `image_url` to a public https URL. Leave `image_url` as `""` when the picture should be generated later.

| Key | Type | Description |
|-----|------|-------------|
| `characters` | array of objects | Optional. Each item has `name`, `description`, and `image_url`. |
| `environments` | array of objects | Optional. Each item has `name`, `description`, and `image_url`. |
| `objects` | array of objects | Optional. Each item has `name`, `description`, and `image_url`. |

**Example (partial):**

```json
{
  "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": "https://example.com/whiskers.png"
      },
      {
        "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:**
```json
{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": false
}
```

**Narration with background music:**
```json
{
  "has_bg_music": true,
  "has_narration": true,
  "native_audio": false,
  "narrator": "Rachel"
}
```

**Native audio (sound effects + lip sync):**
```json
{
  "has_bg_music": true,
  "has_narration": false,
  "native_audio": true
}
```

**No audio:**
```json
{
  "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).

## Output

Returns a story object with an ID and initial status. The agent must poll GET /v2/story/{story_id} until status is 'success', then read video_url for the final composed video. The response also includes all_medias with per-scene video URLs, prompts, resolution, and tool used.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "Idea2VideoRequest",
 "required": [
  "idea"
 ],
 "properties": {
  "idea": {
   "type": "string",
   "title": "Idea",
   "examples": [
    "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."
   ],
   "description": "Detailed text description of your story concept."
  },
  "style": {
   "enum": [
    "AutoS",
    "Cinematic Narrative",
    "Neo-Nostalgia / Film Grain",
    "Photorealistic",
    "Authentic Minimal",
    "Claymation",
    "3D Pixar",
    "Cartoon Comic",
    "2D Anime",
    "Oil Painting",
    "Cyberpunk Futueristic Aesthetic"
   ],
   "type": "string",
   "title": "Story Style",
   "default": "AutoS",
   "examples": [
    "AutoS",
    "Cinematic Narrative",
    "3D Pixar",
    "Photorealistic"
   ],
   "description": "Visual storytelling style. 'AutoS' lets AI choose automatically. Other options enforce a specific style direction."
  },
  "title": {
   "type": "string",
   "title": "Story Title",
   "default": "",
   "examples": [
    "My Story Video"
   ]
  },
  "elements": {
   "anyOf": [
    {
     "type": "object",
     "title": "StoryElementsInput",
     "examples": [
      {
       "objects": [
        {
         "name": "Logo",
         "image_url": "https://example.com/logo.png",
         "description": "Brand logo, flat, on a transparent background."
        }
       
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "CustomerStoryResponse",
 "properties": {
  "id": {
   "type": "string",
   "title": "ID",
   "default": ""
  },
  "idea": {
   "type": "string",
   "title": "Idea",
   "default": "",
   "description": "Idea of the story"
  },
  "title": {
   "type": "string",
   "title": "Title",
   "default": ""
  },
  "status": {
   "type": "string",
   "title": "Status",
   "default": ""
  },
  "video_url": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "title": "Video URL"
  },
  "all_medias": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "CustomerMediaResponse",
    "properties": {
     "id": {
      "type": "string",
      "title": "Id",
      "default": ""
     },
     "title": {
      "type": "string",
      "title": "Title",
      "default": ""
     },
     "prompt": {
      "type": "string",
      "title": "Prompt",
      "default": ""
     },
     "result": {
      "type": "array",
      "items": {},
      "title": "Generated Video URLs",
      "default": []
     },
     "version": {
      "type": "string",
      "title": "Version",
      "default": "3"
     },
     "quantity": {
      "type": "integer",
      "title": "Quantity",
      "default": 1,
      "maximum": 4,
      "minimum": 1,
      "description": "Number of generated outputs."
     },
     "created_at": {
      "type": "string",
      "title": "Created At",
      "default": ""
     },
     "resolution": {
      "type": "array",
      "items": {},
      "title": "Resolution",
      "default": []
     },
     "updated_at": {
      "type": "string",
      "title": "Updated At",
      "default": ""
     },
     "video_tool": {
      "enum": [
       "Auto",
       "AutoT3",
       "AutoT1",
       "HappyHorse",
       "Grok",
       "KlingAI",
       "KlingT3",
       "KlingPro",
       "GoogleOmni",
       "VeoLite",
       "VeoFast",
       "Veo",
       "RunwayML",
       "MinimaxHailuo",
       "MinimaxTurbo",
       "Seedance",
       "SeedanceFast",
       "SeedanceT6",
       "Pixverse",
       "PixverseT3",
       "Hunyuan",
       "Vidu",
       "PVideo",
       "StaticMotion",
       "Wan",
       "TryOnVideo"
      ],
      "type": "string",
      "title": "Video Tool",
      "default": "Auto",
      "description": "Motion/generation tool option (same as create media)."
     },
     "customer_id": {
      "type": "string",
      "title": "Customer ID",
      "default": ""
     },
     "descr
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-idea-to-video-934a0a00/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.vimmerse.net](https://www.zero.xyz/host/agents.vimmerse.net/llms.txt)