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, Low Res or P4).
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 using a Hi Res or Low Res voice.

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. Voices with model name of Hi Res or Low Res only.
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.

Personifier 4 Synthesis

endpoint = "/api/v1/external/synthesis/p4/"
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/p4/ \
-d 'download_token=<download_token>' --data-urlencode 'script=This is a sample' -d 'pitch=1' -d 'rate=1'

The above command returns a json response with the rendering id to be used with the Personifier 4 Synthesis Status endpoint.

{
  "status": 200,
  "rendering_id": "5709750f9" 
}

Convert a line of text into speech using a Personifier 4 voice.

HTTP Request

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

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. Voices with model name of P4 only.
script	None	the text to synthesize, default max chars 2800.
pitch	1	pitch modifier. Valid range [0.5, 1.5]. < 1 lowers pitch, > 1 increases pitch.
rate	1	rate modifier. Valid range [0.5, 1.5]. < 1 lowers rate, > 1 increases rate.

Personifier 4 Synthesis Status

endpoint = "/api/v1/external/synthesis/p4/status/"
payload = {"api_key": API_KEY,
           "rendering_id": "5709750f9"
}
sign_and_send(endpoint, method="GET", params=payload)

$ curl -H "Authorization: Bearer <access_token>" \
-G https://vocalid.co/api/v1/external/synthesis/p4/status/ \
-d 'download_token=<download_token>' --data-urlencode 'rendering_id=5709750f9'

The above command returns a json response with the status of the P4 rendering and the resulting wav files url when complete.

{
  "status": "COMPLETE",
  "url": "https://fake.url/to.wav" 
}

Get the status of a Personifier 4 synthesis request.

HTTP Request

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

Scope

voice:synthesis

Query Parameters

Parameter	Default	Description
api_key	None	a non-private API key provided by VocaliD. (HMAC Only)
rendering_id	None	the rendering_id of a previous P4 synthesis request.

Results

Parameter	Description
status	PENDING, ERROR or COMPLETE
url	Url to generated wav file. url parameter only available when status is COMPLETE.

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`