[{"data":1,"prerenderedAt":183},["ShallowReactive",2],{"reference-detail-zh-understand_media_api_v1_media_understand_post":3,"developer-code-9xxlc7":181,"developer-code-optk0u":182},{"tag":4,"sourceTag":4,"tagSlug":5,"method":6,"path":7,"slug":8,"summary":9,"description":10,"operationId":11,"groupOrder":12,"descriptionHtml":13,"parameters":14,"requestBody":22,"responses":80,"security":168,"codeSamples":171},"Media Understanding","media-understanding","POST","\u002Fapi\u002Fv1\u002Fmedia\u002Funderstand","understand-media","理解媒体（结构化）","使用前沿多模态模型对图像、音频和视频进行标注或提取结构化信息。提供指令（`prompt`）、媒体（`inputs`）和 JSON `schema` 后，响应中的 `output` 将符合该结构定义，可包含限定标签、评分、时间戳、转写字段等自定义内容。此接口同步执行。费用根据上游模型的 token 用量计算，包括输入媒体、提示词以及输出（含推理），每 0.10 美元折合 1 点，每次调用向上取整，仅成功时扣费。Beta 期间每个 API Key 的并发数受限，超限请求会被拒绝，不会排队。","understand_media_api_v1_media_understand_post",999,"\u003Cp>使用前沿多模态模型对图像、音频和视频进行标注或提取结构化信息。提供指令（\u003Ccode>prompt\u003C\u002Fcode>）、媒体（\u003Ccode>inputs\u003C\u002Fcode>）和 JSON \u003Ccode>schema\u003C\u002Fcode> 后，响应中的 \u003Ccode>output\u003C\u002Fcode> 将符合该结构定义，可包含限定标签、评分、时间戳、转写字段等自定义内容。此接口同步执行。费用根据上游模型的 token 用量计算，包括输入媒体、提示词以及输出（含推理），每 0.10 美元折合 1 点，每次调用向上取整，仅成功时扣费。Beta 期间每个 API Key 的并发数受限，超限请求会被拒绝，不会排队。\u003C\u002Fp>",[15],{"name":16,"in":17,"required":18,"description":19,"type":20,"example":21},"X-API-Key","header",true,"你的 VisionStory API Key（`sk-vs-...`），请仅保存在服务端。可在 [API Key 管理](\u002Fapi-keys) 中创建或管理，需要 Pro 或更高方案。","string","sk-vs-your-api-key",{"required":18,"contentType":23,"schema":24,"example":69},"application\u002Fjson",{"type":25,"description":26,"nullable":27,"properties":28},"MediaUnderstandRequest","",false,[29,60,64],{"name":30,"required":18,"type":31,"description":32,"nullable":27,"properties":33,"items":34},"inputs","MediaRef[]","1–8 个媒体项（图像\u002F音频\u002F视频），每项通过 `asset_id`、公开 `url` 或 `inline_data` 提供。允许混合媒体类型，请求结束后不保留媒体。",[],{"type":35,"description":36,"nullable":27,"properties":37},"MediaRef","媒体引用，必须且只能提供以下一种：`asset_id`（素材库中的素材，可跨请求复用）、`url`（单次使用的公开 URL）或 `inline_data`（单次使用的 base64 数据，不保存）。",[38,43,56],{"name":39,"required":27,"type":40,"description":41,"nullable":18,"properties":42},"asset_id","string | null","POST \u002Fapi\u002Fv1\u002Fasset 返回的素材 ID，用于跨请求复用素材。",[],{"name":44,"required":27,"type":45,"description":46,"nullable":18,"properties":47},"inline_data","InlineDataModel | null","仅供本次使用的内嵌 base64 媒体数据，不会加入素材库。图像支持 image\u002Fjpeg、image\u002Fjpg、image\u002Fpng、image\u002Fwebp、image\u002Fbmp、image\u002Ftiff、image\u002Fgif；音频支持 audio\u002Fwav、audio\u002Fx-wav、audio\u002Fwave、audio\u002Fmpeg、audio\u002Fmp3；视频支持 video\u002Fmp4、video\u002Fquicktime、video\u002Fmov。",[48,52],{"name":49,"required":18,"type":20,"description":50,"nullable":27,"properties":51},"data","文件原始字节编码后的 base64 字符串，不包含 `data:` URI 前缀。",[],{"name":53,"required":18,"type":20,"description":54,"nullable":27,"properties":55},"mime_type","内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] 和图像 ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic']。",[],{"name":57,"required":27,"type":40,"description":58,"nullable":18,"properties":59},"url","仅供本次使用的公开可访问媒体 URL，不会加入素材库。",[],{"name":61,"required":18,"type":20,"description":62,"nullable":27,"properties":63},"prompt","要提取或标注的内容。描述任务，必要时解释结构定义中各字段的含义；模型会按 `inputs` 中给定的顺序读取媒体。",[],{"name":65,"required":18,"type":66,"description":67,"nullable":27,"properties":68},"schema","object","输出必须符合的 JSON Schema，支持 draft 2020-12 的子集。顶层必须为对象。建议保持扁平且定义明确：用枚举限定标签集合，并为每个字段添加 `description`。",[],{"inputs":70,"prompt":73,"schema":74},[71],{"url":72},"https:\u002F\u002Fexample.com\u002Fcat.jpg","Identify the main subject in the image.",{"additionalProperties":27,"properties":75,"required":78,"type":66},{"subject":76},{"description":77,"type":20},"Main subject in the image.",[79],"subject",[81,140],{"status":82,"description":83,"contentType":23,"schema":84,"example":123,"examples":132,"headers":139},"200","请求成功",{"type":85,"description":26,"nullable":27,"properties":86},"BaseSuccessResponse_MediaUnderstandResponse_",[87,113,118],{"name":49,"required":18,"type":88,"description":89,"nullable":18,"properties":90},"MediaUnderstandResponse | null","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[91,96,100],{"name":92,"required":18,"type":93,"description":94,"nullable":27,"properties":95},"cost_credit","integer","本次调用扣除的点数，按上游费率计算用量费用后向上取整，最低 1 点。",[],{"name":97,"required":18,"type":66,"description":98,"nullable":27,"properties":99},"output","符合请求中 `schema` 定义的结构化结果。",[],{"name":101,"required":18,"type":102,"description":26,"nullable":27,"properties":103},"usage","MediaUnderstandUsage",[104,109],{"name":105,"required":27,"type":93,"description":106,"nullable":27,"default":107,"properties":108},"input_tokens","提示词和媒体输入消耗的 token 数量。",0,[],{"name":110,"required":27,"type":93,"description":111,"nullable":27,"default":107,"properties":112},"output_tokens","生成的 token 数量，包含模型的推理内容。",[],{"name":114,"required":27,"type":20,"description":115,"nullable":27,"default":116,"properties":117},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":119,"required":18,"type":120,"description":121,"nullable":27,"properties":122},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":124,"message":116,"server_time":131},{"cost_credit":125,"output":126,"usage":128},1,{"subject":127},"cat",{"input_tokens":129,"output_tokens":130},120,12,"2026-09-04T00:00:00Z",[133],{"name":116,"description":134,"summary":83,"value":135},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":136,"message":116,"server_time":131},{"cost_credit":125,"output":137,"usage":138},{"subject":127},{"input_tokens":129,"output_tokens":130},[],{"status":141,"description":142,"contentType":23,"schema":143,"example":165,"headers":167},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":144,"description":26,"nullable":27,"properties":145},"ErrorResponse",[146],{"name":147,"required":18,"type":148,"description":26,"nullable":27,"properties":149},"error","ErrorDetail",[150,154,158,162],{"name":151,"required":18,"type":93,"description":152,"nullable":27,"properties":153},"code","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":155,"required":27,"type":40,"description":156,"nullable":18,"properties":157},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":159,"required":27,"type":40,"description":160,"nullable":18,"properties":161},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":114,"required":18,"type":20,"description":163,"nullable":27,"properties":164},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":166},{"code":125,"message":20,"details":20,"hint":20},[],[169],{"APIKeyHeader":170},[],[172,175,178],{"lang":173,"source":174},"SDK","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\u002Fmedia\u002Fphoto.jpg\"}],\n    schema={\"type\": \"object\", \"properties\": {\"subject\": {\"type\": \"string\"}},\n            \"required\": [\"subject\"], \"additionalProperties\": False},\n)\nprint(result)",{"lang":176,"source":177},"REST","import os\nimport requests\n\nresponse = requests.post(\n    \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fmedia\u002Funderstand\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"inputs\": [\n        {\n          \"url\": \"https:\u002F\u002Fexample.com\u002Fcat.jpg\"\n        }\n      ],\n      \"prompt\": \"Identify the main subject in the image.\",\n      \"schema\": {\n        \"additionalProperties\": False,\n        \"properties\": {\n          \"subject\": {\n            \"description\": \"Main subject in the image.\",\n            \"type\": \"string\"\n          }\n        },\n        \"required\": [\n          \"subject\"\n        ],\n        \"type\": \"object\"\n      }\n    },\n)\nresponse.raise_for_status()\nprint(response.json())",{"lang":179,"source":180},"cURL","curl --request POST 'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fmedia\u002Funderstand' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application\u002Fjson' \\\n  --data '{\n  \"inputs\": [\n    {\n      \"url\": \"https:\u002F\u002Fexample.com\u002Fcat.jpg\"\n    }\n  ],\n  \"prompt\": \"Identify the main subject in the image.\",\n  \"schema\": {\n    \"additionalProperties\": false,\n    \"properties\": {\n      \"subject\": {\n        \"description\": \"Main subject in the image.\",\n        \"type\": \"string\"\n      }\n    },\n    \"required\": [\n      \"subject\"\n    ],\n    \"type\": \"object\"\n  }\n}'","\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\u002Fmedia\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>\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>\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>\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:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(result)\u003C\u002Fspan>\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:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"cost_credit\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"output\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"subject\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"cat\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"usage\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"input_tokens\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">120\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"output_tokens\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">12\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:#7EE787\">  \"message\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"success\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"server_time\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"2026-09-04T00:00:00Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788547144656]