# 概念 (/docs/cloud/services/media/concepts)



一个库是素材的隔离单元。检索只会命中当前库的素材。

## 库与素材 [#库与素材]

素材有稳定的 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） [#文档与其他文件raw]

PDF、文本等 raw 文件只存放，不做理解，semantic 为 unavailable，不进入语义检索，只能按元数据（public\_id、display\_name、tags、context 等）用表达式检索。需要按全文内容检索文档，请使用[知识库](/docs/cloud/services/knowledge)。

## 删除与恢复 [#删除与恢复]

删除后立即不可见。库可在 7 天内恢复，到期后无法恢复。单个素材没有恢复接口。

## 与文件的区别 [#与文件的区别]

「文件」存放原始文件；素材库进一步组织、理解和检索内容。从文件导入是拷贝：两份文件独立，之后的修改或删除不会互相同步。

[API 参考 →](/docs/api/native/media)