NAV Navbar
OAuth2 (cURL) HMAC (python3)
  • Introduction
  • Authentication
  • Requests
  • User
  • Accounts
  • Voices
  • Voice Build
  • Introduction

    Welcome to the VocaliD API!

    Authentication

    All endpoints are authenticated using either HMAC or OAuth2.

    HMAC

    Example code to generate API request using HMAC:

    import hashlib
    import hmac
    import random
    import pprint
    import time
    import datetime
    import requests as http_requests
    
    
    URL_BASE = "https://vocalid.co"
    API_SECRET = "1234567890"
    API_KEY = "1234567890"
    
    
    def get_test_nonce():
        return str(int(time.time() * 10000)) + str(random.getrandbits(64))
    
    def get_timestamp():
        t = datetime.datetime.utcnow()
        return t.isoformat()
    
    def to_hexdigest(data):
        h = hashlib.sha256()
        h.update(data.encode('latin-1'))
        return h.hexdigest()
    
    # generates authorization header for sending requests
    def generate_authorization_header(secret, method, endpoint, params, nonce, body, timestamp, **kwargs):
        signature = generate_signature(secret, method, endpoint, params, nonce, body, timestamp, **kwargs)
        return "signature={}, nonce={}, timestamp={}".format(signature, nonce, timestamp)
    
    
    # generates signature based on required args
    def generate_signature(secret, method, endpoint, params, nonce, body, timestamp, **kwargs):
        body = to_hexdigest(body)
    
        ########################################
        #   GET
        #   /api/v1/.../.../
        #   param1=1&parma2=2
        #   nonce
        #   body as sha256
        #   timestamp as iso 8601
        ########################################
        data = "{}\n{}\n{}\n{}\n{}\n{}".format(method, endpoint, params, nonce, body, timestamp)
        data = to_hexdigest(data)
        # hmac only allows str not unicode
        h = hmac.new(bytes(secret, 'latin-1'), bytes(data, 'latin-1'), hashlib.sha256)
        return h.hexdigest()
    
    
    def sign_and_send(endpoint, method, body=None, params=None, files=None, json=None):
        url = URL_BASE + endpoint
        r = http_requests.Request(method, url, data=body, params=params, files=files, json=json)
        prepped = r.prepare()
    
        params_split = prepped.path_url.split("?")
        params = params_split[1] if len(params_split) == 2 else ""
    
        data_to_sign = {
            "nonce": get_test_nonce(),
            "secret": SECRET,
            "method": method,
            "endpoint": endpoint,
            "params": params,
            "body": prepped.body if prepped.body else "",
            "timestamp": get_timestamp()
        }
    
        prepped.headers["Authorization"] = generate_authorization_header(**data_to_sign)
        with http_requests.Session() as session:
            response = session.send(prepped)
            pprint.pprint({"status": response, "elapsed": response.elapsed, "json":response.json()})
            return response.json()
    
    # Refer to HMAC (python).
    

    VocaliD will provide you with your API key (not private) and API secret (private) when setting up your account. Some example code is provided in the sidebar to illustrate the process of issuing an authenticated request.

    Authorization Header

    Authorization: signature=<signature>, nonce=<nonce>, timestamp=<timestamp>

    OAuth2

    VocaliD OAuth2 api supports both both client credentials and authorization grant types.

    Authorization Header

    authorization: Bearer <access_token>

    Client Credentials

    Client Credentials:

    'Refer to Oauth2 (cURL).'
    
    $ curl -u client_id:client_secret \
    https://vocalid.co/api/v1/oauth/token \
    -d 'grant_type=client_credentials' \
    -d 'scope=voice:synthesis'
    

    Tokens can be revoked:

    $ curl -u client_id:client_secret \
    https://vocalid.co/api/v1/oauth/revoke \
    -d 'token=<access_token>'
    

    Tokens can be introspected:

    $ curl -u client_id:client_secret \
    https://vocalid.co/api/v1/oauth/introspect \
    -d 'token=<access_token>'
    

    HTTP Request

    POST https://vocalid.co/api/v1/oauth/token

    Post Data

    Parameter Description Example
    grant_type specifies type of grant being requests. client_credentials
    scope list of scopes voice:synthesis

    Response

    Parameter Description Example
    access_token bearer token used for api requests pZHNK9LwgZujg9t3zMj1yzzcbeaZwFN3T5CgLxpdtl
    expires_in time in seconds token will expire 15552000
    token_type type of token Bearer
    scope list of scopes voice:synthesis

    Requests

    Post

    Post data can be sent using either form-data or json content types, in both cases json data is sent.

    Form Data

    Parameters are sent in a json object under the data form key.

    Headers

    Parameter Value
    content-type multipart/form-data

    JSON

    Parameters are sent in a json object.

    Headers

    Parameter Value
    content-type application/json

    User

    Query user information

    endpoint = "/api/v1/external/user/info/"
    payload = {"api_key": API_KEY}
    return sign_and_send(endpoint, method="GET", params=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    https://vocalid.co/api/v1/external/user/info/ 
    

    The above command returns a list of voice build requests as json:

    {
      "nickname": "MyFakeNickname"
    }
    

    This endpoint returns information about the current user.

    HTTP Request

    GET https://vocalid.co/api/v1/external/user/info/

    Scope

    user:info

    Query Parameters

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)

    Results

    Parameter Description
    nickname the nickname chosen by the user. (nullable)

    Accounts

    Register new account

    endpoint = "/api/v1/external/account/register/"
    payload = {"api_key": API_KEY , "gender": "male", "age": "1"}
    sign_and_send(endpoint, method="POST", json=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json"  \
    https:/vocalid.co/api/v1/external/account/register/ \
    -d '{"gender": "male", "age": "25"}'
    

    The above command returns JSON structured like this:

    {
      "account_id": "123456"
    }
    

    This endpoint creates a new account.

    HTTP Request

    POST https://vocalid.co/api/v1/external/account/register/

    Scope

    external_account

    Post Data

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    gender the gender of the user. May be “male”, “female”, or “other”
    age the age of the user. Must be a whole number

    Post a recording

    endpoint = "/api/v1/external/recording/save/"
    payload = {"data": json.dumps({"api_key": API_KEY,
               "account_id": ACCOUNT_ID,
               "sentence": "this is my vocal identity."})}
    files = {"file": open("/path/to/file.wav")}
    sign_and_send(endpoint, method="POST", body=payload, files=files)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: multipart/form-data"  \
    https://vocalid.co/api/v1/external/recording/save/ \
    -F 'file=@/path/to/file.wav' \
    -F 'data={"account_id": "<account_id>", "sentence": "this is a sample"}'
    

    The above command returns JSON structured like this:

    {
        "sentence_status": {"code": "OK"},
        "status": 200
    }
    

    Upload a recording and assign it to a previously registered user account.

    HTTP Request

    POST https://vocalid.co/api/v1/external/recording/save/

    Scope

    external_account

    Post Data

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    account_id the id of a previously created user account
    sentence a transcription of the recorded audio (i.e. what the user is saying in the recording)

    Response Sentence Status Codes

    Status Description
    OK Recording submission was successful.
    OVERDRIVEN Your recordings are coming through too loud. We suggest adjusting the microphone position to about 2 inches from the corner of your mouth - not directly in front of your mouth.
    UNDERDRIVEN Your recordings are coming through too quiet. It may be worth checking to make sure that your computer is recognizing your headset as the main form of sound input.

    Query account information

    endpoint = "/api/v1/external/account/info/"
    payload = {"api_key": API_KEY, "account_id": ACCOUNT_ID}
    sign_and_send(endpoint, method="GET", params=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    -G https://vocalid.co/api/v1/external/account/info/ \
    -d 'account_id=<account_id>'
    

    The above command returns JSON structured like this:

    {
      "sentences_recorded": 0
    }
    

    Query info about a previously registered user account.

    HTTP Request

    GET https://vocalid.co/api/v1/external/account/info/

    Scope

    external_account

    Query Parameters

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    account_id the id of a previously created user account

    Voices

    Query available voices

    endpoint = "/api/v1/external/voices/list/"
    payload = {"api_key": API_KEY}
    sign_and_send(endpoint, method="GET", params=payload)
    
    
    $ curl -H "Authorization: Bearer <account_id>" \
    https://vocalid.co/api/v1/external/voices/list/ \
    -X "GET"
    

    The above command returns JSON structured like this:

    {
      "voices": 
        [{"account_id": null,
          "can_download": true,
          "can_stream": true,
          "download_token": "123456",
          "expiration": null,
          "synthesis_count": 8,
          "voice_id": "7890123"
        }]
    }
    

    Query voices available for synthesis and download.

    HTTP Request

    GET https://vocalid.co/api/v1/external/voices/list/

    Scope

    voice:list

    Query Parameters

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)

    Results

    Parameter Description
    account_id the id of the account that the voice was built for or 'null' if the voice is not associated with a specific account.
    can_download boolean indicating whether or not the voice can be downloaded via the the API.
    can_stream boolean indicating whether or not the voice can be used for synthesis via the API.
    download_token token used for downloading the voice or generating synthesis.
    expiration the time after which the voice will no longer be available or null if the voice will never expire.
    synthesis_count the number of synthesis requests that have been made for the voice.
    voice_id the ID of a previously created voice.
    filename recommended filename when downloading voice locally.
    model_name type of voice model (Hi Res or Low Res).
    name name assigned to voice.

    Synthesis

    endpoint = "/api/v1/external/synthesis/"
    payload = {"api_key": API_KEY,
               "script": "this is my vocal identity",
               "download_token": DOWNLOAD_TOKEN,
               "pitch": 1,
               "rate": 1,
    }
    sign_and_send(endpoint, method="GET", params=payload)
    
    
    $ curl -H "Authorization: Bearer <access_token>" \
    -G https://vocalid.co/api/v1/external/synthesis/ \
    -d 'download_token=<download_token>' --data-urlencode 'script=This is a sample' -d 'pitch=1' -d 'rate=1'
    

    The above command returns audio data with a content-type of audio/wav unless a put_url is provided. If a put_url is provided a json response will be returned with the status code and response of the put request.

    boto3.client('s3').generate_presigned_url('put_object', {'Bucket': bucket, 'Key': key, 'ContentType': 'audio/wav'})
    

    The above command returns a pre-signed put url for s3 that can be used in the put_url parameter.

    Convert a line of text into speech.

    HTTP Request

    GET https://vocalid.co/api/v1/external/synthesis/

    Scope

    voice:synthesis

    Query Parameters

    Parameter Default Description
    api_key None a non-private API key provided by VocaliD. (HMAC Only)
    download_token None the download token of a previously created voice.
    script None the text to synthesize, max chars 256.
    pitch 1 pitch modifier. Valid range (0, 10]. < 1 lowers pitch, > 1 increases pitch.
    rate 1 rate modifier. Valid range (0, 10]. < 1 lowers rate, > 1 increases rate.
    container wav Specifies container format of audio data. Can be wav or empty string for raw pcm data.
    sample_rate 48000 Specifies sample rate of audio data. must be 8000, 16000, 11025, 22050, 32000, 44100 or 48000.
    put_url None Pre-authenticated url that the server will upload resulting audio file to via a put request. Files put to the url will have the content-type of audio/wav.

    Download Voice

    endpoint = "/api/v1/external/voices/download/<download_token>"
    payload = {"api_key": API_KEY, "device_id": DEVICE_ID}
    sign_and_send(endpoint, method="GET", params=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    https://vocalid.co/api/v1/external/voices/download/<download_token> \
    -G -d 'device_id=<device_id>'
    

    The above command returns voice file as binary data.

    Download voice file for enabling voice for local synthesis.

    HTTP Request

    GET https://vocalid.co/api/v1/external/voices/download/<download_token>

    Scope

    voice:download

    Query Parameters

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    device_id id of registered device.

    Download License File

    endpoint = "/api/v1/external/licenses/<download_token>"
    payload = {"api_key": API_KEY, "device_id": DEVICE_ID}
    sign_and_send(endpoint, method="GET", params=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    https://vocalid.co/api/v1/external/licenses/<download_token> \
    -G -d 'device_id=<device_id>'
    

    The above command returns license file as binary data.

    Download license file for local synthesis.

    HTTP Request

    GET https://vocalid.co/api/v1/external/licenses/<download_token>

    Scope

    voice:download

    Query Parameters

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    device_id id of registered device.

    Voice Build

    Request voice build

    endpoint = "/api/v1/external/build/new/"
    payload = {"api_key": API_KEY, "account_id": ACCOUNT_ID}
    return sign_and_send(endpoint, method="POST", json=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json"  \
    https://vocalid.co/api/v1/external/build/new/ \
    -d '{"account_id": "<account_id>"}'
    

    The above command returns JSON structured like this on success:

    {
      "build_id": "bb0928ed181d4a6d913e3024e27bad67",
      "status": "success"
    }
    

    If a build has already been requested:

    {
      "message": "account already has a voice build pending.", 
      "status": "error"
    }
    

    This endpoint requests a new voice is built for a given account.

    HTTP Request

    POST https://vocalid.co/api/v1/external/build/new/

    Scope

    voice_build

    Post Data

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    account_id the id of a previously created user account

    Query status of voice builds

    endpoint = "/api/v1/external/build/status/"
    payload = {"api_key": API_KEY, "status": "COMPLETE"}
    return sign_and_send(endpoint, method="GET", params=payload)
    
    $ curl -H "Authorization: Bearer <access_token>" \
    https://vocalid.co/api/v1/external/build/status/ 
    

    The above command returns a list of voice build requests as json:

    [
      {
        "account_id": "123456",
        "build_id": "876543",
        "status": "ERROR"
      },
      {
        "account_id": "234567",
        "build_id": "987654",
        "status": "PENDING"
      },
      {
        "account_id": "345678",
        "build_id": "765432",
        "status": "COMPLETE",
        "voice_id": "123456"
      }
    ]
    

    This endpoint returns a list of requested voice builds.

    HTTP Request

    GET https://vocalid.co/api/v1/external/build/status/

    Scope

    voice_build

    Query Parameters

    Parameter Description
    api_key a non-private API key provided by VocaliD (HMAC Only)
    account_id (optional) the id of a previously created user account
    build_id (optional) the id of a previously requested voice build
    status (optional) can be any of the following: PENDING, COMPLETE, ERROR