{"uid":"cap_Bwc8mNINVxmpVv4cBIBI7","slug":"agents-vimmerse-net-vimmerse-create-media-video-generation-79f63fc2","name":"Vimmerse Create Media (Video Generation)","description":"Creates a new media object and starts asynchronous video generation.\n\nSend 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`.\n\nThe API validates the request, checks credits, creates the media record, queues the generation job, and returns immediately with a media object for tracking progress.\n\n## Examples\n\n### Example Response (200)\n\nResponse body uses the same fields as the example below.\n\n```json\n{\n  \"id\": \"abc123-def456-ghi789\",\n  \"title\": \"Example Media\",\n  \"description\": \"Media description\",\n  \"customer_id\": \"customer123\",\n  \"primary_user_id\": \"user-abc-123\",\n  \"media_items\": null,\n  \"duration_time\": \"5\",\n  \"processing_status\": \"new\",\n  \"pose_preset\": {\n    \"motion_type\": \"Auto\",\n    \"prompt\": \"A cinematic shot over mountains at sunrise\",\n    \"quantity\": 1,\n    \"motion_length\": 5,\n    \"loop\": 1\n  },\n  \"submit_params\": {\"native_audio\": true, \"file_size\": \"\", \"scale_factor\": \"1\"},\n  \"result\": [],\n  \"webhook_url\": \"\",\n  \"created_at\": \"2025-04-01T18:57:37.355064+00:00\",\n  \"updated_at\": \"2025-04-01T18:57:55.502020+00:00\",\n  \"version\": \"3\"\n}\n```\n\n### Example 1: Create Media (Python)\n\nCopy and run this as-is, then replace only `YOUR_API_KEY`.\n\n```python\nimport requests\n\nBASE_URL = \"https://api.vimmerse.net\"\nAPI_KEY = \"YOUR_API_KEY\"\n\nurl = f\"{BASE_URL}/v2/media\"\nheaders = {\n    \"X-Api-Key\": API_KEY,\n    \"Content-Type\": \"application/json\",\n}\n\npayload = {\n    \"title\": \"Product Launch Clip\",\n    \"description\": \"Short cinematic intro for a new product\",\n    \"prompt\": \"Smooth camera move from the product photo to the lifestyle photo\",\n    \"media_items\": [\n        {\n            \"type\": \"image\",\n            \"url\": \"https://example.com/watch-front.png\",\n            \"position\": \"First\"\n        },\n        {\n            \"type\": \"image\",\n            \"url\": \"https://example.com/watch-lifestyle.png\",\n            \"position\": \"Last\"\n        }\n    ],\n    \"video_tool\": \"Auto\",\n    \"duration\": 5,\n    \"quantity\": 1,\n    \"loop\": 1,\n    \"aspect_ratio\": \"16:9\",\n    \"audio_option\": {\n        \"narrator\": \"Sarah\",\n        \"narration\": \"Introducing the next generation of smart performance.\"\n    }\n}\n\nresponse = requests.post(url, headers=headers, json=payload, timeout=60)\nresponse.raise_for_status()\nresult = response.json()\nprint(result)\n```\n\n### Example 2: Full Flow (Create -> Poll -> Fetch -> Download)\n\nCopy and run this as-is, then replace only `YOUR_API_KEY`.\n\n```python\nimport requests\nimport time\n\nBASE_URL = \"https://api.vimmerse.net\"\nAPI_KEY = \"YOUR_API_KEY\"\nHEADERS = {\n    \"X-Api-Key\": API_KEY,\n    \"Content-Type\": \"application/json\",\n}\n\n# 1) Create media\ncreate_url = f\"{BASE_URL}/v2/media\"\ncreate_payload = {\n    \"title\": \"AI Demo Video\",\n    \"prompt\": \"A cinematic drone shot over snow mountains at sunrise with dramatic clouds\",\n    \"video_tool\": \"Auto\",\n    \"duration\": 5,\n    \"quantity\": 1,\n    \"loop\": 1,\n    \"aspect_ratio\": \"16:9\"\n}\n\ncreate_res = requests.post(create_url, headers=HEADERS, json=create_payload, timeout=60)\ncreate_res.raise_for_status()\ncreate_data = create_res.json()\nmedia_id = create_data[\"id\"]\nprint(f\"Created media: {media_id}\")\n\n# 2) Poll until processing completes (GET media returns the full media object)\nfor attempt in range(120):\n    detail_res = requests.get(f\"{BASE_URL}/v2/media/{media_id}\", headers=HEADERS, timeout=30)\n    detail_res.raise_for_status()\n    status_data = detail_res.json()\n    status = status_data.get(\"processing_status\", \"\")\n    print(f\"Attempt {attempt + 1}: status={status}\")\n\n    if status == \"success\":\n        break\n    if status == \"failed\":\n        raise RuntimeError(f\"Media generation ended with status: {status}\")\n    time.sleep(10)\nelse:\n    raise TimeoutError(\"Media generation is taking longer than expected.\")\n\n# 3) Use download URL(s) from the response (result can contain several files)\ndetail_data = status_data\nvideo_urls = detail_data.get(\"result\", [])\nfor url in video_urls:\n    print(f\"Video URL: {url}\")\n# Use these URLs to download or display the generated file(s).\n```\n\n## media_items\n\n\nHow to pass images or videos. `media_items` is a **JSON array of objects**, not a string and not a file upload.\n\nEach object has three fields:\n\n| Field | Values | Meaning |\n|-------|--------|---------|\n| `type` | `\"image\"` or `\"video\"` | `\"image\"` is a still (png, jpg, webp). `\"video\"` is an mp4; a frame is taken from it. |\n| `url` | public https URL | The server downloads this URL with no cookies and no Authorization header. |\n| `position` | `\"First\"` or `\"Last\"` | `\"First\"` is the start frame. `\"Last\"` is the end frame. |\n\nOne picture (image-to-video):\n\n```json\n\"media_items\": [\n  {\"type\": \"image\", \"url\": \"https://example.com/start.png\", \"position\": \"First\"}\n]\n```\n\nStart frame and end frame:\n\n```json\n\"media_items\": [\n  {\"type\": \"image\", \"url\": \"https://example.com/start.png\", \"position\": \"First\"},\n  {\"type\": \"image\", \"url\": \"https://example.com/end.png\", \"position\": \"Last\"}\n]\n```\n\nDo not put audio in `media_items`. Audio items are ignored. Use `audio_option` for speech and music.\n\n\n## audio_option\n\n\nOptional 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`.\n\n## Audio parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `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 |\n| `narration` | string | null | Text to convert to speech with the chosen narrator |\n| `narration_url` | string | null | URL to pre-recorded narration (MP3/WAV). If set, `narrator` and `narration` are ignored |\n| `bg_music_prompt` | string | null | Description for AI-generated background music |\n| `bg_music_url` | string | null | URL to an external background music track |\n| `native_audio` | boolean | false | Enable native audio (e.g. sound effects, lip sync) for compatible tools |\n\n## Examples (application/json)\n\n**Narration + background music:**\n```json\n{\n  \"narrator\": \"AutoV\",\n  \"narration\": \"Introducing the next generation of smart performance.\",\n  \"bg_music_prompt\": \"Modern, cinematic background with subtle electronic elements\"\n}\n```\n\n**Pre-recorded narration only:**\n```json\n{\n  \"narration_url\": \"https://example.com/voiceover.mp3\"\n}\n```\n\n**Background music only:**\n```json\n{\n  \"bg_music_url\": \"https://example.com/background.mp3\"\n}\n```\n\n## Notes\n\n- Audio URLs must be publicly accessible (no auth). Supported formats: MP3, WAV.\n- When both `narration_url` and `narration` are provided, `narration_url` wins.\n- Audio inside `media_items` is ignored. `audio_option` is the only audio input.","url":"https://agents.vimmerse.net/v2/media?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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"],"description":"Use \"image\" for a still frame (png, jpg, or webp) or \"video\" for an mp4. \"First\" / \"Last\" go in position. Audio items are ignored by generation; put speech and music in audio_option."},"position":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Position","examples":["First","Last"],"description":"\"First\" is the start frame. \"Last\" is the end frame. One picture: one object with position First. A start-to-end transition: two objects, one First and one Last."}},"description":"One input in media_items. Fields are optional so older payloads still validate.","additionalProperties":true}},{"type":"null"}],"title":"Media Items","examples":[[{"url":"https://example.com/start.png","type":"image","position":"First"},{"url":"https://example.com/end.png","type":"image","position":"Last"}]],"description":"Array of image or video inputs. Send a JSON array of objects, not a string. Each object is {\"type\":\"image\"|\"video\",\"url\":\"https://...\",\"position\":\"First\"|\"Last\"}. \"First\" is the start frame. \"Last\" is the end frame. One picture: [{\"type\":\"image\",\"url\":\"https://example.com/start.png\",\"position\":\"First\"}]. Start and end: add a second object with position Last. url must be a public https URL. Do not upload a file here and do not put audio in this array. Audio belongs in audio_option."},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook URL","description":"Callback URL to receive status updates."},"aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspect Ratio","description":"Optional output aspect ratio."},"audio_option":{"anyOf":[{"type":"object","title":"MediaAudioOption","examples":[{"narrator":"Sarah","narration":"Introducing the next generation of smart performance.","bg_music_prompt":"Modern cinematic background with soft electronic pulses"}],"properties":{"narrator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrator","examples":["Sarah"],"description":"Voice for narration text. Voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill. Ignored when narration_url is set."},"narration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narration","examples":["Introducing the next generation of smart performance."],"description":"Spoken script. The narrator voice reads this text. Ignored when narration_url is set."},"bg_music_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background Music URL","examples":["https://example.com/background.mp3"],"description":"Public https URL of a music file (mp3 or wav). When set, bg_music_prompt is ignored."},"native_audio":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Native Audio","examples":[false],"description":"When true, the video model adds its own sound and lip sync on tools that support it."},"narration_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narration URL","examples":["https://example.com/voiceover.mp3"],"description":"Public https URL of a pre-recorded voice track (mp3 or wav). When set, narrator and narration are ignored."},"bg_music_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background Music Prompt","examples":["Modern cinematic background with soft electronic pulses"],"description":"Text prompt for generated background music. Ignored when bg_music_url is set."}},"description":"Audio for POST /v2/media. JSON object, not a string.","additionalProperties":true},{"type":"null"}],"title":"Audio Option","examples":[{"narrator":"Sarah","narration":"Introducing the next generation of smart performance.","bg_music_prompt":"Modern cinematic background with soft electronic pulses"}],"description":"JSON object for speech and music. Not a string. Keys: narrator (voice name), narration (script), narration_url (public mp3/wav; wins over narrator and narration), bg_music_prompt (music description), bg_music_url (public mp3/wav; wins over bg_music_prompt), native_audio (boolean). Example: {\"narrator\":\"Sarah\",\"narration\":\"Introducing the next generation of smart performance.\"}"},"pipeline_mode":{"enum":["Advanced","Quick"],"type":"string","title":"Pipeline Mode","default":"Advanced","examples":["Advanced","Quick"],"description":"Advanced: preprocess input images (fix orientation, rescale, expand to aspect ratio) and run video post-processing (e.g. looping when loop > 1). Quick: use images as-is and skip post-processing; faster, less processing."}}},"responseSchema":{},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"1.2","displayCostAsset":"USD","priceDynamic":true,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"dynamic","summary":"$1.2/call (dynamic — varies by input)","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":"1.2","per":"call","confidence":"exact"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":"1.2","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_EMTL5wCz4Jok943R2KULN","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"1.2","costPer":"request","priority":0,"asset":"usd","unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.vimmerse.net","brandSlug":"agents-vimmerse-net-x402","brandBaseUrl":"https://agents.vimmerse.net","brandDocsUrl":null,"whatItDoes":"Submits a text-prompt and optional media references to asynchronously generate a video clip, returning a trackable media job object.","exampleAgentPrompt":"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.","exampleUseCases":[{"title":"Animate product image into video ad","prompt":"Take this product image at https://example.com/product.png and generate a 5-second video ad using KlingPro with a prompt like 'the product rotates slowly on a clean white surface with soft studio lighting' — I want just one output in square format."},{"title":"Text-to-video social content creation","prompt":"Generate a 10-second video from this prompt: 'A neon-lit cyberpunk city at night with rain reflecting on wet streets', using Seedance, in 9:16 aspect ratio — I need 2 variations so I can pick the best one."},{"title":"Looping background video generation","prompt":"Create a looping ambient video using the prompt 'calm ocean waves slowly rolling onto a sandy beach at golden hour', make it 8 seconds long with 3 loops using the Wan model for my website background."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-30T22:53:37.548Z","isFirstParty":false,"canonicalSlug":"agents-vimmerse-net-vimmerse-create-media-video-generation-79f63fc2"}