# Vimmerse Create Media (Video Generation)

> Vimmerse Create Media (Video Generation) is a paid API for AI agents from agents.vimmerse.net, paid per call via MPP, $1.2/call (dynamic — varies by input), status unknown (last checked 2026-10-30).

Submits a text-prompt and optional media references to asynchronously generate a video clip, returning a trackable media job object.

## Facts

- Endpoint: POST https://agents.vimmerse.net/v2/media?utm_source=zero.xyz
- Price: $1.2/call (dynamic — varies by input)
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-30
- Activations on Zero: 0
- Provider: agents.vimmerse.net
- Website: https://agents.vimmerse.net
- Canonical page: https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-create-media-video-generation-79f63fc2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Bwc8mNINVxmpVv4cBIBI7

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-create-media-video-generation-79f63fc2 -d '<json body>'
```

Example prompt: Generate a 5-second cinematic video of a drone shot over a mountain range at sunrise using the Veo model — use Auto aspect ratio and loop it once.

## When to prefer this

Choose this endpoint when you need to generate a brand-new video from a text prompt or reference images/videos using state-of-the-art AI video models (Veo, KlingAI, Runway, Seedance, etc.). It is the primary creation surface on Vimmerse. Prefer the Estimate Credits endpoint first if you want to check cost before committing. Use Video-to-Video instead if you are modifying an existing video clip rather than generating fresh content.

## Known failure modes

- Insufficient credits — request fails with 402 if the account lacks enough credits for the selected tool/duration/quantity
- Invalid video_tool enum value — returns 422 validation error
- media_items URL not publicly accessible — server cannot fetch the file and returns an error
- Duration exceeds maximum (30s) or is below minimum (1s) — 422 validation error
- Quantity exceeds maximum (4) — 422 validation error
- Invalid aspect_ratio or unsupported combination with selected video_tool — may return 422 or fall back silently

## How this service works

Creates a new media object and starts asynchronous video generation.

Send a request with **Content-Type: application/json**. The body may include creative intent (`prompt`), optional media references (`media_items`), and generation options such as `video_tool`, `duration`, and `aspect_ratio`.

The API validates the request, checks credits, creates the media record, queues the generation job, and returns immediately with a media object for tracking progress.

## Examples

### Example Response (200)

Response body uses the same fields as the example below.

```json
{
  "id": "abc123-def456-ghi789",
  "title": "Example Media",
  "description": "Media description",
  "customer_id": "customer123",
  "primary_user_id": "user-abc-123",
  "media_items": null,
  "duration_time": "5",
  "processing_status": "new",
  "pose_preset": {
    "motion_type": "Auto",
    "prompt": "A cinematic shot over mountains at sunrise",
    "quantity": 1,
    "motion_length": 5,
    "loop": 1
  },
  "submit_params": {"native_audio": true, "file_size": "", "scale_factor": "1"},
  "result": [],
  "webhook_url": "",
  "created_at": "2025-04-01T18:57:37.355064+00:00",
  "updated_at": "2025-04-01T18:57:55.502020+00:00",
  "version": "3"
}
```

### Example 1: Create Media (Python)

Copy and run this as-is, then replace only `YOUR_API_KEY`.

```python
import requests

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"

url = f"{BASE_URL}/v2/media"
headers = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "title": "Product Launch Clip",
    "description": "Short cinematic intro for a new product",
    "prompt": "Smooth camera move from the product photo to the lifestyle photo",
    "media_items": [
        {
            "type": "image",
            "url": "https://example.com/watch-front.png",
            "position": "First"
        },
        {
            "type": "image",
            "url": "https://example.com/watch-lifestyle.png",
            "position": "Last"
        }
    ],
    "video_tool": "Auto",
    "duration": 5,
    "quantity": 1,
    "loop": 1,
    "aspect_ratio": "16:9",
    "audio_option": {
        "narrator": "Sarah",
        "narration": "Introducing the next generation of smart performance."
    }
}

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
result = response.json()
print(result)
```

### Example 2: Full Flow (Create -> Poll -> Fetch -> Download)

Copy and run this as-is, then replace only `YOUR_API_KEY`.

```python
import requests
import time

BASE_URL = "https://api.vimmerse.net"
API_KEY = "YOUR_API_KEY"
HEADERS = {
    "X-Api-Key": API_KEY,
    "Content-Type": "application/json",
}

# 1) Create media
create_url = f"{BASE_URL}/v2/media"
create_payload = {
    "title": "AI Demo Video",
    "prompt": "A cinematic drone shot over snow mountains at sunrise with dramatic clouds",
    "video_tool": "Auto",
    "duration": 5,
    "quantity": 1,
    "loop": 1,
    "aspect_ratio": "16:9"
}

create_res = requests.post(create_url, headers=HEADERS, json=create_payload, timeout=60)
create_res.raise_for_status()
create_data = create_res.json()
media_id = create_data["id"]
print(f"Created media: {media_id}")

# 2) Poll until processing completes (GET media returns the full media object)
for attempt in range(120):
    detail_res = requests.get(f"{BASE_URL}/v2/media/{media_id}", headers=HEADERS, timeout=30)
    detail_res.raise_for_status()
    status_data = detail_res.json()
    status = status_data.get("processing_status", "")
    print(f"Attempt {attempt + 1}: status={status}")

    if status == "success":
        break
    if status == "failed":
        raise RuntimeError(f"Media generation ended with status: {status}")
    time.sleep(10)
else:
    raise TimeoutError("Media generation is taking longer than expected.")

# 3) Use download URL(s) from the response (result can contain several files)
detail_data = status_data
video_urls = detail_data.get("result", [])
for url in video_urls:
    print(f"Video URL: {url}")
# Use these URLs to download or display the generated file(s).
```

## media_items


How to pass images or videos. `media_items` is a **JSON array of objects**, not a string and not a file upload.

Each object has three fields:

| Field | Values | Meaning |
|-------|--------|---------|
| `type` | `"image"` or `"video"` | `"image"` is a still (png, jpg, webp). `"video"` is an mp4; a frame is taken from it. |
| `url` | public https URL | The server downloads this URL with no cookies and no Authorization header. |
| `position` | `"First"` or `"Last"` | `"First"` is the start frame. `"Last"` is the end frame. |

One picture (image-to-video):

```json
"media_items": [
  {"type": "image", "url": "https://example.com/start.png", "position": "First"}
]
```

Start frame and end frame:

```json
"media_items": [
  {"type": "image", "url": "https://example.com/start.png", "position": "First"},
  {"type": "image", "url": "https://example.com/end.png", "position": "Last"}
]
```

Do not put audio in `media_items`. Audio items are ignored. Use `audio_option` for speech and music.


## audio_option


Optional audio configuration object (JSON). This is a JSON object, not a string. Pass speech and music here. Do not put audio files in `media_items`.

## Audio parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `narrator` | string | AutoV | Voice for text-to-speech. **Available voices**: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill |
| `narration` | string | null | Text to convert to speech with the chosen narrator |
| `narration_url` | string | null | URL to pre-recorded narration (MP3/WAV). If set, `narrator` and `narration` are ignored |
| `bg_music_prompt` | string | null | Description for AI-generated background music |
| `bg_music_url` | string | null | URL to an external background music track |
| `native_audio` | boolean | false | Enable native audio (e.g. sound effects, lip sync) for compatible tools |

## Examples (application/json)

**Narration + background music:**
```json
{
  "narrator": "AutoV",
  "narration": "Introducing the next generation of smart performance.",
  "bg_music_prompt": "Modern, cinematic background with subtle electronic elements"
}
```

**Pre-recorded narration only:**
```json
{
  "narration_url": "https://example.com/voiceover.mp3"
}
```

**Background music only:**
```json
{
  "bg_music_url": "https://example.com/background.mp3"
}
```

## Notes

- Audio URLs must be publicly accessible (no auth). Supported formats: MP3, WAV.
- When both `narration_url` and `narration` are provided, `narration_url` wins.
- Audio inside `media_items` is ignored. `audio_option` is the only audio input.

## Output

Returns a media object immediately with a unique job ID, processing_status (initially 'new'), pose_preset config, duration, and timestamps. The actual video is generated asynchronously and must be polled by ID until completion.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "CreateMediaV2Request",
 "properties": {
  "loop": {
   "type": "integer",
   "title": "Loop",
   "default": 1,
   "maximum": 6,
   "minimum": 1,
   "description": "Loop count for generation."
  },
  "title": {
   "type": "string",
   "title": "Title",
   "default": "",
   "description": "Media title."
  },
  "prompt": {
   "type": "string",
   "title": "Prompt",
   "default": "",
   "description": "Text prompt used for generation."
  },
  "duration": {
   "type": "integer",
   "title": "Scene Duration",
   "default": 5,
   "maximum": 30,
   "minimum": 1,
   "description": "Scene duration in seconds."
  },
  "quantity": {
   "type": "integer",
   "title": "Quantity",
   "default": 1,
   "maximum": 4,
   "minimum": 1,
   "description": "Number of generated outputs."
  },
  "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."
  },
  "description": {
   "type": "string",
   "title": "Description",
   "default": "",
   "description": "Media description."
  },
  "media_items": {
   "anyOf": [
    {
     "type": "array",
     "items": {
      "type": "object",
      "title": "MediaItem",
      "examples": [
       {
        "url": "https://example.com/start.png",
        "type": "image",
        "position": "First"
       }
      ],
      "properties": {
       "url": {
        "anyOf": [
         {
          "type": "string"
         },
         {
          "type": "null"
         }
        ],
        "title": "URL",
        "examples": [
         "https://example.com/start.png"
        ],
        "description": "Public https URL of the file. The server downloads it with no cookies and no Authorization header. Do not send a local path, a data URI, or a multipart file on this field."
       },
       "type": {
        "anyOf": [
         {
          "type": "string"
         },
         {
          "type": "null"
         }
        ],
        "title": "Type",
        "examples": [
         "image",
         "video"
        ],
    
… (truncated)
```

## Response schema (JSON Schema)

```json
{}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-vimmerse-net-vimmerse-create-media-video-generation-79f63fc2/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)