Upload an Audio File

Upload an audio file to the CEQUENS Voice API for use in voice calls. The uploaded file can be referenced in subsequent call requests to play custom audio content to recipients.

Endpoint

POST https://apis.cequens.com/voice/v1/voice/file

Authentication

Bearer token authentication is required. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Headers

Header	Value	Required
`Authorization`	Bearer token	Yes
`Content-Type`	`multipart/form-data`	Yes

Request Body

Parameter	Type	Description	Required
`file`	File	The audio file to upload	Yes

Upload Methods

You can upload the audio file like this:

Multipart form: Send the WAV file as a form file part with Content-Type: multipart/form-data. The first part carrying a filename is used; the field name does not matter.

Audio Specifications

Requirement	Value
Container	WAV (RIFF)
Encoding	Uncompressed PCM
Sample rate	8000 Hz
Channels	1 (mono)
Bit depth	16-bit
Maximum size	5 MB

Not accepted: MP3, Ogg, FLAC, M4A, A-law, mu-law, and ADPCM files.

Response

Status: 201 Created

{
  "reqId": "6b6f9b2d-6f6a-4a0d-9d28-0d4a1f6c6a11",
  "recordId": "2f8c1c0e-9f2f-4a3a-9d1a-0b7f7b0d8c31.wav",
  "bytes": 264044,
  "sampleRate": 8000,
  "channels": 1,
  "bitDepth": 16
}

Response Fields

reqId (string): Correlation ID for this request
recordId (string): The ID of the stored file; use it in <play recordId="..."> and as the fileId of the "Get an Audio File" endpoint
bytes (integer): Number of bytes stored
sampleRate (integer): Sample rate detected in the uploaded file
channels (integer): Channel count detected in the uploaded file
bitDepth (integer): Bit depth detected in the uploaded file

Example Request

curl -X POST https://apis.cequens.com/voice/v1/voice/file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/audio.wav"

Error Responses

Status Code	Error Code	Error Message	Description	Resolution
400	`INVALID_AUDIO_FORMAT`	`unsupported audio format: 2 audio channels (expected 1, mono), sample rate is 44100 Hz (expected 8000 Hz)`	The file does not match required audio specifications. Every mismatched property is listed in the message.	Verify the file is mono, 8000 Hz sample rate, 16-bit PCM, and in WAV format.
400	`UNSUPPORTED_CONTAINER`	`unsupported file format: MP3 (expected WAV / RIFF PCM)`	The uploaded file is not in WAV container format.	Convert the file to WAV format before uploading.
400	`EMPTY_REQUEST_BODY`	`empty request body: expected a WAV audio file`	No file was included in the request.	Ensure the file parameter is included in the request.
400	`MALFORMED_WAV_FILE`	`malformed WAV file: the header is truncated`	The WAV file structure is corrupted or incomplete.	Verify the file is not corrupted and is a valid WAV file.
401	`MISSING_AUTHENTICATION`	`There is no token provided`	Authorization header is missing or empty.	Include a valid Bearer token in the Authorization header.
413	`FILE_TOO_LARGE`	`file too large: <your-file-size> bytes, the maximum is 5 mega`	The uploaded file exceeds the 5 MB size limit.	Reduce the audio duration or compress the file. Maximum is approximately 5 MB.
502	`STORAGE_FAILURE`	`failed to store file`	Temporary storage service failure.	Retry the request after a brief delay.

Error Response Format

All error responses follow this structure:

{
  "reqId": "6b6f9b2d-6f6a-4a0d-9d28-0d4a1f6c6a11",
  "message": "error message details"
}