Audio Upload API

Upload an audio file and receive a private object_key. Use this identifier with APIs that accept an uploaded file from the same project space.

---

API information

• Endpoint: /v1/files/upload
• Request method: POST
• Request format: multipart/form-data
• Authentication: X-API-Key request header
• Response format: JSON. Check the HTTP status and succeed; use error_code and error_message for failures.

---

Request headers

Header	Type	Required	Description
X-API-Key	string	Yes	Project API key.

Let your HTTP client set the multipart/form-data Content-Type with its boundary. Do not set application/json or omit the multipart boundary.

---

Form parameters

Form field	Type	Required	Description
scene	string	Yes	File type. Use audio for audio files.
file	file	Yes	One nonempty audio file, no larger than 50 MiB.

scene details

scene	Purpose	Maximum file size	Supported filename extensions
audio	Audio file upload	50 MiB	.wav, .mp3, .m4a, .webm, .ogg

The file must use one of the listed extensions and be no larger than 50 MiB. There is no audio duration limit for uploading. Follow the input requirements of the API where you use the uploaded file.

Files with .flac, .aac, or .opus extensions are not accepted. AAC and Opus are codecs rather than filename extensions; use a permitted container extension that meets the requirements of the API consuming the file.

---

Rate limit

• The default limit is 30 uploads per user per hour, shared across that user's project keys.

---

Response parameters

Common response envelope

Field	Type	Description
error_code	number	Business error code; 0 on success.
error_message	string	Error description.
succeed	boolean	Whether the upload succeeded.
data	object | null	Upload result on success; null on failure.

data fields

Field	Type	Description
object_key	string	Private identifier for the uploaded audio file.
file_name	string	Original filename.
size	number	File size in bytes.
scene	string	Upload scene, audio.

No public download URL is returned. Use the object key only in its owning project space and the API environment where it was uploaded.

Response example

Successful requests return HTTP 200:

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

---

Request examples

Upload 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"

Use the returned data.object_key unchanged when an API requests an uploaded audio file. The object key is a private identifier, not a public download URL.

---

Common errors

Failures return a non-2xx HTTP status and the standard JSON error envelope.

HTTP status	error_code	Meaning
401	10003	Missing or invalid API key.
400	10001	Invalid multipart request, missing/empty file, or unsupported scene.
400	20012	Unsupported audio filename extension.
413	20010	File exceeds 50 MiB.
429	10005	Upload limit reached.
504	10006	Upload timed out.
503	20002	Storage is temporarily unavailable.
500	10000	Unexpected service error.

See Errors for other common failures.