POST /asset

将磁盘上的音频文件添加到 Curlo 音频库的文件夹中，同时指定其元数据。非常适合自动化场景：田野录音机或渲染管线落盘一个文件后，脚本通过一次请求即可完成入库，并附带标题、艺术家、标签与 UCS 分类。

此端点也可以通过 POST /api/asset 访问，两种路径完全等价。

工作方式

folderPath 必须是已添加到 Curlo 的本地文件夹的磁盘绝对路径。合集（Collection）是虚拟文件夹，不能作为导入目标。
如果文件已经位于目标文件夹内，将直接原地入库，不会发生复制。
否则默认将文件复制到目标文件夹；传入 "move": true 则改为移动。绝不覆盖已存在的同名文件。
物理属性（时长、采样率、声道、格式等）始终自动检测，不可覆盖。
您提供的元数据优先于从文件中读取的值；省略的字段保留自动检测结果，传空字符串则清空该字段。
Curlo 会对每次导入计算文件指纹：重复添加相同文件到同一文件夹会返回 409，并附上已存在资产的 ID。
创建完成后，资产会进入后台 AI 向量索引队列，索引完成后即可被语义搜索检索到。

请求

{
  "filePath": "/Users/me/Downloads/boom_v2.wav",
  "folderPath": "/Volumes/SFX/Explosions",
  "move": false,
  "writeToFile": false,
  "title": "Big Boom v2",
  "artist": "StudioX",
  "genre": "Cinematic",
  "comment": "Great for trailers",
  "assetType": "sfx",
  "isFavorite": true,
  "tags": ["explosion", "cinematic"],
  "ucsCatID": "EXPLReal",
  "ucsFxName": "Boom Big 02",
  "ucsCreatorID": "StudioX",
  "ucsSourceID": "Action Pack Y"
}

请求字段

字段	类型	描述
`filePath`	`string`	必填。音频文件在磁盘上的绝对路径（支持 `~` 展开）。必须是受支持的格式（WAV、MP3、FLAC、AIFF 等）
`folderPath`	`string`	必填。目标文件夹的绝对路径——必须是已添加到 Curlo 的本地文件夹
`move`	`boolean`	可选。默认 `false` 将文件复制到目标文件夹；`true` 则移动。文件已在目标文件夹内时忽略此参数
`writeToFile`	`boolean`	可选。默认 `false` 仅将元数据存入 Curlo 数据库；`true` 则同时写入音频文件本身（标准标签，WAV 还会写入 UCS BEXT 块）
`title`	`string`	可选。省略 = 保留从文件读取的值；传 `""` 清空该字段。下方所有元数据字段语义相同
`artist`	`string`	可选的艺术家覆盖
`genre`	`string`	可选的流派覆盖
`comment`	`string`	可选的备注覆盖
`albumTitle`	`string`	可选的专辑名覆盖
`grouping`	`string`	可选的分组覆盖
`bpm`	`number`	可选的 BPM 覆盖
`assetType`	`string`	可选。`"sfx"`、`"music"` 或 `"unknown"`
`isFavorite`	`boolean`	可选。将新资产标记为收藏
`tags`	`string[]`	可选的要分配的标签名数组。不存在的标签会自动创建并自动分配颜色
`ucsCatID`	`string`	可选的 UCS Category ID 覆盖
`ucsFxName`	`string`	可选的 UCS FxName 覆盖
`ucsCreatorID`	`string`	可选的 UCS CreatorID 覆盖
`ucsSourceID`	`string`	可选的 UCS SourceID 覆盖
`ucsUserCategory`	`string`	可选的 UCS UserCategory 覆盖
`ucsVendorCategory`	`string`	可选的 UCS VendorCategory 覆盖
`ucsUserData`	`string`	可选的 UCS UserData 覆盖

响应

返回 201 Created 与新创建的资产——结构与 GET /asset 相同，另多一个字段：

{
  "id": 12347,
  "fileName": "boom_v2.wav",
  "format": "WAV",
  "duration": 3.2,
  "tags": ["explosion", "cinematic"],
  "warnings": ["Failed to create tag 'cinematic': network unavailable"]
}

响应字段

所有字段与 GET /asset 完全一致。额外字段：

字段	类型	描述
`warnings`	`string[]`	仅在出现非致命问题时存在（如某个标签创建失败、元数据写入音频文件失败）。资产本身已创建成功

错误

状态码	含义
`400`	`filePath` 或 `folderPath` 缺失/为空、音频格式不受支持、`assetType` 无效，或文件无法解析
`403`	已达免费版 5,000 文件上限
`404`	音频文件不存在，或 `folderPath` 未匹配到任何已添加到 Curlo 的本地文件夹
`409`	目标文件夹中已存在同名文件，或相同指纹的文件已在该文件夹中入库
`500`	服务器内部错误