概念
库、素材与理解结果。
一个库是素材的隔离单元。检索只会命中当前库的素材。
库与素材
素材有稳定的 asset_id。public_id 是交付地址中的名称，可以带路径。asset_folder 组织素材；移动文件夹不改变 public_id。按 asset_folder 列出素材只匹配这一层，不包含子文件夹；空字符串表示根。display_name 是显示名称，不决定交付地址。音频使用 resource_type=video，并带 is_audio=true。
库名最长 64 个字符，可以重名；库以 library_id 区分。更新素材的 tags、context 或库的 labels 都是整体替换：传入的值就是新的全部内容，传 （tags 传 []）即清空。
上传 0 字节文件返回 400 FILE_EMPTY；声明或识别为图片却读不出宽高（例如被截断）的文件返回 400 Invalid image file。其他任意文件按 raw 存放。
理解
理解可以产出描述、标签、图片文字、音频转写与视频帧内容。片段结果带起止时间。记录不可变；新版本可以替代旧记录，默认不返回被替代的记录。
整体状态为 pending（等待）、processing（处理中）、ready（完成）、partial（部分完成）或 failed（失败）。单项状态为 pending、running、ready、failed、unsupported（不支持）或 skipped（跳过）。关闭理解或不支持的内容不会阻止原文件读取。
语义检索
当 semantic 为 ready，即可自然语言检索。默认混合检索结合关键词与语义，也可只用语义。命中带匹配内容；音视频片段带起止毫秒，方便定位。从未完成理解的素材不进入语义结果；重新处理中的素材继续用上一版结果参与检索，直到新结果就绪。
文档与其他文件（raw）
PDF、文本等 raw 文件只存放，不做理解，semantic 为 unavailable，不进入语义检索，只能按元数据（public_id、display_name、tags、context 等）用表达式检索。需要按全文内容检索文档，请使用知识库。
删除与恢复
删除后立即不可见。库可在 7 天内恢复，到期后无法恢复。单个素材没有恢复接口。
与文件的区别
「文件」存放原始文件；素材库进一步组织、理解和检索内容。从文件导入是拷贝：两份文件独立，之后的修改或删除不会互相同步。