[{"data":1,"prerenderedAt":510},["ShallowReactive",2],{"guide-\u002Fguides-zh\u002Fmedia-understanding":3,"developer-code-1crrd":508,"developer-code-1co8rwm":509},{"id":4,"title":5,"body":6,"description":499,"extension":500,"meta":501,"navigation":502,"path":504,"seo":505,"stem":506,"__hash__":507},"guidesZh\u002Fguides-zh\u002Fmedia-understanding.md","结构化媒体理解 API",{"type":7,"value":8,"toc":492},"minimark",[9,18,22,82,111,115,123,342,346,357,404,423,427,447,454,457,460,488],[10,11,12,13,17],"p",{},"使用 ",[14,15,16],"code",{},"POST \u002Fapi\u002Fv1\u002Fmedia\u002Funderstand"," 从媒体中提取结构化数据，例如主体标签、场景描述或应用所需的字段。请求需要提供提示词、媒体输入和输出 JSON Schema。这是同步接口，不是视频生成任务：不返回供轮询的任务 ID，也不提供公开的模型选择参数或自由文本输出模式。",[19,20,21],"h2",{"id":21},"请求参数",[23,24,25,41],"table",{},[26,27,28],"thead",{},[29,30,31,35,38],"tr",{},[32,33,34],"th",{},"字段",[32,36,37],{},"必填",[32,39,40],{},"约束",[42,43,44,58,70],"tbody",{},[29,45,46,52,55],{},[47,48,49],"td",{},[14,50,51],{},"prompt",[47,53,54],{},"是",[47,56,57],{},"字符串，1–5000 个字符",[29,59,60,65,67],{},[47,61,62],{},[14,63,64],{},"inputs",[47,66,54],{},[47,68,69],{},"包含 1–8 个媒体引用的数组",[29,71,72,77,79],{},[47,73,74],{},[14,75,76],{},"schema",[47,78,54],{},[47,80,81],{},"描述顶层对象的 JSON Schema，支持 2020-12 的部分规范",[10,83,84,85,88,89,92,93,96,97,100,101,104,105,110],{},"每个媒体引用只能提供一种来源：公开可访问的 ",[14,86,87],{},"url","、已上传素材的 ",[14,90,91],{},"asset_id","，或包含 ",[14,94,95],{},"mime_type"," 和 base64 ",[14,98,99],{},"data"," 的 ",[14,102,103],{},"inline_data","。内联媒体支持 JPEG、PNG、WebP、BMP、TIFF、GIF 图片，WAV\u002FMP3 音频及 MP4\u002FMOV 视频。准确的 MIME 类型见",[106,107,109],"a",{"href":108},"\u002Freference\u002Fmedia-understanding\u002Funderstand-media","请求结构","。不要将本地文件路径作为 URL。",[19,112,114],{"id":113},"使用-python-提取结构化数据","使用 Python 提取结构化数据",[10,116,117,118,122],{},"先",[106,119,121],{"href":120},"\u002Fguides\u002Fsdk#authenticate-the-python-client","配置认证","，再将示例 URL 替换为你自己的可访问媒体。SDK 为此接口设置了 180 秒超时。",[124,125,130],"pre",{"className":126,"code":127,"language":128,"meta":129,"style":129},"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,131,132,151,158,170,181,197,220,231,244,269,283,297,303,309,324],{"__ignoreMap":129},[133,134,137,141,145,148],"span",{"class":135,"line":136},"line",1,[133,138,140],{"class":139},"szBVR","from",[133,142,144],{"class":143},"sVt8B"," visionstory ",[133,146,147],{"class":139},"import",[133,149,150],{"class":143}," VisionStoryClient\n",[133,152,154],{"class":135,"line":153},2,[133,155,157],{"emptyLinePlaceholder":156},true,"\n",[133,159,161,164,167],{"class":135,"line":160},3,[133,162,163],{"class":143},"client ",[133,165,166],{"class":139},"=",[133,168,169],{"class":143}," VisionStoryClient.from_env()\n",[133,171,173,176,178],{"class":135,"line":172},4,[133,174,175],{"class":143},"result ",[133,177,166],{"class":139},[133,179,180],{"class":143}," client.understand_media(\n",[133,182,184,188,190,194],{"class":135,"line":183},5,[133,185,187],{"class":186},"s4XuR","    prompt",[133,189,166],{"class":139},[133,191,193],{"class":192},"sZZnC","\"Identify the main subject in the image.\"",[133,195,196],{"class":143},",\n",[133,198,200,203,205,208,211,214,217],{"class":135,"line":199},6,[133,201,202],{"class":186},"    inputs",[133,204,166],{"class":139},[133,206,207],{"class":143},"[{",[133,209,210],{"class":192},"\"url\"",[133,212,213],{"class":143},": ",[133,215,216],{"class":192},"\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"",[133,218,219],{"class":143},"}],\n",[133,221,223,226,228],{"class":135,"line":222},7,[133,224,225],{"class":186},"    schema",[133,227,166],{"class":139},[133,229,230],{"class":143},"{\n",[133,232,234,237,239,242],{"class":135,"line":233},8,[133,235,236],{"class":192},"        \"type\"",[133,238,213],{"class":143},[133,240,241],{"class":192},"\"object\"",[133,243,196],{"class":143},[133,245,247,250,253,256,258,261,263,266],{"class":135,"line":246},9,[133,248,249],{"class":192},"        \"properties\"",[133,251,252],{"class":143},": {",[133,254,255],{"class":192},"\"subject\"",[133,257,252],{"class":143},[133,259,260],{"class":192},"\"type\"",[133,262,213],{"class":143},[133,264,265],{"class":192},"\"string\"",[133,267,268],{"class":143},"}},\n",[133,270,272,275,278,280],{"class":135,"line":271},10,[133,273,274],{"class":192},"        \"required\"",[133,276,277],{"class":143},": [",[133,279,255],{"class":192},[133,281,282],{"class":143},"],\n",[133,284,286,289,291,295],{"class":135,"line":285},11,[133,287,288],{"class":192},"        \"additionalProperties\"",[133,290,213],{"class":143},[133,292,294],{"class":293},"sj4cs","False",[133,296,196],{"class":143},[133,298,300],{"class":135,"line":299},12,[133,301,302],{"class":143},"    },\n",[133,304,306],{"class":135,"line":305},13,[133,307,308],{"class":143},")\n",[133,310,312,315,318,321],{"class":135,"line":311},14,[133,313,314],{"class":293},"print",[133,316,317],{"class":143},"(result[",[133,319,320],{"class":192},"\"output\"",[133,322,323],{"class":143},"])\n",[133,325,327,329,331,334,337,340],{"class":135,"line":326},15,[133,328,314],{"class":293},[133,330,317],{"class":143},[133,332,333],{"class":192},"\"usage\"",[133,335,336],{"class":143},"], result[",[133,338,339],{"class":192},"\"cost_credit\"",[133,341,323],{"class":143},[19,343,345],{"id":344},"cli-和-mcp","CLI 和 MCP",[10,347,348,349,352,353,356],{},"CLI 的 ",[14,350,351],{},"--inputs"," 和 ",[14,354,355],{},"--schema"," 均接受 JSON：",[124,358,362],{"className":359,"code":360,"language":361,"meta":129,"style":129},"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,363,364,376,386,396],{"__ignoreMap":129},[133,365,366,370,373],{"class":135,"line":136},[133,367,369],{"class":368},"sScJk","visionstory",[133,371,372],{"class":192}," understand-media",[133,374,375],{"class":293}," \\\n",[133,377,378,381,384],{"class":135,"line":153},[133,379,380],{"class":293},"  --prompt",[133,382,383],{"class":192}," \"Identify the main subject in the image.\"",[133,385,375],{"class":293},[133,387,388,391,394],{"class":135,"line":160},[133,389,390],{"class":293},"  --inputs",[133,392,393],{"class":192}," '[{\"url\":\"https:\u002F\u002Fexample.com\u002Fphoto.jpg\"}]'",[133,395,375],{"class":293},[133,397,398,401],{"class":135,"line":172},[133,399,400],{"class":293},"  --schema",[133,402,403],{"class":192}," '{\"type\":\"object\",\"properties\":{\"subject\":{\"type\":\"string\"}},\"required\":[\"subject\"],\"additionalProperties\":false}'\n",[10,405,406,407,410,411,413,414,352,416,418,419,422],{},"本地和远程 MCP 均提供 ",[14,408,409],{},"understand_media","，参数为 ",[14,412,51],{},"、",[14,415,64],{},[14,417,76],{},"。远程 MCP 接受公开 URL 和素材 ID，不接受本地路径或内联媒体。本地 Agent Skill 辅助脚本支持与 CLI 相同的 ",[14,420,421],{},"understand-media"," 命令。",[19,424,426],{"id":425},"响应计费与错误处理","响应、计费与错误处理",[10,428,429,430,433,434,413,437,352,440,443,444,446],{},"成功的 REST 响应包含 ",[14,431,432],{},"data.output","（结构化对象）、",[14,435,436],{},"data.usage.input_tokens",[14,438,439],{},"data.usage.output_tokens",[14,441,442],{},"data.cost_credit","。SDK 会自动解包 ",[14,445,99],{},"。此操作可能需要 180 秒，调用方应用或 MCP 客户端也应预留足够的超时时间。",[10,448,449,450,453],{},"仅成功请求计费。费用根据 token 用量计算，按每 0.10 美元折合 1 积分向上取整，最低 1 积分。每个 API Key 有并发限制，超出后直接拒绝，不排队。内容审核可能以错误码 ",[14,451,452],{},"37100"," 拒绝请求。",[10,455,456],{},"不要在超时后自动重复请求：服务端可能已经处理成功，再次成功调用会产生新费用。请先检查错误，再决定是否重试。不要记录 API Key 或 base64 媒体内容。",[19,458,459],{"id":459},"相关指南",[461,462,463,471,481],"ul",{},[464,465,466,470],"li",{},[106,467,469],{"href":468},"\u002Fguides\u002Faudio-understanding","语音转文字","：语音转录、SRT 字幕及单词时间戳。",[464,472,473,477,478,480],{},[106,474,476],{"href":475},"\u002Freference\u002Fassets\u002Fcreate-asset","素材 API","：上传一次，通过返回的 ",[14,479,91],{}," 复用素材。",[464,482,483,487],{},[106,484,486],{"href":485},"\u002Fguides\u002Ffor-agents","面向 Agent","：连接 MCP 客户端或安装 Agent Skill。",[489,490,491],"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":129,"searchDepth":153,"depth":153,"links":493},[494,495,496,497,498],{"id":21,"depth":153,"text":21},{"id":113,"depth":153,"text":114},{"id":344,"depth":153,"text":345},{"id":425,"depth":153,"text":426},{"id":459,"depth":153,"text":459},"通过 VisionStory SDK、CLI 或 MCP，结合提示词与 JSON Schema，从图片、音频或视频中提取结构化数据。","md",{},{"title":503,"order":233},"媒体理解","\u002Fguides-zh\u002Fmedia-understanding",{"title":5,"description":499},"guides-zh\u002Fmedia-understanding","s_LMu7e0GMcsCSFSMLJ5pjN9MdVkmKCBXMMZhRaBbS4","\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]