acapela cloud / Documentation

Documentation

Samples

Script

Android

iOS/Mac

Python

Javascript

Bots

Alexa

Google Assistant

Tags

\TAG=VALUE\

List of the tags that can be inserted in the text

Voice Tags

\pau=number\	This tag inserts a pause of the specified number of milliseconds in the speech.
\prn="phonetic"\	With this tag, a user can synthesize a specific pronunciation inside a text. The phonetic string is composed of phonemes followed by space characters (phonetic alphabet is language-dependent). This tag is only suitable for inserting single words into the text. Unpredictable errors (mainly prosody) can occur when inserting greater units. Example: I will say: \prn=h e l @U1\." is equivalent to "I will say: hello..
\rms=number\	Sets the reading mode to spelling out each letter of each word (number is 1), or turns it off (number is 0).
\rmw=number\	Sets the reading mode to leaving audible pauses between each word (number is 1), or turns it off (number is 0).
\spd=number\	This tag sets the baseline average talking speed of the voice to the specified number of words per minute. Each voice has a default speed (about 180 words per minute, depending of the voice). Call to reset to the default speed. Range: 1/3 to 3 times the default speed (typically \spd=60\ to . This tag persists on the next texts being spoken until the next voice change or the next tag cancelling it out.
\rspd=number\	This tag sets the relative speed. 100 is the default speed (about 180 words per minute, depending of the voice). Call \rst\ to reset to the default speed. This tag persists on the next texts being spoken until the next voice change or the next tag cancelling it out.
\vct=number\	This tag controls the Voice Shaping of the voice, please refer to the Developer’s Guide for more information (min: 50%-150%). This tag persists on the next texts being spoken until the next voice change or the next tag cancelling it out.
\vol=number\	This tag sets the output volume. It is formatted as \ where volume is a value in the range 0 to 65535, inclusive. The default value is 65535. This tag persists on the next texts being spoken until the next voice change or the next tag cancelling it out.
\audioboost=val\	The Audio Boost has effect on 2 aspects of the speech, it improves the speech clarity by emphasizing medium and high frequencies, that are important for intelligibility, and it increases the perceived level of the speech with no saturation effect. This tag is formatted as \audioboost=val\ where val is a value in the range 0 to 90, inclusive. The default value is 0. The parameter val controls the emphasis of medium and high frequencies, from no emphasis (0), to maximum emphasis (90).
\rst\	This tag resets the engine to the default settings for the current mode.

Audio Tags

Only raw PCM 16-bit mono files with the same frequency as the voice used are supported by the audio tags.

\audio=play="filename.pcm"\	Plays a sound in the foreground (synchronous mode). Example: \audio=play="filename.pcm"\ I play a sound then I speak
\audio=mix="filename.pcm"\	Plays the file in the background, the speech synthesis will continue during the playing. Example: \audio=mix="filename.pcm"\ I play the sound while I speak
\audio=offset=x\	Skips x milliseconds at the beginning of the sound. Example: \audio=play="filename.pcm";offset=5000\ I play the sound from position 5000ms then I speak
mix mode only \audio=pause\ \audio=resume\ \audio=stop\ \audio=play\	pause / resume / stop / play Example: \audio=mix="filname.pcm"\ I play the musis while I speak , then I put the background music on pause! \audio=pause\ Then I resume it! \audio=resume\ Finally, I stop it! \audio=stop\ finished.
continue	Makes a sound continue in the background (asynchronous mode). There must be a duration=timeduration or until=timeposition argument. It turns the foreground playing into background playing Example: Please applaud! \audio=play="bravo.pcm";duration=100;continue\ Thank you!. Play sound for 100 milliseconds then continue playing it in the background while saying “Thank you!”.
duration=timeduration	Plays the sound until the position timeposition milliseconds within the sound is reached (play or mix commands) and then stops reading it. Example: \audio=play="mozart.pcm";until=5000\ Play music 5 secs then speak
until=timeposition	Plays the sound until the position timeposition milliseconds within the sound is reached (play or mix commands) and then stops reading it. Example: \audio=play="mozart.pcm";duration=2000\ Play song two seconds then speak and play again music for three seconds.\audio=play="mozart.pcm";offset=2000;until=5000\
\audio=repeat=status\	When status is on, continuously repeats the foreground or background sound (play or mix command). When it is off, does not repeat it (anymore). If status is a positive integral number, possibly zero, it will be the number of times to play the sound from the beginning as soon as its end is reached in addition to the regular play of the sound. In the end, the sound is player times + 1. Example: \audio=mix="bravo.pcm";repeat=on\I speak while they applaud!\audio=play;repeat=off\
\audio=volume=percentage\	Sets the volume of the sound to percentage % of its base level. 100 is the base level. Lesser than 100 reduces the volume, greather than 100 raises it (which can lead to distortion and saturation). Example: \audio=play="bravo.raw";volume=100;\ I play the sound file at 100% volume. To fade the volume in or out you need to do add a pause tag after Example: \audio=volume=80\ \pau=1000\ \audio=volume=90\ \pau=1000\ \audio=volume=100\ \pau=1000\ \audio=volume=90\ \pau=1000\ \audio=volume=80\ \pau=1000\ \audio=volume=70\ \pau=1000\ \audio=volume=60\ \pau=1000\

Api

POST /api/login/

Parameters

Field	Type	Description
email	String	your email
password	String	your password

Responses

Value	Description	Response
200	Login success	{token : string}
401	Login failure	{'error':'User account not active.'} {'error':'Unable to login with provided credentials.'}
400	Error	{'error':'Error description'}

                response=$(curl --silent -X POST 'https://www.acapela-cloud.com/api/login/'
                -d '{"email":"xxx@xxx.com","password":"xxxxxx"}'
                -H 'Content-Type:application/json')
                token=$(echo $response | sed "s/{.*\"token\":\"\([^\"]*\).*}/\1/g")
                echo $token
              

                import requests
                import json

                headers = {
                'Content-Type': 'application/json',
                }
                data = '{"email":"xxx@xxx.xxx","password":"xxxxxx"}'

                response = requests.post('https://www.acapela-cloud' + '/api/login/', headers=headers, data=data)

                # get token from login
                json_response = response.json()

                if response.status_code == 200:
                token = json_response["token"]
              

GET /api/logout/

Logout

GET POST /api/tos/

Get the Terms of service and Accept/reject them

GET Get the Terms of Service content

Parameters

Field	Type	Value - Description
none

Responses

Value	Description	Response
200	Terms of Service text	{'raw': '...', 'html : '...'}
400	Error	{'error':'Error description'}

POST Accept or reject the Terms of Service

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Field	Type	Value - Description
answer	String	yes / no

Responses

Value	Description	Response
200	Terms of Service accepted	{'success':'Terms of usage accepted. You can now use the service'}
200	Terms of Service rejected	{'success':'You didn't accept the Terms of Usage. You cannot use the service.'}
403	Not logged	{'error':'You must be logged.'}
401	Invalid token	{'detail':'Invalid token.'}
400	Error	{'error':'Error description'}

Samples

Curl
Python

    # Read Terms of Service list
    response=$(curl --silent -G 'https://www.acapela-cloud.com/api/tos/')
    echo "$response"
    echo ""

    # Accept Erms of Service
    response=$(curl --silent -X POST 'https://www.acapela-cloud.com/api/tos/' -d '{"answer":"yes"}' -H 'Authorization: Token '$token -H 'Content-Type: application/json') 
    echo "$response"
    echo ""
                

    import requests
    import json

    # get Terms of service text or accept/reject them
    headers = {
      'Authorization': 'Token ' + token,
        'Content-Type': 'application/json',
    }
  
    if answer == "":
      response = requests.get(server_url + '/api/tos/', headers=headers)
    else:
      data = '{"answer": "' + answer + '"}'
      response = requests.post(server_url + '/api/tos/', headers=headers, data=data.encode('utf-8'))
  
    return response
    
                

GET /api/account/

Retrieve your account information

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Field	Type	Description
None

Responses

Value	Description	Response
200	Account information (email/address/voices/credit ...)	Json string
400	Error	{'error':'Error description'}

Samples

Curl
Python

  response=$(curl --silent -G 'https://www.acapela-cloud.com/api/account/' -H 'Authorization: Token
  '$token)
  echo "account : $response"
                

    import requests
    import json

    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }

    response = requests.get('https://www.acapela-cloud.com' + '/api/account/', headers=headers)
    json_response = response.json()

    if response.status_code != 200:
      print(ERROR_MARK + ' - account details error')
    else:
      for item in json_response:
      print("\t" + str(item) + " : " + str(json_response[item]))

                

PATCH /api/account/

Update your account information

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Field	Type	Description
first_name	String	Your first name
last_name	String	Your last name
address	String	Your address
company	String	Your company
country	String	Your country (must match one of the values return by /api/coutnry)

Responses

Value	Description	Response
200	Account information (email/address/voices/credit ...)	Json string
400	Error	{'error':'Error description'}

Samples

Curl
Python

    response=$(curl --silent -X PATCH 'https://www.acapela-cloud.com/api/account/'
    -d '{"company":"Acapela","address":"rue"}'
    -H 'Authorization: Token '$token -H 'Content-Type: application/json')
    echo $response
                

    import requests
    import json

    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }

    data = '{"address": "' + address + '","first_name": "' + first_name + '"}'

    response = requests.patch('https://www.acapela-cloud.com' + '/api/account/', headers=headers,
    data=data)

                

GET POST /api/command/

Send a TTS command to retrieve audio stream or generate an audio file

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Field	Type	Value - Description
voice	String	Alice22_HQ - voice name (voice list returned in your account info)
text	String	Text to speak Warning : With the GET method text is limited to 2048 characters
output	String	stream (default) - return the audio samples by chunks storage - return an audio file content or a zip file content : audio + events (words + visemes) events - return a json file only with the events (words / visemes)
type	String	Audio type Values : "mp3" (default) / "ogg" / "wav" / "flac" / "ac3" / "asf" / "wma" / "opus" / "aac" "aiff" / "webm" / "mka" / "s16le" / "alaw" / "mulaw"
wordpos	String	Get word positions (json file) Values : "on" / "off" (default)
mouthpos	String	Get mouth positions (json file) Values : "on" / "off" (default)
speed	Int	Voice speed Values : 30 to 300 (default 100)
shape	Int	Voice Shaping Values : 50 to 150 (default 100)
volume	Int	Voice volume Values : 50 to 65535 (default 32768)
samplerate	Int	Audio sample rate in Hz Values : 8000 / 11025 / 12000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000 (default 22050) Note : Opus codec only supports 48000
bitrate	Int	Audio birate in kbps (mp3/ogg/ac3/asf/wma/opus) Possible values : 24 / 32 / 40 / 48 / 56 / 64 / 80 / 96 / 112 / 128 / 144 / 160 / 192 / 224 / 240 / 256 / 320 Default and supported values depend on the codec and the samplerate
dico	String	TTS Dictionary Value : Dictionary name (e.g. dico.dic)
application	String	Application name/id Value : Application name If you use multiple applications on a same account and need to have statistics for each application

Responses

Value	Description	Response
200	TTS generation success	Audio chunks (stream) Audio file content (storage with no position file) Zip file content (storage with position file)
403	Not logged	{'error':'You must be logged.'}
400	Not enough credit	{'error':'Not enough credit.'}
400	Incorrect or not allowed voice	{'error':'Voice not allowed.'}
400	Incorrect parameter (value)	{'error':'Invalid parameter or parameter value.'}
401	Invalid token	{'detail':'Invalid token.'}
400	Error	{'error':'Error description'}

Samples

Curl
Python

    response=$(curl --silent -G
    'https://www.acapela-cloud.com/api/command/?voice=Alice22k_HQ&text=hello&output=stream&type=mp3&token='$token)
    echo "response : $response"

    response=$(curl --silent -G --data-urlencode "text=hello" --data-urlencode "voice=Alice22k_HQ"
    --data-urlencode "output=storage" 'https://www.acapela-cloud.com/api/command/'
    -H 'Authorization: Token '$token)
    echo "response content : $response"

                

    import requests
    import json

    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }

    params = {'voice':voice,'output':output,'text':text,'type':type,'wordpos':wordpos}

    if output == "stream":
      response = requests.get('https://www.acapela-cloud.com' + '/api/command/', stream=True ,headers=headers, params=params)
    else:
      response = requests.get('https://www.acapela-cloud.com' + '/api/command/', headers=headers,params=params)

    if "audio" in response.headers['Content-Type']:
      file = open("audio.mp3", "wb")
      file.write(response.content)
      file.close()
    if "zip" in response.headers['Content-Type']:
      file = open("result.zip", "wb")
      file.write(response.content)
      file.close()

                

GET /api/stats/

Retrieve your stats (credit used, number of commands sent ...)

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Field	Description	Value
type	String	voice : voice usage statisitics command : command usage statisitics credit : credit usage statisitics billing : billing based on credit usage and price per hour purchase : online payments history (standalone account)
interval (optional)	String	day : statisitics cumulated day by day month : statisitics cumulated month by month year : statisitics cumulated year by year
option (optional)	String	application : statisitics by application name

Responses

Value	Description	Response
200	Statistic informaton	Json string
400	Not logged	{'error':'You must be logged.'}
401	Invalid token	{'detail':'Invalid token.'}
400	Field type missing	{'error':'Type field missing.'}
400	Invalid type	{'error':'Invalid type.'}
400	Invalid interval	{'error':'Invalid interval.'}
401	Login failure	{'error':'User account not active.'} {'error':'Unable to stats with provided credentials.'}
400	Error	{'error':'Error description'}

Samples

Curl
Python

    response=$(curl --silent -G 'https://www.acapela-cloud.com/api/stats/?type=credit&token='$token)
    echo "stats credit : $response"
                

    import requests
    import json

    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }
    params = { 'type':'voice','interval':'month'}

    response = requests.get('https://www.acapela-cloud.com' + '/api/stats/', headers=headers,params=params)
                

POST /api/password/change/

Update your password

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Value	Description	Response
password	String	your new password

Responses

Value	Description	Response
200	Password changed	{'success':'Password changed.'}
401	Invalid token	{'detail':'Invalid token.'}
400	Error	{'error':'Error description'}

Samples

Curl
Python

    response=$(curl --silent -X POST 'https://www.acapela-cloud.com/api/password/change/'
    -d '{"password":"test"}'
    -H 'Authorization: Token '$token -H 'Content-Type: application/json')
    echo $response
                

    import requests
    import json

    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }

    data = '{"password": "' + password + '"}'
    response = requests.post('https://www.acapela-cloud.com' + '/api/password/change/', headers=headers,data=data)
    return response
                

POST /api/password/reset/

Reset your password if you lost it

POST /api/storage/

Upload a dictionary file in your storage account folder

Dictionaries must have a .dic extension
Audio files (for audio tag) must have a .pcm or .raw extension

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Header

Field	Type	Description
Content-type	String	multipart/form-data
Content-Disposition	String	'attachment; filename=xxxxxx.xxx'

Parameters

Field	Type	Description
File	String	File path to upload For dictionary the extension must be .dic For audio file (audio tags) extension must bne .pcm or .raw

Responses

Value	Description	Response
200	File uplaoded	{"success":"File uploaded."}
400	Error	{'error':'Error description'}

Samples

Curl
Python

    # Storage upload
    response=$(curl --silent -X POST 'https://www.acapela-cloud.com/api/storage/'
    -F 'file=@./dico.dic' -H 'Authorization: Token '$token
    -H 'Content-Type: multipart/form-data'
    -H 'Content-Disposition: attachment; filename=dico.dic')
    echo 'response : ' $response
                

    import requests
    import json

    # upload file
    headers = {
      'Authorization': 'Token ' + token,
    }

    files = {"file": (file, open('dico.dic', 'rb'), 'multipart/form-data')}
    response = requests.post(server_url + '/api/storage/',files=files, headers=headers)

    return response

                

GET /api/storage/

Retrieve your files (dictionaries) stored in your account storage folder

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Parameters

Field	Type	Description
None

Responses

Value	Description	Response
200	List of files stored in the account folder	Json string
400	Error	{'error':'Error description'}

Samples

Curl
Python

    response=$(curl --silent -G 'http://localhost/api/storage/'
    -H 'Authorization: Token '$token)
    echo "files : $response"
                

    import requests
    import json

    # list user files
    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }

    response = requests.get(server_url + '/api/storage/', headers=headers)

    if response.status_code != 200:
      print(ERROR_MARK + ' - error')
    else:
      list = json.loads(response.text)
      for file in list:
        print(file)

                

DELETE /api/storage/

Remove a dictionary file from your storage account folder

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token

Header

Value	Description	Response
Content-type	String	application/json

Parameters

Field	Type	Description
File	String	Filename to delete

Responses

Value	Description	Response
200	File deleted	{'success':'File deleted.'}
400	Error	{'error':'Error description'}

Samples

Curl
Python

    response=$(curl --silent -X DELETE 'http://localhost/api/storage/'
    -d '{"file":"xxxxx.xx"}' -H 'Authorization: Token '$token
    -H 'Content-Type: application/json')
    echo 'response : ' $response
                

    import requests
    import json

    # Delete user file
    headers = {
      'Authorization': 'Token ' + token,
      'Content-Type': 'application/json',
    }
    data = '{"file": "' + file + '"}'
    response = requests.delete(server_url + '/api/storage/', headers=headers, data=data)
                

GET /api/country/

Retrieve the list of countries for account creation