{"uid":"cap_D_AZxe6OmwYUuAmUDMAiy","slug":"agents-vimmerse-net-vimmerse-images-to-video-5876507f","name":"Vimmerse Images-to-Video","description":"Generates a story video from an **idea** and a list of **image URLs**. Send **Content-Type: application/json**.\n\nPipeline: narrations/music → animate each image → compose final video. Poll **GET /v2/story/{story_id}** until `status` is `success`.\n\n### Example: Images-to-Video (Python)\n\n```python\nimport requests\n\nBASE_URL = \"https://api.vimmerse.net\"\nAPI_KEY = \"YOUR_API_KEY\"\n\nurl = f\"{BASE_URL}/v2/story/images-2-video\"\nheaders = {\"X-Api-Key\": API_KEY, \"Content-Type\": \"application/json\"}\n\npayload = {\n    \"idea\": \"Cinematic product-only smoothie promo: fresh berries, bananas, oranges on a wooden table, blender mixing, smoothie pouring into glass, 16:9, photorealistic.\",\n    \"image_urls\": [\n        \"https://example.com/image1.jpg\",\n        \"https://example.com/image2.jpg\",\n        \"https://example.com/image3.jpg\",\n    ],\n    \"title\": \"Smoothie Promo\",\n    \"aspect_ratio\": \"16:9\",\n    \"video_tool\": \"Auto\",\n    \"is_transition\": True,\n    \"scene_duration\": 5,\n    \"audio_option\": {\"has_bg_music\": True, \"has_narration\": True, \"native_audio\": False},\n    \"language\": \"English\",\n}\n\nresponse = requests.post(url, headers=headers, json=payload, timeout=60)\nresponse.raise_for_status()\nresult = response.json()\nprint(f\"Story ID: {result['id']}, Scenes: {len(payload['image_urls'])}\")\n```\n\n## audio_option\n\n\nAudio configuration for story generation (JSON object). Used in idea-2-video, url-2-video, images-2-video, and advanced Step 1 (Create Storyboard).\n\n## Audio parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `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 |\n| `has_narration` | boolean | true | Include narration. Ignored when `native_audio` is true |\n| `has_bg_music` | boolean | true | Include background music |\n| `native_audio` | boolean | false | Include native sound effects and lip sync. When true, narration is disabled |\n\n## Usage examples (application/json)\n\n**Background music only:**\n```json\n{\n  \"has_bg_music\": true,\n  \"has_narration\": false,\n  \"native_audio\": false\n}\n```\n\n**Narration with background music:**\n```json\n{\n  \"has_bg_music\": true,\n  \"has_narration\": true,\n  \"native_audio\": false,\n  \"narrator\": \"Rachel\"\n}\n```\n\n**Native audio (sound effects + lip sync):**\n```json\n{\n  \"has_bg_music\": true,\n  \"has_narration\": false,\n  \"native_audio\": true\n}\n```\n\n**No audio:**\n```json\n{\n  \"has_bg_music\": false,\n  \"has_narration\": false,\n  \"native_audio\": false\n}\n```\n\n## Notes\n\n- When `native_audio` is true, `has_narration` is ignored (effectively false).\n- `narrator` is only used when `has_narration` is true and `native_audio` is false.\n- Send `audio_option` as a JSON object in the request body (Content-Type: application/json).","url":"https://agents.vimmerse.net/v2/story/images-2-video?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"Images2VideoRequest","required":["image_urls"],"properties":{"idea":{"type":"string","title":"Idea","default":"Create a stunning video showcasing these images with a compelling narrative","examples":["Animated story of Charlie, cheerful young person with short brown hair, casual clothes in morning, festive outfits later, consistent appearance across all scenes, cinematic lighting, high detail, warm festive colors. Make it in 3D Pixar style."],"description":"Text description of your story concept."},"title":{"type":"string","title":"Story Title","default":"","examples":["My Story Video"]},"language":{"enum":["Arabic","Chinese","English","French","German","Hindi","Japanese","Korean","Spanish","Turkish"],"type":"string","title":"Language","default":"English","examples":["English","Spanish","French","German","Japanese"]},"image_urls":{"type":"array","items":{"type":"string"},"title":"Image URLs","examples":[["https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/zd2f0q.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/nkeh11.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/c4khlw.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/q1kq79.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/vgpk83.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/xe929j.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/ajqmkf.jpg","https://media.vimmerse.net/vimmerse-product/assets/7076a3ed-0869-4ad2-875f-e07b40de9498/uploads/obfa5z.jpg"]],"minItems":1,"description":"Array of publicly accessible image URLs. Required."},"video_tool":{"enum":["Auto","KlingAI","Seedance","Pixverse","VeoFast","Vidu","AutoT1","VeoLite","PVideo"],"type":"string","title":"Video Animation Method","default":"Auto","examples":["Auto","KlingAI","Seedance","Pixverse","VeoFast","Vidu","AutoT1","VeoLite","PVideo"]},"webhook_url":{"type":"string","title":"Webhook URL","default":""},"aspect_ratio":{"enum":["16:9","4:3","1:1","3:4","9:16"],"type":"string","title":"Aspect Ratio","default":"16:9","examples":["16:9","4:3","1:1","3:4","9:16"]},"audio_option":{"anyOf":[{"type":"object","title":"StoryAudioOption","examples":[{"narrator":"AutoV","has_bg_music":true,"native_audio":false,"has_narration":true}],"properties":{"narrator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrator","examples":["AutoV"],"description":"Voice used when has_narration is true. Voices: AutoV, Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill."},"has_bg_music":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Background Music","examples":[true],"description":"When true, generate background music. Omit to keep the default (true)."},"native_audio":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Native Audio","examples":[false],"description":"When true, the video model adds sound and lip sync and narration is not used. Omit to keep the default (false)."},"has_narration":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Narration","examples":[true],"description":"When true, generate spoken narration. Ignored when native_audio is true. Omit to keep the default (true)."}},"description":"Audio for story endpoints. JSON object, not a string. This is not the media audio_option shape.","additionalProperties":true},{"type":"string"},{"type":"null"}],"title":"Audio Configuration","examples":[{"narrator":"AutoV","has_bg_music":true,"native_audio":false,"has_narration":true},{"native_audio":true}],"description":"JSON object for story audio. Not a string, and not the media audio_option shape. Keys: has_bg_music (boolean), has_narration (boolean), native_audio (boolean), narrator (voice name). When native_audio is true, narration is not used. Example: {\"has_bg_music\":true,\"has_narration\":true,\"native_audio\":false,\"narrator\":\"AutoV\"}"},"is_transition":{"type":"boolean","title":"Enable Transitions","default":false,"examples":[true,false]},"scene_duration":{"type":"integer","title":"Scene Duration","default":5,"maximum":30,"minimum":1,"description":"Duration per scene in seconds. The supported values vary based on video tool selected."}},"description":"Request body for POST /story/images-2-video. Accepts JSON for easier client usage."},"responseSchema":{"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":""},"description":{"type":"string","title":"Description","default":""},"media_items":{"type":"array","items":{},"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":{"type":"string","title":"Webhook URL is called when status of the media has been updated.","default":""},"audio_option":{"anyOf":[{"type":"object","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.\"}"},"used_credits":{"type":"integer","title":"Used Credits","default":0},"payment_status":{"type":"string","title":"Payment Status","default":""},"primary_user_id":{"type":"string","title":"Primary User ID","default":"","description":"Utilize the `primary_user_id` parameter to determine the owner of the Media. If the `primary_user_id` value is not included in the request object, it will default to your customer_id."},"processing_status":{"type":"string","title":"Processing Status","default":"new"}},"description":"Customer-facing media response model for non-product customers.\nThis intentionally excludes internal/advanced fields from MediaV3."},"title":"All Medias","description":"Generated media records for this story. Each record's media_items array uses {type, url, position}."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"storyboard":{"anyOf":[{"type":"object","title":"StoryboardResponse","properties":{"music":{"anyOf":[{"type":"object","title":"StoryboardMusicResponse","properties":{"lyrics":{"type":"string","title":"Lyrics","default":""},"music_url":{"type":"string","title":"Music URL","default":"","description":"Public https URL of a music file."},"description":{"type":"string","title":"Description","default":"","description":"Music prompt: genre, tempo, instruments, mood."}},"description":"Storyboard music (description, lyrics, music_url).","additionalProperties":true},{"type":"null"}]},"scenes":{"type":"array","items":{"type":"object","title":"StoryboardSceneResponse","properties":{"name":{"type":"string","title":"Name","default":""},"narrator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrator","description":"Spoken line for this scene."},"image_url":{"type":"string","title":"Image URL","default":"","description":"Public https URL of the scene still. Empty until the scene image exists."},"narration_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narration URL","description":"Public https URL of a narration file for this scene."},"image_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Description"},"video_description":{"type":"string","title":"Video Description","default":"","description":"Motion prompt for this scene."}},"description":"Storyboard scene with video/image descriptions and narrator text.","additionalProperties":true},"title":"Scenes","description":"List of scenes"},"objects":{"type":"array","items":{"type":"object","title":"StoryElementItemResponse","properties":{"name":{"type":"string","title":"Name","default":"","description":"Short distinct name used in scene text."},"image_url":{"type":"string","title":"Image URL","default":"","description":"Public https URL of an existing picture. Empty when the picture is generated later."},"description":{"type":"string","title":"Description","default":"","description":"Visual description. The picture URL goes in image_url."}},"description":"Single character, environment, or object in story elements.","additionalProperties":true},"title":"Objects","description":"List of objects"},"characters":{"type":"array","items":{"type":"object","title":"StoryElementItemResponse","properties":{"name":{"type":"string","title":"Name","default":"","description":"Short distinct name used in scene text."},"image_url":{"type":"string","title":"Image URL","default":"","description":"Public https URL of an existing picture. Empty when the picture is generated later."},"description":{"type":"string","title":"Description","default":"","description":"Visual description. The picture URL goes in image_url."}},"description":"Single character, environment, or object in story elements.","additionalProperties":true},"title":"Characters","description":"List of characters"},"environments":{"type":"array","items":{"type":"object","title":"StoryElementItemResponse","properties":{"name":{"type":"string","title":"Name","default":"","description":"Short distinct name used in scene text."},"image_url":{"type":"string","title":"Image URL","default":"","description":"Public https URL of an existing picture. Empty when the picture is generated later."},"description":{"type":"string","title":"Description","default":"","description":"Visual description. The picture URL goes in image_url."}},"description":"Single character, environment, or object in story elements.","additionalProperties":true},"title":"Environments","description":"List of environments"}},"description":"Full storyboard (scenes, characters, music, environments, objects).","additionalProperties":true},{"type":"null"}],"title":"Storyboard","description":"Storyboard"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook URL","description":"Webhook URL is called after batch or story is finished"},"aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspect Ratio"},"used_credits":{"type":"integer","title":"Used Credits","default":0},"is_transition":{"type":"boolean","title":"Enable Transitions","default":false},"progress_percentage":{"type":"integer","title":"Progress Percentage","default":0}},"description":"Customer Story Response"},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"1.5","displayCostAsset":"USDC","priceDynamic":true,"priceHint":null,"priceStatus":"priced","priceSource":"registry","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.5/call (dynamic — varies by input)","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_YV-R6av_ZI9Jo7eJ5MpiX","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"unknown","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.vimmerse.net","brandSlug":"agents-vimmerse-net-x402","brandBaseUrl":"https://agents.vimmerse.net","brandDocsUrl":null,"whatItDoes":"Generates an animated story video with narration and background music from a text idea and a list of image URLs.","exampleAgentPrompt":"Take these three product photos — https://example.com/img1.jpg, https://example.com/img2.jpg, https://example.com/img3.jpg — and turn them into a cinematic 16:9 promo video for my smoothie brand called 'Fresh Blend', with background music, an English voiceover narration, and 5-second scenes that flow together with transitions.","exampleUseCases":[{"title":"Product launch promo video","prompt":"I have five product images for our new sneaker launch. Can you make a cinematic 16:9 story video called 'Stride Launch' from these URLs — https://example.com/s1.jpg, https://example.com/s2.jpg, https://example.com/s3.jpg, https://example.com/s4.jpg, https://example.com/s5.jpg — with the idea: bold urban sneaker reveal, high energy streets, close-ups of the shoe design? Include background music and English narration, 5 seconds per scene."},{"title":"Real estate listing walkthrough","prompt":"Turn these four property photos into a smooth story video for our listing called 'Sunset Villa'. The images are https://example.com/r1.jpg, https://example.com/r2.jpg, https://example.com/r3.jpg, https://example.com/r4.jpg. Concept: luxurious modern home with ocean views, warm afternoon light, inviting interiors. Use a 16:9 aspect ratio, English narration, background music, and 6-second scenes with transitions."},{"title":"Personal photo memory reel","prompt":"I want to make a 9:16 vertical story video as a birthday memory reel from these photos: https://example.com/p1.jpg, https://example.com/p2.jpg, https://example.com/p3.jpg, https://example.com/p4.jpg, https://example.com/p5.jpg, https://example.com/p6.jpg. Title it 'Emma's 30th', and use the idea: joyful journey through Emma's life — childhood adventures, family moments, and celebrations. Add background music, English narration, 5-second scenes."}],"resultDescription":"Returns a story object containing a story ID, status field, and eventually (after polling GET /v2/story/{story_id}) a video_url pointing to the fully composed video, plus an all_medias array with per-scene animated clip URLs, prompts, and metadata such as resolution and video tool used.","failureModes":["Invalid or inaccessible image URLs return an error or produce blank scenes","Missing required image_urls field returns a validation error","Unsupported aspect ratio or video_tool enum value causes request rejection","Long queues or downstream model failures may cause the story to remain in a non-success status indefinitely","Insufficient credits result in a payment or authorization error","Very large numbers of images or long scene durations may increase processing time significantly"],"whenToPreferThis":"Choose this endpoint when you already have a set of existing image URLs and want to produce a complete multi-scene story video with AI-generated narration, background music, and animated motion applied to each image. It is ideal for product marketing reels, real-estate walkthroughs, personal photo slideshows, and social media content creation where the visual assets are already available and only need to be animated and composed into a narrative video.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T00:42:16.938Z","isFirstParty":false,"canonicalSlug":"agents-vimmerse-net-vimmerse-images-to-video-5876507f"}