API Documentation

Getting Started

Voicen provides a secure REST API for developers to convert text to audio in different languages.

In this documentation all methods and objects that returned by this methods are explained in detail for developers to easily use.


Base URL

The base URL of TTS API is:

https://tts.voicen.com/api/v1/

All commands listed below will be executed via this URL.

Errors are returned in JSON format.

Getting access token

To use Voicen API you need access token that you can find on the your account page.

You can also re-generate your token if you need.

In all API request access token is sent like below

-H "Authorization: Token $VOICEN_ACCESS_TOKEN"

Submit a text or text file

An example of submitting an text or text file to Voicen API:

Parameters
Content-type
Header is used to indicate the media type of the resource.
text
String
lang
String (language of text)
file
path to a text file
voice_id
String
Avaliable voice IDs:
  • 325640 - Azerbaijani, female, Aytac
  • 325641 - Azerbaijani, female, Aynur
  • 325642 - Azerbaijani, male, Ramin
  • 325643 - Azerbaijani, male, Elchin
  • 325644 - Turkish, female, Sibel
  • 325645 - Russian, female, Anna

	curl  --header "Content-Type: application/json" \
		  --header "Authorization: Token $VOICEN_ACCESS_TOKEN" \
		  --request POST \
		  --data '{"text":"salam", "lang":"az", "voice_id": "325640"}' \
		  https://tts.voicen.com/api/v1/jobs/text/

					

	curl  --header "Content-type: multipart/form-data" \
		  --header "Authorization: Token $VOICEN_ACCESS_TOKEN" \
		  --request POST \
		  -F lang=az -F voice_id=325640 \
		  -F file=@path/to/myfile.txt \
	       https://tts.voicen.com/api/v1/jobs/file/

					

import requests
import json

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Token $VOICEN_ACCESS_TOKEN',
}

data = '{"text":"salam", "lang":"az", "voice_id": "325640"}'

response = requests.post('https://tts.voicen.com/api/v1/jobs/text/', headers=headers, data=data)

print(json.dumps(response.json(), indent=4, sort_keys=True))

					

import requests
import json

headers = {
	'Authorization': 'Token $VOICEN_ACCESS_TOKEN',
}

files = {
	'lang': (None, 'az'),
	'voice_id': (None, '325640'),
	'file': ('myfile.txt', open('myfile.txt', 'rb')),
}

response = requests.post('https://tts.voicen.com/api/v1/jobs/file/', headers=headers, files=files)

print(json.dumps(response.json(), indent=4, sort_keys=True))

					

$request = curl_init();

curl_setopt($request, CURLOPT_URL, 'https://tts.voicen.com/api/v1/jobs/text/');
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($request, CURLOPT_POST, 1);
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"text\":\"salam\", \"lang\":\"az\", \"voice_id\": \"325640\"}");

$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Token $VOICEN_ACCESS_TOKEN';
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($request);

curl_close($request);

print_r($result);

					

$request = curl_init();

curl_setopt($request, CURLOPT_URL, 'https://tts.voicen.com/api/v1/jobs/file/');
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($request, CURLOPT_POST, 1);
$headers = array();
$headers[] = 'Content-Type: multipart/form-data';
$headers[] = 'Authorization: Token $VOICEN_ACCESS_TOKEN';
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
$cfile = new CURLFile('example.txt');
$data = array(
	'file' => $cfile,
	'lang' => 'az',
	'voice_id' => '325640'
);
curl_setopt($request, CURLOPT_POSTFIELDS, $data);

$result = curl_exec($request);
print_r($result);
	
curl_close($request);
Status Codes
Code Description
200 Success
400 Bad request. Error messsge in a JSON format about errors.
401 Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/
415 Unsupported media type 

{
	"data": {
		"id": 1219,
		"voice_id": 325640,
		"language": "az",
		"character_count": 568,
		"status": "preparing",
		"created": "2020-03-31T11:13:51.942419Z"
	}
}

					

{
	"error": {
		"code": 400,
		"message": "Error message here"
	}
}

					

{
	"error": {
		"code": 401,
		"message": "No valid API key provided."
	}
}

Get list of jobs

You can get all of your jobs list.

Parameters
limit
Integer. Limit number of jobs
offset
Integer. By specifying offset, you retrieve a subset of records starting with the offset value.
curl -X GET "https://tts.voicen.com/api/v1/jobs/?limit=15&offset=0" -H "Authorization: Token $VOICEN_ACCESS_TOKEN"
					

import requests
import json

headers = {
	'Authorization': 'Token $VOICEN_ACCESS_TOKEN',
}

response = requests.get('https://tts.voicen.com/api/v1/jobs/?limit=10&offset=0', headers=headers)

print(json.dumps(response.json(), indent=4, sort_keys=True))

					

$request = curl_init();

curl_setopt_array($request, [
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_URL => 'https://tts.voicen.com/api/v1/jobs/?limit=15&offset=0',
	CURLOPT_HTTPHEADER => array(
		'Authorization: Token $VOICEN_ACCESS_TOKEN'
	)
]);

$result = curl_exec($request);

curl_close($request);

print_r($result);
Status Codes
Code Description
200 Success
400 Bad Request
401 Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ 
{
	"count": 125
	"next": "https://tts.voicen.com/api/v1/jobs/?limit=5&offset=55",
	"previous": "https://tts.voicen.com/api/v1/jobs/?limit=5&offset=45",
	"results": [
		{
			"id": 1219,
			"voice_id": 325640,
			"language": "az",
			"character_count": 1456,
			"status": "preparing",
			"created": "2020-03-31T11:13:51.942419Z",
		},
		...
	]
}

{
	"error": {
		"code": 401,
		"message": "No valid API key provided."
	}
}

					

{
	"error": {
		"code": 400,
		"message": "Error message here"
	}
}

Get synthesize by ID

You can get synthesized audio of your sent text.

Only mp3 format is supported

curl --fail -X GET https://tts.voicen.com/api/v1/jobs/$JOB_ID/synthesize/ -H "Authorization: Token $VOICEN_ACCESS_TOKEN" --output mysynthesize.mp3
				

import requests
import json

headers = {
	'Authorization': 'Token $VOICEN_ACCESS_TOKEN',
}

response = requests.get('https://tts.voicen.com/api/v1/jobs/$JOB_ID/synthesize/', headers=headers)

if response.status_code == 200:
	with open("path/to/destination/mysynthesize.mp3", "wb") as f:
		f.write(response.content)
else:
	print(json.dumps(response.json(), indent=4, sort_keys=True))

				

$request = curl_init();

curl_setopt_array($request, [
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_URL => 'https://tts.voicen.com/api/v1/jobs/$JOB_ID/synthesize/',
	CURLOPT_HTTPHEADER => array(
		'Authorization: Token $VOICEN_ACCESS_TOKEN'
	)
]);

$result = curl_exec($request);
$status_code = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);

if($status_code == 200) {
	file_put_contents("mysynthesize.mp3", $result);
} else {
	print_r($result);
}
Status Codes
Code Description
200 Success.
401 Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/
404 Could not find job for requested ID.
406 Synthesize status is not "ready" 
Synthesize returned successfully.

{
	"error": {
		"code": 401,
		"message": "No valid API key provided."
	}
}

					

{
	"error": {
		"code": 400,
		"message": "Error message here"
	}
}

					

{
	"error": {
		"code": 406,
		"message": "Not acceptable",
		"allowedStatuses" : "ready",
		"currentStatus" : "processing",
	}
}

Get information about job by ID 

curl -X GET https://tts.voicen.com/api/v1/jobs/$JOB_ID/ -H "Authorization: Token $VOICEN_ACCESS_TOKEN"
				

import requests
import json

headers = {
	'Authorization': 'Token $VOICEN_ACCESS_TOKEN',
}

response = requests.get('https://tts.voicen.com/api/v1/jobs/$JOB_ID/', headers=headers)

print(json.dumps(response.json(), indent=4, sort_keys=True))

					

$request = curl_init();

curl_setopt_array($request, [
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_URL => 'https://tts.voicen.com/api/v1/jobs/$JOB_ID/',
	CURLOPT_HTTPHEADER => array(
		'Authorization: Token $VOICEN_ACCESS_TOKEN'
	)
]);

$result = curl_exec($request);
curl_close($request);
print_r($result);

Status can be one of the following:
["waiting", "preparing", "processing", "synthesizing", "ready", "failed"]

Status Codes
Code Description
200 Success
401 Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/
404 Could not find job for requested ID. 

{
	"data": {
		"id": 1219,
		"voice_id": 325640,
		"language": "az",
		"character_count": 568,
		"status": "preparing",
		"created": "2020-03-31T11:13:51.942419Z"
	}
}

					

{
	"error": {
		"code": 401,
		"message": "No valid API key provided."
	}
}

					

{
	"error": {
		"code": 404,
		"message": "ID not found."
	}
}

Delete job by ID

Delete synthesize

All completed job's (status with success or failure) data - text, text files and their synthesizes will be permanently deleted. 

curl -X DELETE https://tts.voicen.com/api/v1/jobs/$JOB_ID/ -H "Authorization: Token $VOICEN_ACCESS_TOKEN"
				

import requests
import json

headers = {
	'Authorization': 'Token $VOICEN_ACCESS_TOKEN',
}

response = requests.delete('https://tts.voicen.com/api/v1/jobs/$JOB_ID/', headers=headers)

print(json.dumps(response.json(), indent=4, sort_keys=True))

					

$request = curl_init();

curl_setopt_array($request, [
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_URL => 'https://tts.voicen.com/api/v1/jobs/$JOB_ID/',
	CURLOPT_CUSTOMREQUEST => 'DELETE',
	CURLOPT_HTTPHEADER => array(
		'Authorization: Token $VOICEN_ACCESS_TOKEN'
	)
]);

$result = curl_exec($request);
curl_close($request);
print_r($result);
Status Codes
Code Description
200 successfully deleted
401 Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/
404 Could not find job for requested ID.
406 Invalid status to delete 
						
{
	"data": {
		"code": 200,
		"deleted": True
	}
}

					

{
	"error": {
		"code": 400,
		"message": "Error message here"
	}
}

					

{
	"error": {
		"code": 401,
		"message": "No valid API key provided."
	}
}

					

{
	"error": {
		"code": 404,
		"message": "ID not found."
	}
}

					

{
	"error": {
		"code": 406,
		"message": "Not acceptable",
		"allowedStatuses" : [ "ready", "failed" ],
		"currentStatus" : "processing",
		"deleted" : False,
	}
}