[{"data":1,"prerenderedAt":512},["ShallowReactive",2],{"guide-\u002Fguides\u002Fmedia-understanding":3,"developer-code-1crrd":510,"developer-code-1co8rwm":511},{"id":4,"title":5,"body":6,"description":501,"extension":502,"meta":503,"navigation":504,"path":506,"seo":507,"stem":508,"__hash__":509},"guides\u002Fguides\u002Fmedia-understanding.md","Structured Media Understanding API",{"type":7,"value":8,"toc":494},"minimark",[9,18,23,83,112,116,124,343,347,358,405,425,429,449,456,459,463,490],[10,11,12,13,17],"p",{},"Use ",[14,15,16],"code",{},"POST \u002Fapi\u002Fv1\u002Fmedia\u002Funderstand"," to extract structured data from media, such as a subject label, scene description, or fields for your application. Supply a prompt, media inputs, and your output JSON Schema. This is a synchronous API, not a video generation task: there is no task ID to poll, public model selector, or free-text response mode.",[19,20,22],"h2",{"id":21},"request-parameters","Request parameters",[24,25,26,42],"table",{},[27,28,29],"thead",{},[30,31,32,36,39],"tr",{},[33,34,35],"th",{},"Field",[33,37,38],{},"Required",[33,40,41],{},"Contract",[43,44,45,59,71],"tbody",{},[30,46,47,53,56],{},[48,49,50],"td",{},[14,51,52],{},"prompt",[48,54,55],{},"Yes",[48,57,58],{},"String, 1–5000 characters",[30,60,61,66,68],{},[48,62,63],{},[14,64,65],{},"inputs",[48,67,55],{},[48,69,70],{},"Array of 1–8 media references",[30,72,73,78,80],{},[48,74,75],{},[14,76,77],{},"schema",[48,79,55],{},[48,81,82],{},"JSON Schema (supported 2020-12 subset) describing a top-level object",[10,84,85,86,89,90,93,94,97,98,101,102,105,106,111],{},"Each media reference supplies exactly one of ",[14,87,88],{},"url"," (publicly accessible), ",[14,91,92],{},"asset_id"," (an uploaded asset), or ",[14,95,96],{},"inline_data"," (",[14,99,100],{},"mime_type"," and base64 ",[14,103,104],{},"data","). Supported inline media includes JPEG, PNG, WebP, BMP, TIFF, GIF; WAV\u002FMP3 audio; and MP4\u002FMOV video. See the ",[107,108,110],"a",{"href":109},"\u002Freference\u002Fmedia-understanding\u002Funderstand-media","request schema"," for precise MIME types. Do not send local file paths as URLs.",[19,113,115],{"id":114},"extract-structured-data-with-python","Extract structured data with Python",[10,117,118,119,123],{},"After ",[107,120,122],{"href":121},"\u002Fguides\u002Fsdk#authenticate-the-python-client","configuring authentication",", replace the example URL with your own accessible media. The SDK sets a 180-second timeout for this operation.",[125,126,131],"pre",{"className":127,"code":128,"language":129,"meta":130,"style":130},"language-python shiki shiki-themes github-light github-dark","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nresult = client.understand_media(\n    prompt=\"Identify the main subject in the image.\",\n    inputs=[{\"url\": \"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"}],\n    schema={\n        \"type\": \"object\",\n        \"properties\": {\"subject\": {\"type\": \"string\"}},\n        \"required\": [\"subject\"],\n        \"additionalProperties\": False,\n    },\n)\nprint(result[\"output\"])\nprint(result[\"usage\"], result[\"cost_credit\"])\n","python","",[14,132,133,152,159,171,182,198,221,232,245,270,284,298,304,310,325],{"__ignoreMap":130},[134,135,138,142,146,149],"span",{"class":136,"line":137},"line",1,[134,139,141],{"class":140},"szBVR","from",[134,143,145],{"class":144},"sVt8B"," visionstory ",[134,147,148],{"class":140},"import",[134,150,151],{"class":144}," VisionStoryClient\n",[134,153,155],{"class":136,"line":154},2,[134,156,158],{"emptyLinePlaceholder":157},true,"\n",[134,160,162,165,168],{"class":136,"line":161},3,[134,163,164],{"class":144},"client ",[134,166,167],{"class":140},"=",[134,169,170],{"class":144}," VisionStoryClient.from_env()\n",[134,172,174,177,179],{"class":136,"line":173},4,[134,175,176],{"class":144},"result ",[134,178,167],{"class":140},[134,180,181],{"class":144}," client.understand_media(\n",[134,183,185,189,191,195],{"class":136,"line":184},5,[134,186,188],{"class":187},"s4XuR","    prompt",[134,190,167],{"class":140},[134,192,194],{"class":193},"sZZnC","\"Identify the main subject in the image.\"",[134,196,197],{"class":144},",\n",[134,199,201,204,206,209,212,215,218],{"class":136,"line":200},6,[134,202,203],{"class":187},"    inputs",[134,205,167],{"class":140},[134,207,208],{"class":144},"[{",[134,210,211],{"class":193},"\"url\"",[134,213,214],{"class":144},": ",[134,216,217],{"class":193},"\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"",[134,219,220],{"class":144},"}],\n",[134,222,224,227,229],{"class":136,"line":223},7,[134,225,226],{"class":187},"    schema",[134,228,167],{"class":140},[134,230,231],{"class":144},"{\n",[134,233,235,238,240,243],{"class":136,"line":234},8,[134,236,237],{"class":193},"        \"type\"",[134,239,214],{"class":144},[134,241,242],{"class":193},"\"object\"",[134,244,197],{"class":144},[134,246,248,251,254,257,259,262,264,267],{"class":136,"line":247},9,[134,249,250],{"class":193},"        \"properties\"",[134,252,253],{"class":144},": {",[134,255,256],{"class":193},"\"subject\"",[134,258,253],{"class":144},[134,260,261],{"class":193},"\"type\"",[134,263,214],{"class":144},[134,265,266],{"class":193},"\"string\"",[134,268,269],{"class":144},"}},\n",[134,271,273,276,279,281],{"class":136,"line":272},10,[134,274,275],{"class":193},"        \"required\"",[134,277,278],{"class":144},": [",[134,280,256],{"class":193},[134,282,283],{"class":144},"],\n",[134,285,287,290,292,296],{"class":136,"line":286},11,[134,288,289],{"class":193},"        \"additionalProperties\"",[134,291,214],{"class":144},[134,293,295],{"class":294},"sj4cs","False",[134,297,197],{"class":144},[134,299,301],{"class":136,"line":300},12,[134,302,303],{"class":144},"    },\n",[134,305,307],{"class":136,"line":306},13,[134,308,309],{"class":144},")\n",[134,311,313,316,319,322],{"class":136,"line":312},14,[134,314,315],{"class":294},"print",[134,317,318],{"class":144},"(result[",[134,320,321],{"class":193},"\"output\"",[134,323,324],{"class":144},"])\n",[134,326,328,330,332,335,338,341],{"class":136,"line":327},15,[134,329,315],{"class":294},[134,331,318],{"class":144},[134,333,334],{"class":193},"\"usage\"",[134,336,337],{"class":144},"], result[",[134,339,340],{"class":193},"\"cost_credit\"",[134,342,324],{"class":144},[19,344,346],{"id":345},"cli-and-mcp","CLI and MCP",[10,348,349,350,353,354,357],{},"The CLI accepts JSON for both ",[14,351,352],{},"--inputs"," and ",[14,355,356],{},"--schema",":",[125,359,363],{"className":360,"code":361,"language":362,"meta":130,"style":130},"language-bash shiki shiki-themes github-light github-dark","visionstory understand-media \\\n  --prompt \"Identify the main subject in the image.\" \\\n  --inputs '[{\"url\":\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"}]' \\\n  --schema '{\"type\":\"object\",\"properties\":{\"subject\":{\"type\":\"string\"}},\"required\":[\"subject\"],\"additionalProperties\":false}'\n","bash",[14,364,365,377,387,397],{"__ignoreMap":130},[134,366,367,371,374],{"class":136,"line":137},[134,368,370],{"class":369},"sScJk","visionstory",[134,372,373],{"class":193}," understand-media",[134,375,376],{"class":294}," \\\n",[134,378,379,382,385],{"class":136,"line":154},[134,380,381],{"class":294},"  --prompt",[134,383,384],{"class":193}," \"Identify the main subject in the image.\"",[134,386,376],{"class":294},[134,388,389,392,395],{"class":136,"line":161},[134,390,391],{"class":294},"  --inputs",[134,393,394],{"class":193}," '[{\"url\":\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"}]'",[134,396,376],{"class":294},[134,398,399,402],{"class":136,"line":173},[134,400,401],{"class":294},"  --schema",[134,403,404],{"class":193}," '{\"type\":\"object\",\"properties\":{\"subject\":{\"type\":\"string\"}},\"required\":[\"subject\"],\"additionalProperties\":false}'\n",[10,406,407,408,411,412,414,415,417,418,420,421,424],{},"Both local and remote MCP expose ",[14,409,410],{},"understand_media"," with ",[14,413,52],{},", ",[14,416,65],{},", and ",[14,419,77],{},". Remote MCP accepts public URLs and asset IDs, not local paths or inline media. The local Agent Skill helper supports the same ",[14,422,423],{},"understand-media"," command as the CLI.",[19,426,428],{"id":427},"response-billing-and-failure-handling","Response, billing, and failure handling",[10,430,431,432,435,436,414,439,417,442,445,446,448],{},"A successful REST response contains ",[14,433,434],{},"data.output"," (the structured object), ",[14,437,438],{},"data.usage.input_tokens",[14,440,441],{},"data.usage.output_tokens",[14,443,444],{},"data.cost_credit",". The SDK unwraps ",[14,447,104],{}," automatically. This operation can take up to 180 seconds; allow sufficient time in the calling application or MCP client as well.",[10,450,451,452,455],{},"Only successful requests are charged. Cost is based on token usage, converted at 1 credit per USD 0.10 and rounded up, with a minimum of 1 credit. There is a per-key concurrency limit; excess requests are rejected rather than queued. Content moderation can reject a request with code ",[14,453,454],{},"37100",".",[10,457,458],{},"Do not automatically repeat a timed-out request: the server may already have succeeded, and another successful call can incur another charge. Inspect the error before retrying. Never log API keys or base64 media.",[19,460,462],{"id":461},"related-guides","Related guides",[464,465,466,474,483],"ul",{},[467,468,469,473],"li",{},[107,470,472],{"href":471},"\u002Fguides\u002Faudio-understanding","Speech to Text"," — use transcription for speech, SRT subtitles, and word timestamps.",[467,475,476,480,481,455],{},[107,477,479],{"href":478},"\u002Freference\u002Fassets\u002Fcreate-asset","Assets API"," — upload media once and reuse the returned ",[14,482,92],{},[467,484,485,489],{},[107,486,488],{"href":487},"\u002Fguides\u002Ffor-agents","For agents"," — connect an MCP client or install the Agent Skill.",[491,492,493],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}",{"title":130,"searchDepth":154,"depth":154,"links":495},[496,497,498,499,500],{"id":21,"depth":154,"text":22},{"id":114,"depth":154,"text":115},{"id":345,"depth":154,"text":346},{"id":427,"depth":154,"text":428},{"id":461,"depth":154,"text":462},"Extract JSON data from images, audio, or video using a prompt and JSON Schema with the VisionStory SDK, CLI, or MCP.","md",{},{"title":505,"order":234},"Media Understanding","\u002Fguides\u002Fmedia-understanding",{"title":5,"description":501},"guides\u002Fmedia-understanding","FcDACFEOh5RTUhjhYRaya3NcQ32hgjYj-N8CoVZgCxI","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">result \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.understand_media(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    prompt\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Identify the main subject in the image.\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    inputs\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">[{\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">}],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    schema\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"type\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"object\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"properties\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"subject\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"type\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"string\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">}},\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"required\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"subject\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"additionalProperties\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">False\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(result[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"output\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">])\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(result[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"usage\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">], result[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"cost_credit\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">])\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">visionstory\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> understand-media\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --prompt\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"Identify the main subject in the image.\"\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --inputs\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '[{\"url\":\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"}]'\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --schema\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '{\"type\":\"object\",\"properties\":{\"subject\":{\"type\":\"string\"}},\"required\":[\"subject\"],\"additionalProperties\":false}'\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788547143927]