POST /search
通过语义搜索或元数据搜索来搜索您的音频库。传入一个扁平的 JSON 请求体，包含您需要的过滤条件。所有字段均为可选，您只需传入需要的参数即可。
此端点也可以通过
POST /api/search访问，两种路径完全等价。注意：对/search发送 GET 请求会返回405，必须使用 POST 并携带 JSON 请求体。
请求
{
"q": "dog barking",
"target": "all",
"tags": ["Thunder", "Sci-Fi"],
"ucs": ["AIRBlow", "ANMLCat"],
"formats": ["WAV", "AIFF"],
"sampleRates": [44100, 48000],
"channels": [1, 2],
"bitDepths": [24],
"minDuration": 1.0,
"maxDuration": 10.0,
"sort": "BestMatch",
"ascending": false,
"limit": 50,
"offset": 0
}请求字段
| 字段 | 类型 | 描述 |
|---|---|---|
q | string | 搜索查询文本 |
target | string | 搜索模式（默认："all"），详见下表 |
tags | string[] | 按标签名称筛选，如 ["Thunder", "Sci-Fi"] |
ucs | string[] | 按 UCS 筛选。每个值按以下顺序解析：精确 CatID（如 "AIRBlow"）匹配该子类；大类名或其 CatShort（如 "ANIMALS"、"ANML"）匹配整个大类；无法识别的值退回前缀匹配。详见下方 UCS 值解析。 |
formats | string[] | 文件格式筛选，如 ["WAV", "MP3"] |
sampleRates | number[] | 采样率筛选，如 [44100, 48000] |
channels | number[] | 声道数筛选，如 [1, 2] |
bitDepths | number[] | 位深筛选，如 [16, 24] |
minDuration | number | 最短时长（秒） |
maxDuration | number | 最长时长（秒） |
sort | string | 排序方式（默认："BestMatch"），详见下表 |
ascending | boolean | 排序方向（默认：false，即降序） |
limit | number | 最多返回结果数（默认：50） |
offset | number | 分页偏移量（默认：0） |
UCS 值解析
ucs 中的每个字符串按以下顺序做大小写不敏感解析：
- 精确 CatID —— 已知的子类编码（如
"AIRBlow"、"ANMLCat"）精确匹配分配到该子类的文件。 - 大类名或 CatShort —— 顶层分类名（如
"ANIMALS"、"WEATHER"）或其缩写（如"ANML"、"WTHR"）匹配该大类下的所有子类。 - 兜底 —— 无法识别的值按前缀匹配已分配的 CatID。
注意： UCS v8.2.1 中少数字符串既是某大类的 CatShort 又是某具体子类的 CatID（例如
"BEEP"既是 BEEPS 的缩写，也是 BEEPS-GENERAL 的 CatID；"RAIN"、"WIND"以及全部 ARCHIVED/WEATHER/SWOOSHES 缩写同理）。此时精确 CatID 优先："BEEP"只匹配 BEEPS-GENERAL。要筛选整个大类，请传大类名或不含冲突的缩写——例如传"BEEPS"选中整个 BEEPS 家族。
target 有效值
| 值 | 描述 |
|---|---|
"all" | 混合搜索（语义 + 元数据，默认） |
"semantic" | 仅语义（AI 驱动）搜索 |
"sfx" | 仅限音效文件 |
"music" | 仅限音乐文件 |
"tag" | 按标签名称筛选 |
"fileName" | 按文件名搜索 |
"artist" | 按作者搜索 |
"grouping" | 按分组搜索 |
"genre" | 按流派搜索 |
"albumTitle" | 按专辑名称搜索 |
"comment" | 按备注搜索 |
"ucsId" | 按 UCS 类别 / 子类别搜索 |
"ucsFxName" | 按 UCS FxName 搜索 |
"ucsCreatorID" | 按 UCS CreatorID 搜索 |
"ucsSourceID" | 按 UCS SourceID 搜索 |
"ucsUserCategory" | 按 UCS UserCategory 搜索 |
"ucsVendorCategory" | 按 UCS VendorCategory 搜索 |
"ucsUserData" | 按 UCS UserData 搜索 |
sort 有效值
| 值 | 描述 |
|---|---|
"BestMatch" | 按相关性匹配度排序（使用语义 / 混合搜索时推荐） |
"DateAdded" | 按文件添加到库中的日期排序 |
"FileName" | 按文件名字母顺序排序 |
"Duration" | 按音频时长排序 |
"FileSize" | 按文件大小排序 |
"SampleRate" | 按采样率排序 |
"Channels" | 按声道数排序 |
"UCSCategory" | 按 UCS 类别排序 |
"format" | 按文件格式排序 |
"artist" | 按作者排序 |
"albumTitle" | 按专辑名称排序 |
"genre" | 按流派排序 |
响应
返回一个包含匹配文件对象的 JSON 数组。
[
{
"id": 12345,
"absoluteURL": "file:///Users/username/Audio/SFX/explosion_huge.wav",
"score": 95.5,
"matches": [
{
"chunkId": 6789,
"segments": [[0.5, 2.1], [3.0, 4.5]],
"score": 92.0
}
]
}
]响应字段
| 字段 | 类型 | 描述 |
|---|---|---|
id | number | 音频文件的唯一标识符 |
absoluteURL | string | 本地文件的绝对路径 URL |
score | number | 该文件的最高相关性匹配度（0-100） |
matches | array | 匹配的音频片段列表 |
matches[].chunkId | number | 具体匹配音频块的 ID |
matches[].segments | array | 匹配发生的时间段 [开始, 结束]（秒） |
matches[].score | number | 该具体片段的相关性匹配度 |