{"uid":"cap_VoTsv5_fI0ADrnjD28x5A","slug":"agents-vimmerse-net-vimmerse-get-story-detail-87c27425","name":"Vimmerse Get Story Detail","description":"Retrieves a story by ID. Use this to poll until `status` is `success` and then read `video_url`.\n\n### Example: Get Story (Python)\n\n```python\nimport requests\n\nBASE_URL = \"https://api.vimmerse.net\"\nAPI_KEY = \"YOUR_API_KEY\"\nSTORY_ID = \"your-story-id-here\"\n\nurl = f\"{BASE_URL}/v2/story/{STORY_ID}\"\nheaders = {\"X-Api-Key\": API_KEY}\n\nresponse = requests.get(url, headers=headers, timeout=30)\nresponse.raise_for_status()\nresult = response.json()\nprint(f\"Story ID: {result['id']}, Status: {result['status']}, Progress: {result.get('progress_percentage', 0)}%\")\nif result.get(\"status\") == \"success\" and result.get(\"video_url\"):\n    print(f\"Video URL: {result['video_url']}\")\n```","url":"https://agents.vimmerse.net/v2/story/{story_id}?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","required":["story_id"],"properties":{"story_id":{"type":"string","title":"Story ID","examples":["abc123-def456-ghi789"],"description":"Unique identifier of the story to retrieve"}}},"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":"0.000000","displayCostAsset":"USD","priceDynamic":false,"priceHint":null,"priceStatus":"unknown_unparsed","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":"unknown","summary":"price unknown","primary":{"kind":"unknown","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"unknown","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_AsfAuSmLgpbPr8Wz89GSr","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.000000","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":"Retrieves a story job by ID, returning its current status, progress percentage, and final video URL when complete.","exampleAgentPrompt":"Can you check the status of my Vimmerse story with ID abc123-def456-ghi789 and let me know if the video is ready yet?","exampleUseCases":[{"title":"Polling story until video is ready","prompt":"Keep checking story abc123-def456-ghi789 on Vimmerse every 30 seconds and tell me when the video URL is available."},{"title":"Retrieving completed story video link","prompt":"My Vimmerse story job abc123-def456-ghi789 should be done by now — can you grab the final video URL for me?"},{"title":"Checking story generation progress","prompt":"What percentage complete is my Vimmerse story abc123-def456-ghi789? I want to know how much longer I need to wait."}],"resultDescription":"A JSON object containing the story's ID, title, idea/concept, current status (e.g. 'pending', 'processing', 'success', 'failed'), progress percentage, the final video_url (null until complete), and an array of all_medias with individual media item details including prompts, generated video URLs, resolution, video tool used, and timestamps.","failureModes":["Story ID not found — returns 404 if the ID does not exist or belongs to another account","Story still processing — status will be 'pending' or 'processing' and video_url will be null; agent must poll again","Authentication failure — missing or invalid X-Api-Key header returns 401/403","Story failed — status may be 'failed' with no video_url populated","Network timeout — the polling request itself times out before receiving a response"],"whenToPreferThis":"Use this endpoint after creating a story job (via the Create Story endpoint) to track its asynchronous progress and retrieve the final video URL. This is the canonical polling endpoint for story-level multi-scene video jobs on Vimmerse, as opposed to the Get Media endpoint which tracks individual media objects. Prefer this when you need the aggregated story output (combined video_url) and metadata about all media items in the story.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T00:42:13.143Z","isFirstParty":false,"canonicalSlug":"agents-vimmerse-net-vimmerse-get-story-detail-87c27425"}