使用 POST /api/v1/media/understand 从媒体中提取结构化数据，例如主体标签、场景描述或应用所需的字段。请求需要提供提示词、媒体输入和输出 JSON Schema。这是同步接口，不是视频生成任务：不返回供轮询的任务 ID，也不提供公开的模型选择参数或自由文本输出模式。
请求参数
| 字段 | 必填 | 约束 |
|---|---|---|
prompt | 是 | 字符串，1–5000 个字符 |
inputs | 是 | 包含 1–8 个媒体引用的数组 |
schema | 是 | 描述顶层对象的 JSON Schema，支持 2020-12 的部分规范 |
每个媒体引用只能提供一种来源：公开可访问的 url、已上传素材的 asset_id，或包含 mime_type 和 base64 data 的 inline_data。内联媒体支持 JPEG、PNG、WebP、BMP、TIFF、GIF 图片，WAV/MP3 音频及 MP4/MOV 视频。准确的 MIME 类型见请求结构。不要将本地文件路径作为 URL。
使用 Python 提取结构化数据
先配置认证，再将示例 URL 替换为你自己的可访问媒体。SDK 为此接口设置了 180 秒超时。
from visionstory import VisionStoryClient
client = VisionStoryClient.from_env()
result = client.understand_media(
prompt="Identify the main subject in the image.",
inputs=[{"url": "https://example.com/photo.jpg"}],
schema={
"type": "object",
"properties": {"subject": {"type": "string"}},
"required": ["subject"],
"additionalProperties": False,
},
)
print(result["output"])
print(result["usage"], result["cost_credit"])
CLI 和 MCP
CLI 的 --inputs 和 --schema 均接受 JSON：
visionstory understand-media \
--prompt "Identify the main subject in the image." \
--inputs '[{"url":"https://example.com/photo.jpg"}]' \
--schema '{"type":"object","properties":{"subject":{"type":"string"}},"required":["subject"],"additionalProperties":false}'
本地和远程 MCP 均提供 understand_media，参数为 prompt、inputs 和 schema。远程 MCP 接受公开 URL 和素材 ID，不接受本地路径或内联媒体。本地 Agent Skill 辅助脚本支持与 CLI 相同的 understand-media 命令。
响应、计费与错误处理
成功的 REST 响应包含 data.output（结构化对象）、data.usage.input_tokens、data.usage.output_tokens 和 data.cost_credit。SDK 会自动解包 data。此操作可能需要 180 秒，调用方应用或 MCP 客户端也应预留足够的超时时间。
仅成功请求计费。费用根据 token 用量计算，按每 0.10 美元折合 1 积分向上取整，最低 1 积分。每个 API Key 有并发限制，超出后直接拒绝，不排队。内容审核可能以错误码 37100 拒绝请求。
不要在超时后自动重复请求：服务端可能已经处理成功，再次成功调用会产生新费用。请先检查错误，再决定是否重试。不要记录 API Key 或 base64 媒体内容。