使用前沿多模态模型对图像、音频和视频进行标注或提取结构化信息。提供指令（prompt）、媒体（inputs）和 JSON schema 后，响应中的 output 将符合该结构定义，可包含限定标签、评分、时间戳、转写字段等自定义内容。此接口同步执行。费用根据上游模型的 token 用量计算，包括输入媒体、提示词以及输出（含推理），每 0.10 美元折合 1 点，每次调用向上取整，仅成功时扣费。Beta 期间每个 API Key 的并发数受限，超限请求会被拒绝，不会排队。
请求头
X-API-Keystring必填你的 VisionStory API Key（sk-vs-...），请仅保存在服务端。可在 API Key 管理 中创建或管理，需要 Pro 或更高方案。
请求体
application/json必填inputsMediaRef[]必填1–8 个媒体项（图像/音频/视频），每项通过 asset_id、公开 url 或 inline_data 提供。允许混合媒体类型，请求结束后不保留媒体。
asset_idstring | null可为空POST /api/v1/asset 返回的素材 ID，用于跨请求复用素材。
inline_dataInlineDataModel | null可为空仅供本次使用的内嵌 base64 媒体数据，不会加入素材库。图像支持 image/jpeg、image/jpg、image/png、image/webp、image/bmp、image/tiff、image/gif；音频支持 audio/wav、audio/x-wav、audio/wave、audio/mpeg、audio/mp3；视频支持 video/mp4、video/quicktime、video/mov。
datastring必填文件原始字节编码后的 base64 字符串，不包含 data: URI 前缀。
mime_typestring必填内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] 和图像 ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic']。
urlstring | null可为空仅供本次使用的公开可访问媒体 URL，不会加入素材库。
promptstring必填要提取或标注的内容。描述任务，必要时解释结构定义中各字段的含义；模型会按 inputs 中给定的顺序读取媒体。
schemaobject必填输出必须符合的 JSON Schema，支持 draft 2020-12 的子集。顶层必须为对象。建议保持扁平且定义明确：用枚举限定标签集合，并为每个字段添加 description。
响应
200请求成功
application/json
dataMediaUnderstandResponse | null必填可为空当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。
cost_creditinteger必填本次调用扣除的点数，按上游费率计算用量费用后向上取整，最低 1 点。
outputobject必填符合请求中 schema 定义的结构化结果。
usageMediaUnderstandUsage必填input_tokensinteger提示词和媒体输入消耗的 token 数量。
output_tokensinteger生成的 token 数量，包含模型的推理内容。
messagestring便于阅读的状态消息；调用成功时为 "success"。
server_timestring · date-time必填服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。
default错误响应。所有失败均使用统一结构：error 对象包含数字错误码 code、便于阅读的 message、可选的 details 字符串，以及提供后续处理建议的可选 hint（便于 AI Agent 使用）。
application/json
errorErrorDetail必填codeinteger必填机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。
detailsstring | null可为空可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。
hintstring | null可为空供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。
messagestring必填便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。