Upload a recording

post

https://api.emaktalk.com/api/v1/recordings

Uploads audio and stores it as a recording on your account, converting it to WAV. For an ordinary upload the audio is also transcribed automatically: the transcript is stored in tts_text and becomes the description when you do not supply one. Sending tts_ssml instead marks the recording as text-to-speech and skips that transcription.

The file name decides whether this creates or replaces. The audio is stored under a file name made from the upload's name (file.name, or name when file is a plain string), cleaned up to a safe .wav name.

If the upload's name is already that clean .wav name and your account has a recording stored under it, this replaces that recording's audio and keeps its id, so everything that uses it plays the new audio (200).
Otherwise it creates a new recording (201). If the clean name is taken, the new recording gets the next free numbered name, such as greeting_2.wav: an upload never overwrites a different recording.
Send reject_duplicate: true to be refused (409) instead when your account already has a recording with that file name, or one whose name is the same ignoring case.

To replace a known recording's audio, use Update a recording.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

Recording name; it is cleaned up before storage, and a name that cleans down to nothing is rejected with 400.

file

string

required

The audio, either as a base64 string (optionally a data:<mime>;base64, URI) or as an object with base64 data plus optional name and type; it is converted to WAV on the server.

domain

string

Domain name — not an identifier — of the account to store the recording under; it is resolved by name, so send your own domain or omit the field to use your current account.

description

string

Description, truncated to 200 characters on a word boundary; defaults to the transcript, the text-to-speech text, or the name.

tts_ssml

string | null

Speech markup; sending it marks the recording as text-to-speech and skips the automatic transcription.

tts_text

string | null

Full spoken text, stored for text-to-speech recordings; for ordinary uploads the automatic transcript is stored here instead.

tts_provider

string | null

Label for the text-to-speech provider used.

tts_voice

string | null

Label for the text-to-speech voice used.

tts_editor_state

object | null

Opaque Speech Studio editor state, stored as-is.

reject_duplicate

boolean

When true, nothing is created or replaced if your account already has a recording stored under this file name, or one whose name is the same ignoring case: the answer is 409 Duplicate Recording. Defaults to false.

Responses

401

Missing or invalid API key.

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The upload replaced the audio of the recording already stored under this file name. The body is that recording, with its id unchanged.

201A new recording was created. The body is the recording.

400Nothing was stored: name is empty, the account in domain couldn't be resolved, file is missing or malformed, its base64 can't be decoded, no audio was received, or file.name has an extension that isn't a format we accept (WAV, MP3, M4A, AAC, OGG, Opus, WebM or FLAC).

403You are not an administrator of the account you named.

422Audio Conversion Failed: the file couldn't be converted to audio the phone system plays. Check that it plays, or upload it as WAV or MP3. Nothing was stored.

503Lookup Failed: your account's existing recordings couldn't be checked, so nothing was stored. Try again.