通用文件上传接口

上传图片、音频或视频到 VUI Labs，成功后返回文件标识 object_key。例如，可以把音频上传响应中的 data.object_key 直接作为音色克隆接口的 ref_audio。

接口信息

接口路径: /v1/files/upload
请求方式: POST
请求格式: multipart/form-data
认证方式: Header 中的 X-API-Key
响应格式: JSON；请通过 succeed 判断上传是否成功，通过 error_code 和 error_message 查看失败原因

请求头

参数名	类型	必填	说明
X-API-Key	string	是	应用密钥

表单参数

参数名	类型	必填	说明
scene	string	是	上传场景：`image` / `audio` / `video`
file	file	是	要上传的文件

scene 说明

scene	用途	最大大小	ObjectKey 前缀
image	图片上传	10MB	`uploads/image/{uid}/...`
audio	音频上传	50MB	`uploads/audio/{uid}/...`
video	视频上传	200MB	`uploads/video/{uid}/...`

频次限制

普通用户每小时最多上传 30 次。

响应参数

通用响应结构

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

data 字段

字段	类型	说明
object_key	string	已上传文件的标识，可用于音色克隆等接口
file_name	string	上传时的原始文件名
size	number	文件大小，单位 byte
scene	string	上传场景
url	string	可选访问地址；默认不返回

响应示例

{
  "error_code": 0,
  "error_message": "成功",
  "succeed": true,
  "data": {
    "object_key": "uploads/audio/1001/20260630/1782820801123_abcd1234_sample.wav",
    "file_name": "sample.wav",
    "size": 123456,
    "scene": "audio"
  }
}

请求示例

上传音频

curl -X POST "https://api.vuilabs.cn/v1/files/upload" \
  -H "X-API-Key: your-secret-key-here" \
  -F "scene=audio" \
  -F "file=@/path/to/sample.wav"

上传后用于音色克隆

音色克隆是两步调用：先上传音频，再把上传响应中的 data.object_key 传给保存音色接口。两次请求应使用同一个 X-API-Key。

第一步，上传本地参考音频：

curl -X POST "https://api.vuilabs.cn/v1/files/upload" \
  -H "X-API-Key: your-secret-key-here" \
  -F "scene=audio" \
  -F "file=@/path/to/sample.wav"

成功后记录响应中的 data.object_key：

{
  "error_code": 0,
  "error_message": "成功",
  "succeed": true,
  "data": {
    "object_key": "uploads/audio/1001/20260630/1782820801123_abcd1234_sample.wav",
    "file_name": "sample.wav",
    "size": 123456,
    "scene": "audio"
  }
}

第二步，把该值原样传入 ref_audio：

curl -X POST "https://api.vuilabs.cn/v1/voice/save" \
  -H "X-API-Key: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "my-voice",
    "ref_audio": "uploads/audio/1001/20260630/1782820801123_abcd1234_sample.wav"
  }'

url 默认不返回是正常行为，克隆音色不需要把 ObjectKey 转换成公开 URL。服务端会自动解析参考音频并获得文本，无需手动填写参考文案。用于音色克隆的原始参考音频应不超过 50MB、时长为 3～60 秒。更多参数见音色克隆接口。

常见错误

HTTP 状态码	error_code	说明
200	10001	参数错误，例如缺少 `scene`、缺少 `file`、文件为空或 scene 不支持
200	10003	未授权，例如缺少或使用了无效的 `X-API-Key`
429	10005	上传频次超过限制
413	20010	文件大小超过当前 scene 限制
200	10000	上传处理失败，请查看 `error_message`；持续失败请联系支持

业务失败通常返回 HTTP 200，请检查 succeed 和 error_code。文件大小超限返回 HTTP 413，上传频次超限返回 HTTP 429，响应体仍使用统一 JSON 结构。

接口信息​

请求头​

表单参数​

scene 说明​

频次限制​

响应参数​

通用响应结构​

data 字段​

响应示例​

请求示例​

上传音频​

上传后用于音色克隆​

常见错误​