Shell HTTP JavaScript Ruby Python

Replica API

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

We recommend using Postman App to experiment with the API. See the Quick start section below for instructions on how to make requests to our API using Postman and a "Hello world" application.

Usage

Authentication

Users need to have an account in Replica Studios in order to use the API.

/auth endpoint accepts credentials and returns JWT token that can be used for making further calls by supplying it in Authorization header (Bearer token). The token expires in 1 hour (for more details see Auth).

Text to speech

Quick start

For more advanced users, who worked with a REST API before, we recommend jumping straight to Endpoints documentation.

Below you will find a quick walk-through on how to interact with the API, either manually or programmatically.

Make requests using Postman

Postman is the easiest way to get started and try out the API without writing a single line of code. It is a tool that will let you execute requests to the API with a single click of a button and print the responses.

Import request collection

After downloading Postman, import a Collection of pre-configured requests, which is available under this link: https://www.getpostman.com/collections/3c13d3cd89f689c72766.

You can import it by clicking Import button at the top of Postman app window and pasting the link in the Import from link section. The collection should load in the left panel and you should see a list of the possible requests to the API.

Import

Get the access token

First thing you need to do is make a request to Auth endpoint which will provide you the authentication token. This token needs to be attached to all subsequent requests. You will need to provide a pair of credentials (client_id and secret) as params. You should have obtained those from Replica when you signed up for access to the API.

Open the Auth request tab by clicking on the POST auth request from the list. Open the Body section and set the client_id and secret params, be careful not to add any spaces. Then click Send button. If authentication succeeeded, you should see the token value at the bottom (q long string of letters and numbers without spaces in it). Please copy that value. The token will be valid for an hour. To get a new one, just send another request.

Token

Let it speak!

Now, having acquired the access token, we can make requests to any other endpoints. Let's generate some audio from text!

Open the GET speech request tab and go to Authorization section, select TYPE to be Bearer token and paste the token into the input box on the right.

Authorization

Now go to Params section, where you can find the txt param and speaker_id params which let you set what text should be said by which speaker. A list of available speaker ID's (voices) can be obtained by calling the voice endpoint, for now we can just put c4fe46c4-79c0-403e-9318-ffe7bd4247dd there, which is one of our demo speakers, named Deckard.

Params

You are ready now to hit the Send button, wait a second and you should see the response at the bottom. One of the response fields will be a link to wav file which you can download and play.

Congratulations! You should now hear Deckard reading your script.

If something went wrong, have a look at Troubleshooting section.

Make requests programmatically

The Postman walk-through above is a good introduction to the basic flow of using the API to authenticate and generate audio from text. We also provide a simple Python script, which automates all those steps and can illustrate how to use the API programmatically. Feel free to copy it to your application.

The script is publicly accessible as a Gitlab snippet: https://gitlab.com/snippets/1960032

You can also use the Languages panel on the right side of API Endpoints to get useful snippets of code for other languages.

API endpoints

auth

Code samples

# You can also use wget
curl -X POST https://api.replicastudios.com/auth \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=00000000-0000-0000-0000-000000000001' \
  --data-urlencode 'secret=mySecretPassword'

POST https://api.replicastudios.com/auth HTTP/1.1
Host: api.replicastudios.com
Content-Type: application/x-www-form-urlencoded

client_id=00000000-0000-0000-0000-000000000001&secret=mySecretPassword

const inputBody = 'client_id=00000000-0000-0000-0000-000000000001&secret=mySecretPassword';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
};

fetch('https://api.replicastudios.com/auth',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/x-www-form-urlencoded'
}

result = RestClient.post 'https://api.replicastudios.com/auth',
  params: {
  }, headers: headers, body: 'client_id=00000000-0000-0000-0000-000000000001&secret=mySecretPassword'

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
payload = 'client_id=00000000-0000-0000-0000-000000000001&secret=mySecretPassword'

r = requests.post('https://api.replicastudios.com/auth', headers = headers, data = payload)

print(r.json())

POST /auth

Authentication endpoint.

Expects two parameters - client credentials (client_id and secret) encoded as x-www-form-urlencoded in the request body.

Returns a JSON response with JWT token which must be used to make calls to other endpoints. JWT token should be sent as the Authorization: Bearer HTTP header (see examples of calls for other endpoints).

JWT token (jwt.io) is a modern, secure standard for self-contained web access tokens, well suited for stateless REST API's. One of its advantages is that it's not encrypted, but encoded in base64, thus it can be read by both client and server. It includes information about the authenticated client and/or user, permissions and its expiry time. The token is cryptographically signed by our server, hence any tampering with the token will be detected and access will be denied.

We recommend jwt.io site for inspecting the contents of JWT tokens manually. Have a look at our example Python API client to see how to decode and read the token properties programmatically, e.g. check its expiry time.

Note: if your account has used up all credit your token will not authorize you to perform speech generation. This can be checked by decoding the token and verifying if generation permission is present in scopes.

/* sample response */
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1c2VyX2lkIjoiNTg0NmJiMWItYzI2Yy00YTdlLTllYTctMWJmYTc2ZTRkNGNiIiwiZXhwIjoxNTg2MTQ4ODA0LCJpYXQiOjE1ODYxNDcwMDQsInVzZXJfZW1haWwiOiJrYXJvbEByZXBsaWNhc3R1ZGlvcy5jb20iLCJzY29wZXMiOlsiZ2VuZXJhdGUiLCJhZG1pbiJdfQ.YPmwvXC3pU99-t9i9oIA_7wuxE_GjpsJNYn-rFg7KNPUaW8F8QD5laNLdeuZiX9gcF3VvjPVMVX7VTQtrV0nASRa--L5SNBasSVgR59wdwZQpcYOok6Zq0nv0IdTIdiQrkWpKYIsMiVAkJ7EapHO5uSmiUYfueRdGKG2bDaB-qXMOZBZTSZRuoX_1nWStYHwkYuJIz2U1KX167qwCemjEW5O0iTdi1biz7_srw7uAOsFy9YU4QDEKCzLG1OSAYN_APw8_trIqMSJO0Y0S83-CaWorO1zDtOgiAHJW6m_JPaTrg_5xewTWtB5Uji7zjBvhIC9NGcV95CMZqUBgKY1ExJ1ei309Om0QUthxJHIi6FUAYbDSM1UCWXpjAYn6fBQyo4mK-Pfaxqk9GOJVOBOfCrVND_0tyOAGLwe18k0Fl_pLCTIxyPuRQItaeu_S5QPcwqZK_20b1JHVx-siCc5Xv8t6-c9dHE5rWeVdmsgEgAioaTk-ZEnXDizY_vDFn_ZhCgbX-w9_VEQ_LcP9o2lQdGIwkPcVG3HM9WrFChOworQUgUxZiYSQnKnbD2_9BPeQn5hOmN_bPE8lwWoMTJdVJFl9gEV72pA1B-_-NVnTpD9_kENVLYVqilJTCK8UJ_kactbdJweYtVmNIm1R6W8Dmd5t0mYUmOjAmq6MFJpmoo"
}

Parameters

Name In Type Required Description
Content-Type header string true
client_id body string true UUID of the client requesting authentication
secret body string true client's secret

voice

Code samples

# You can also use wget
curl -X GET https://api.replicastudios.com/voice \
  -H 'Authorization: Bearer {token}'

GET https://api.replicastudios.com/voice HTTP/1.1
Host: api.replicastudios.com

Authorization: Bearer {token}


const headers = {
  'Authorization':'Bearer {token}'
};

fetch('https://api.replicastudios.com/voice',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {token}'
}

result = RestClient.get 'https://api.replicastudios.com/voice',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {token}'
}

r = requests.get('https://api.replicastudios.com/voice', headers = headers)

print(r.json())

GET /voice

Endpoint listing all available voices (speakers) for the calling client.

Speakers UUID's are stable i.e. they will not change without notice. You do not need to query this endpoint before making a call to TTS (/speech) endpoint, if you already know your speaker UUID.

Parameters

Name In Type Required Description
Authorization header string true JWT access token

speech

Code samples

# You can also use wget
curl -X GET https://api.replicastudios.com/speech?txt=Please call Stella&speaker_id=c4fe46c4-79c0-403e-9318-ffe7bd4247dd \
  -H 'Authorization: Bearer {token}'

GET https://api.replicastudios.com/speech?txt=Please%20call%20Stella&speaker_id=c4fe46c4-79c0-403e-9318-ffe7bd4247dd HTTP/1.1
Host: api.replicastudios.com

Authorization: Bearer {token}


const headers = {
  'Authorization':'Bearer {token}'
};

fetch('https://api.replicastudios.com/speech?txt=Please call Stella&speaker_id=c4fe46c4-79c0-403e-9318-ffe7bd4247dd',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {token}'
}

result = RestClient.get 'https://api.replicastudios.com/speech',
  params: {
    'txt' => 'Please call Stella',
    'speaker_id' => 'c4fe46c4-79c0-403e-9318-ffe7bd4247dd'
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {token}'
}

r = requests.get('https://api.replicastudios.com/speech', params={
  'txt': 'Please call Stella',  'speaker_id': 'c4fe46c4-79c0-403e-9318-ffe7bd4247dd'
}, headers = headers)

print(r.json())

GET /speech

Text-to-speech (TTS) endpoint.

This endpoint is blocking i.e. it will return a response only once it's ready (see /submit for non blocking calls). It usually takes about 1-3 seconds, depending on the length of text and speaker.

The request should contain the text and speaker ID, response will contain a URL to an audio file with the generated speech. By default the format is wav, which is the fastest (no compression cost).

Note: we advise to apply URL encoding to txt parameter, so any non-alphanumeric characters will be correctly passed to backend, e.g. "Escape those: - ( ) !" should be escaped to "Escape+those%3A+-+%28+%29+%21".

Other optional parameters are extension (audio format), bit_rate and sample_rate to control the output audio properties. Note that not all formats support all possible combinations of bit rate and sample rate, we'll try to return the closest possible.

Note: the returned URL will expire after few days so we do not recommend to store them. They should either be played or downloaded straight away.

/* Sample response */
{
    "uuid": "c1aa11f3-3ec6-4830-b2ac-056740ac5b3a",
    "generation_time": 0.859611988067627,
    "url": "https://dial-s3.s3.amazonaws.com/previews/24000000-0000-0000-0000-000000000000/c1aa11f3-3ec6-4830-b2ac-056740ac5b3a/c1aa11f3-3ec6-4830-b2ac-056740ac5b3a.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIC53N7WR6G7QL5BA/20200415/us-east-1/s3/aws4_request&X-Amz-Date=20200415T230400Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=d497b7a8f44d4e21c5ca3a522323fa4c0995deca95aec2a21aff54216236bc52",
    "duration": 1.2,
    "speaker_id": "c4fe46c4-79c0-403e-9318-ffe7bd4247dd",
    "txt": "Please call Stella",
    "bit_rate": 128,
    "sample_rate": 22050,
    "extension": "mp3"
}

Parameters

Name In Type Required Description
Authorization header string true JWT access token
txt query string true The text to generate
speaker_id query string true Speaker (voice) UUID
extension query string false Output format. Supported: wav (default), mp3, ogg, flac
bit_rate query int false Output bit rate (kbps): 128 (default), 320
sample_rate query int false Output sample rate (Hz). Supported: 1600, 22050 (default), 44100, 48000

speech (long polling)

Code samples

# You can also use wget
curl -X POST https://api.replicastudios.com/speech?speaker_id=c4fe46c4-79c0-403e-9318-ffe7bd4247dd&txt=Please call Stella \
  -H 'Authorization: Bearer {token}'

POST https://api.replicastudios.com/speech?speaker_id=c4fe46c4-79c0-403e-9318-ffe7bd4247dd&txt=Please%20call%20Stella HTTP/1.1
Host: api.replicastudios.com

Authorization: Bearer {token}


const headers = {
  'Authorization':'Bearer {token}'
};

fetch('https://api.replicastudios.com/speech?speaker_id=c4fe46c4-79c0-403e-9318-ffe7bd4247dd&txt=Please call Stella',
{
  method: 'POST',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {token}'
}

result = RestClient.post 'https://api.replicastudios.com/speech',
  params: {
    'speaker_id' => 'c4fe46c4-79c0-403e-9318-ffe7bd4247dd',
    'txt' => 'Please call Stella'
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {token}'
}

r = requests.post('https://api.replicastudios.com/speech', params={
  'speaker_id': 'c4fe46c4-79c0-403e-9318-ffe7bd4247dd', 'txt': 'Please call Stella'
}, headers = headers)

print(r.json())

POST /speech

Non blocking Text-to-speech (TTS) endpoint (note this is a POST request to the same /speech endpoint).

This endpoint is non-blocking i.e. it will return immediately with a JSON response containting UUID of the job. The TTS results need to be fetched by calling /poll endpoint and providing that UUID.

Same parameters are expected as in non-blocking GET /speech above.

Parameters

Name In Type Required Description
Authorization header string true JWT access token
speaker_id query string true speaker (voice) UUID
txt query string true the text to generate

poll (long polling)

Code samples

# You can also use wget
curl -X GET https://api.replicastudios.com/speech/{job_uuid}?timeout=5 \
  -H 'Authorization: Bearer {token}'

GET https://api.replicastudios.com/speech/{job_uuid}?timeout=5 HTTP/1.1
Host: api.replicastudios.com

Authorization: Bearer {token}


const headers = {
  'Authorization':'Bearer {token}'
};

fetch('https://api.replicastudios.com/speech/{job_uuid}?timeout=5',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {token}'
}

result = RestClient.get 'https://api.replicastudios.com/speech/{job_uuid}',
  params: {
    'timeout' => '5'
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {token}'
}

r = requests.get('https://api.replicastudios.com/speech/{job_uuid}', params={
  'timeout': '5'
}, headers = headers)

print(r.json())

GET /speech/{job_uuid}

Endpoint for retrieving results of a job submitted using POST to /speech endpoint.

The job UUID should be supplied as path parameter e.g. /speech/87c0384e-02b0-47d2-a95c-c6b52378000b.

Caller can provide timeout parameter (in seconds) which specifies how long the request should be held before returning, if results are not ready (this is so called "long polling" technique, which reduces the number of calls needed to get the result).

If results are not ready, will return HTTP 404 Not found, meaning that the call needs to be repeated.

As soon as results are ready, will return a response similar to /speech.

Parameters

Name In Type Required Description
Authorization header string true JWT token
job UUID path string true UUID of the job e.g. 87c0384e-02b0-47d2-a95c-c6b52378000b
timeout query integer false time (in seconds) to keep request alive if result not ready

Troubleshooting

Incorrect request parameters will result in 400 Bad Request response.

There is a limit of 2000 characters per request. For longer texts, please split them into multiple requests.

If you run out of free quota, you will not be able to make any more requests to TTS API. Please contact Replica Studios to purchase more.

Failed speech generation will result in JSON response containing the error code and textual description.

Partial success will yield a result with the warning field populated.

Help and feedback

You can contact us for further assistance or report bugs.

We would love to hear your feedback.