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
- 325648 - Azerbaijani, male, Kamil
- 325647 - Turkish, female, Zeynep
- 325646 - Turkish, male, Mesut
- 325644 - Turkish, female, Sibel
- 325645 - Russian, female, Anna
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);
use error_chain::error_chain;
use reqwest::header::{AUTHORIZATION, CONTENT_TYPE};
use std::io::Read;
error_chain! {
foreign_links {
Io(std::io::Error);
HttpRequest(reqwest::Error);
}
}
fn main() -> Result<()> {
let url = "https://tts.voicen.com/api/v1/jobs/text/";
let api_key = "$VOICEN_ACCESS_TOKEN";
let auth_token = format!("Token {}", api_key);
let data = r#"{"text":"salam", "lang":"az", "voice_id": "325640"}"#;
let client = reqwest::blocking::Client::new();
let mut res = client.post(url)
.header(AUTHORIZATION, auth_token)
.header(CONTENT_TYPE, "application/json")
.body(data)
.send()?;
let mut body = String::new();
res.read_to_string(&mut body)?;
println!("{}", body);
Ok(())
}
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.
$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);
use error_chain::error_chain;
use reqwest::header::AUTHORIZATION;
use std::io::Read;
error_chain! {
foreign_links {
Io(std::io::Error);
HttpRequest(reqwest::Error);
}
}
fn main() -> Result<()> {
let url = "https://tts.voicen.com/api/v1/jobs/?limit=10&offset=0";
let api_key = "$VOICEN_ACCESS_TOKEN";
let auth_token = format!("Token {}", api_key);
let client = reqwest::blocking::Client::new();
let mut res = client.get(url).header(AUTHORIZATION, auth_token).send()?;
let mut body = String::new();
res.read_to_string(&mut body)?;
println!("{}", body);
Ok(())
}
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
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);
}
use error_chain::error_chain;
use reqwest::header::AUTHORIZATION;
use std::fs::File;
use reqwest::StatusCode;
error_chain! {
foreign_links {
Io(std::io::Error);
Reqwest(reqwest::Error);
}
}
fn main() -> Result<()> {
let url = "https://tts.voicen.com/api/v1/jobs/$JOB_ID/synthesize/";
let api_key = "$VOICEN_ACCESS_TOKEN";
let auth_token = format!("Token {}", api_key);
let client = reqwest::blocking::Client::new();
let mut response = client.get(url).header(AUTHORIZATION, auth_token).send()?;
let status = response.status();
if !(status == StatusCode::OK) {
error_chain::bail!("Unexpected server response: {}", status);
}
let mut file = File::create("test.mp3").expect("Unable to create file");
response.copy_to(&mut file)?;
Ok(())
}
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
use error_chain::error_chain;
use reqwest::header::AUTHORIZATION;
use std::io::Read;
error_chain! {
foreign_links {
Io(std::io::Error);
HttpRequest(reqwest::Error);
}
}
fn main() -> Result<()> {
let url = "https://tts.voicen.com/api/v1/jobs/$JOB_ID/";
let api_key = "$VOICEN_ACCESS_TOKEN";
let auth_token = format!("Token {}", api_key);
let client = reqwest::blocking::Client::new();
let mut response = client.get(url).header(AUTHORIZATION, auth_token).send()?;
let mut body = String::new();
response.read_to_string(&mut body)?;
println!("{}", body);
Ok(())
}
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.
$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);
use error_chain::error_chain;
use reqwest::header::AUTHORIZATION;
use std::io::Read;
error_chain! {
foreign_links {
Io(std::io::Error);
HttpRequest(reqwest::Error);
}
}
fn main() -> Result<()> {
let url = "https://tts.voicen.com/api/v1/jobs/$JOB_ID/";
let api_key = "$VOICEN_ACCESS_TOKEN";
let auth_token = format!("Token {}", api_key);
let client = reqwest::blocking::Client::new();
let mut res = client.delete(url).header(AUTHORIZATION, auth_token).send()?;
let mut body = String::new();
res.read_to_string(&mut body)?;
println!("{}", body);
Ok(())
}
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,
}
}