音频上传 API

上传音频文件并获取私有的 object_key。需要使用已上传文件的接口可引用该标识，文件须属于同一项目空间。

接口信息

接口路径：/v1/files/upload
请求方式：POST
请求格式：multipart/form-data
认证方式：请求头中的 X-API-Key
响应格式：JSON。请同时检查 HTTP 状态码和 succeed，通过 error_code 和 error_message 查看失败原因。

请求头

参数名	类型	必填	说明
`X-API-Key`	string	是	项目 API Key。

由 HTTP 客户端自动设置包含 boundary 的 multipart/form-data Content-Type。不要设置 application/json，也不要省略 multipart boundary。

表单参数

表单字段	类型	必填	说明
`scene`	string	是	文件类型，音频填写 `audio`。
`file`	file	是	一个非空音频文件，大小不超过 50 MiB。

scene 说明

`scene`	用途	最大大小	支持的文件扩展名
`audio`	音频文件上传	50 MiB	`.wav`、`.mp3`、`.m4a`、`.webm`、`.ogg`

文件须使用上表列出的扩展名，大小不超过 50 MiB。上传没有音频时长限制。后续使用文件时，请遵循对应接口的输入要求。

不接受 .flac、.aac 或 .opus 扩展名。AAC 和 Opus 是编码，不是文件扩展名；请选择允许的容器扩展名，并满足后续使用接口的要求。

频次限制

默认每个用户每小时最多上传 30 次，该用户的项目 Key 共用此限额。

响应参数

通用响应结构

字段	类型	说明
`error_code`	number	业务错误码，成功为 `0`。
`error_message`	string	错误信息。
`succeed`	boolean	上传是否成功。
`data`	object \| null	成功时为上传结果，失败时为 `null`。

data 字段

字段	类型	说明
`object_key`	string	已上传音频的私有文件标识。
`file_name`	string	上传时的原始文件名。
`size`	number	文件大小，单位为字节。
`scene`	string	上传场景，为 `audio`。

不返回公开下载地址。对象键只能用于上传时所属的项目空间及 API 环境。

响应示例

成功时返回 HTTP 200：

{
  "error_code": 0,
  "error_message": "",
  "succeed": true,
  "data": {
    "object_key": "returned-private-object-key",
    "file_name": "sample.wav",
    "size": 160044,
    "scene": "audio"
  }
}

请求示例

上传音频

export VUILABS_API_BASE_URL="https://api.vuilabs.ai"
export VUILABS_API_KEY="your-api-key"
curl --request POST \
  --url "$VUILABS_API_BASE_URL/v1/files/upload" \
  --header "X-API-Key: $VUILABS_API_KEY" \
  --form "scene=audio" \
  --form "file=@/path/to/sample.wav"

当其他接口需要已上传的音频文件时，原样传入返回的 data.object_key。该值是私有文件标识，不是公开下载地址。

常见错误

失败时返回非 2xx HTTP 状态码及统一 JSON 错误响应。

HTTP 状态	`error_code`	含义
`401`	`10003`	API Key 缺失或无效。
`400`	`10001`	multipart 请求无效、缺少或上传空文件、场景不支持。
`400`	`20012`	音频文件扩展名不受支持。
`413`	`20010`	文件超过 50 MiB。
`429`	`10005`	达到上传限额。
`504`	`10006`	上传超时。
`503`	`20002`	存储暂时不可用。
`500`	`10000`	服务发生未预期错误。

其他通用错误请参见错误码。

接口信息​

请求头​

表单参数​

scene 说明​

频次限制​

响应参数​

通用响应结构​

data 字段​

响应示例​

请求示例​

上传音频​

常见错误​