Acapela Cloud

Snippets

Script

Android

iOS/Mac

Python

Javascript

Alexa

Google

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} The token will be required for most API calls to ensure security (in authorization header) The token has no expiration date (deleted only if you call the logout function)
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

Authorization header

Field	Type	Description
token	String	Token returned by the login function 'Authorization': 'Token ' + token Once deleted any API call using it will be rejected. You'll have to login again to get a new valid token and use it in your API calls

Parameters

Field	Type	Description
none

Responses

Value	Description	Response
200	Logout success	{'success':'User logged out.'}
401	Invalid token	{'detail':'Invalid token.'}
400	Error	{'error':'Error description'}

Samples

Curl
Python

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

    import requests
    import json

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

    response = requests.get('https://www.acapela-cloud' + '/api/logout/', headers=headers)
    return response

                

GET /api/account/

Retrieve your account information (credits / voice list ...)

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 (name,gender, language,locale) / 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 / start speaking faster) return the audio samples by chunks or mixed audio/events if events are set to on (see events chapter below) text length limited to maximum 3000 characters for this mode file : return the audio file content when all is generated or a zip file if events are set to on : audio + events (words / visemes / markers) 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" / "wav_mulaw" / "wav_alaw":
wordpos	String	Get word positions (json file) Values : "on" / "off" (default)
mouthpos	String	Get mouth positions (json file) Values : "on" / "off" (default)
markpos	String	Get mark text tags positions (json file) Values : "on" / "off" (default)
speed	Int	Voice speed Values : 30 to 300 (default 100)
shaping	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. File extension must be .dic Multiple dictionaries must be separated by a comma (e.g dico=dico1.dic,dico2.dic) If several dictionaries are loaded and contain a same word/entry, the last loaded dictionary has the priority
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 (see FAQ)

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 file (dictionary / sound) in your storage account folder

GET /api/storage/

Retrieve your files (dictionaries / sounds) 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 / sound 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 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
    
                

Events

- Events
Word and viseme positions

If you need to highlight the text while speaking or display a speaking avatar you can retrieve the word and viseme positions for a given text
To do that you need to set to on the wordpos and/or mouthpos parameters in the /api/command/ request
Depending on the chosen ouput you'll get either a json file or mixed audio stream with all the TTS events (inclucing word and/or viseme positions)

Audio file and events json file (in a zip file)
     /api/command/?voice=Sharon22k_HQ&text=Hello&output=file&wordpos=on&mouthpos=on&token=xxxxxxxxxx

Only the events file (in a json file)
     /api/command/?voice=Sharon22k_HQ&text=Hello&output=events&wordpos=on&mouthpos=on&token=xxxxxxxxxx

Mixed streamed audio and events (see below for description and samples)
     /api/command/?voice=Sharon22k_HQ&text=Hello&output=stream&wordpos=on&mouthpos=on&token=xxxxxxxxxx

Events are provided as json

      {
        "EventKind": "Word",
        "ID": 5,
        "SamplePosition": 10006,
        "Time":  0.453786,
        "Flags": "TTS_Word",
        "WordOffset": 6,
        "WordSize": 3,
        "Word": "how"
      },
      {
        "EventKind": "Phoneme",
        "ID": 5,
        "SamplePosition": 10006,
        "Time": "0.453786",
        "Flags": "TTS_Word",
        "Duration": 59,
        "Mouth": {
            "bMouthHeight": 48,
            "bMouthWidth": 64,
            "bMouthUpturn": 128,
            "bJawOpen": 16,
            "bTeethUpperVisible": 16,
            "bTeethLowerVisible": 16,
            "bTonguePosn": 48,
            "bLipTension": 0
        },
        "Viseme": 12
      },

"EventKind": "Word"

      SamplePosition
      Word position in samples

      Time   
      Word position in seconds

      WordOffset
      Word position in bytes

      WordSize
      Word size in bytes

"EventKind": "Phoneme"

      Viseme : The viseme code based on the disney list
    
        SVP_0 = 0       'silence
        SVP_1 = 1       'ae ax ah
        SVP_2 = 2       'aa
        SVP_3 = 3       'ao
        SVP_4 = 4       'ey eh uh
        SVP_5 = 5       'er
        SVP_6 = 6       'y iy ih ix
        SVP_7 = 7       'w uw
        SVP_8 = 8       'ow
        SVP_9 = 9       'aw
        SVP_10 = 10     'oy
        SVP_11 = 11     'ay
        SVP_12 = 12     'h
        SVP_13 = 13     'r
        SVP_14 = 14     'l
        SVP_15 = 15     's z
        SVP_16 = 16     'sh ch jh zh
        SVP_17 = 17     'th dh
        SVP_18 = 18     'f v
        SVP_19 = 19     'd t n
        SVP_20 = 20     'k g ng
        SVP_21 = 21     'p b m
      
      SamplePosition
      Phoneme position in samples

      Time    
      Phoneme position in seconds

Mixed Streamed Audio/Events

      When using stream output with events enabled, you will receive data chunks that will contain events and/or audio buffers

      A buffer is received as follow : type:size\ncontent
      
      - type can be either audio or events
      - size gives the number of byte the buffer will contain
      
      So basically what you have to do is read incoming chunks byte per byte until you detect either "audio:" or "events:"
      Then you read the buffer length until you find the \n marker
      And finally you read the buffer content
      
      Note that a buffer might be contained in several chunks

Examples

Python

Javascript