Phonexia Speech Engine API Documentation version: 3.63.1

POST /admin/user create new user

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/admin/user?login=james"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$LOGIN = "james";  //= user's login

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/user?login=$LOGIN",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "UserResult", "user": { "login": "james", "active": true, "roles": [ "user", "admin" ] } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>UserResult</name> <user> <login>james</login> <active>true</active> <roles> <item>user</item> <item>admin</item> </roles> </user> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden
404Not Found	1020User does not exist

Create new user. Body of request has to contain user's data. It is possible to set the Content-Type parameter in the request header which is helpful in case the client wants to send input data in XML format. Access to this method is allowed only for users with "admin" role.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content.
login	json/xml content	string	yes	new user's login
password	json/xml content	string	yes	new user's password
active	json/xml content	boolean	no	new user's active status
roles	json/xml content	list of strings	no	new user's roles

Body

{
  "user": {
    "login": "james",
    "password": "password1234",
    "active": true,
    "roles": [
      "user",
      "admin"
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <login>james</login>
  <password>password1234</password>
  <active>true</active>
  <roles>
    <item>user</item>
    <item>admin</item>
  </roles>
</user>

Example

DELETE /admin/user Delete user from server

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"new_user.json" "SERVER_ADDRESS:PORT/admin/user"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$user_data = array(
  'user' =>
  array (
    'login'    => 'james',
    'password' => 'password1234',
    'active'   => true,
    'roles'    =>
    array (
      'user',
      'admin'
    )
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($user_data),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/user",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI 1021User already exists 1025An invalid value was specified for one of the header parameters in the request 1019An invalid data was specified in the request content
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

Delete user from server. All user's data (all recordings, results, settings) will be deleted. Access to this method is allowed only for users with "admin" role.

Parameters

Name	Parameter Type	Data Type	Required	Description
login	query	string	yes	selected user's login

Body

empty content

Example

PUT /admin/user change user settings

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/admin/user?login=james"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$LOGIN = "james";  //= user's login

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/user?login=$LOGIN",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden
404Not Found	1020User does not exist

Resource locker

CHECK All user's Files
CHECK All user's Speaker models
CHECK All user's Speaker groups
CHECK All user's Calibration sets
CHECK All user's Keyword lists
CHECK All user's Audio Source Profiles

Change user settings. Body of request contains changed user's settings. It is possible to set the Content-Type parameter in the request header which is helpful in case the client wants to send input data in XML format. Currently, it is not possible to change user's login. Access to this method is allowed only for users with "admin" role.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content.
login	query	string	yes	selected user's login
login	json/xml content	string	yes	user's login - currently, it is not possible to change it
password	json/xml content	string	no	changed password
active	json/xml content	boolean	no	changed active status
roles	json/xml content	list of strings	no	changed roles

Body

{
  "user": {
    "login": "james",
    "password": "newpassword",
    "active": true,
    "roles": [
      "user",
      "admin"
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <login>james</login>
  <password>newpassword</password>
  <active>true</active>
  <roles>
    <item>user</item>
    <item>admin</item>
  </roles>
</user>

Example

/admin/users – returns list of all users

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X PUT --data-binary @"new_user.json" "SERVER_ADDRESS:PORT/admin/user?login=james"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$LOGIN = "james";  //= user's login

$user_data = array(
  'user' =>
  array (
    'login'    => $LOGIN,
    'password' => 'newpassword',
    'active'   => true,
    'roles'    =>
    array (
      'user',
    )
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'PUT',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($user_data),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/user?login=$LOGIN",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1025An invalid value was specified for one of the header parameters in the request
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden
404Not Found	1020User does not exist

GET /admin/users list of all users

Returns list of all users. Access to this method is allowed only for users with "admin" role.

Body

empty content

Example

/admin/roles – list of user roles

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/admin/users?format=xml"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/users",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AdminUsersResult", "users": [ { "login": "george", "active": true, "roles": [ "user", "admin" ] }, { "login": "john", "active": true, "roles": [ "user" ] } ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>AdminUsersResult</name> <users> <item> <login>george</login> <active>true</active> <roles> <item>user</item> <item>admin</item> </roles> </item> <item> <login>john</login> <active>true</active> <roles> <item>user</item> </roles> </item> </users> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

GET /admin/roles Information about user roles

Returns list of all user roles. Access to this method is allowed only for users with "admin" role.

Body

empty content

Example

/admin/licenses – list of licenses

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/admin/roles"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/roles",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "RolesResult", "roles": [ "admin", "user" ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>RolesResult</name> <roles> <item>admin</item> <item>user</item> </roles> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

GET /admin/licenses Information about licenses

For each technology returns total count of licenses, used licenses and hours to expire. Access to this method is allowed only for users with "admin" role.

Body

empty content

Example

/doc – SPE's API documentation

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/admin/licenses"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/admin/licenses",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "LicensesResult", "licenses": [ { "technology_name": "Server", "technology_abbreviation": "SERVER", "model_name": "", "license": { "hours_to_expire": 6483, "n_licenses": 16, "n_used_licenses": 2 } }, { "technology_name": "Diarization", "technology_abbreviation": "DIAR", "model_name": "S", "license": { "hours_to_expire": 6483, "n_licenses": 16, "n_used_licenses": 2 } }, ... ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>LicensesResult</name> <licenses> <item> <technology_name>Server</technology_name> <technology_abbreviation>SERVER</technology_abbreviation> <model_name/> <license> <hours_to_expire>6483</hours_to_expire> <n_licenses>16</n_licenses> <n_used_licenses>2</n_used_licenses> </license> </item> <item> <technology_name>Diarization</technology_name> <technology_abbreviation>DIAR</technology_abbreviation> <model_name>S</model_name> <license> <hours_to_expire>6483</hours_to_expire> <n_licenses>16</n_licenses> <n_used_licenses>2</n_used_licenses> </license> </item> ... </licenses> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

Basic Operations

GET /doc API documentation

Returns API documentation in HTML. This endpoint doesn't require authentication.

Body

empty content

Example

/login – user authentication

curl -X GET "SERVER_ADDRESS:PORT/doc"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/doc",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	HTML document
404Not Found	1008File not found

POST /login Login user

Allows user to login with user's name and password. If user is successfully logged in, response contains session id. Given session id is necessary to use in other request headers (parameter X-SessionID). For more information, see Authentication chapter.

Body

empty content

Example

/directory – storage directory manipulation

curl -u "LOGIN:PASSWORD" -X POST "SERVER_ADDRESS:PORT/login"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$ENCODE_CREDENTIALS = base64_encode("username:password");

$options = array(
'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'Authorization: Basic ' . $ENCODE_CREDENTIALS,
    'ignore_errors'  => true,
  )
);
$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/login",
  false,
  $context
);
$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserSessionResult", "session": { "id": "258f505c-a6fa-4c3f-8a87-b048874ac6aa" } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>UserSessionResult</name> <session> <id>258f505c-a6fa-4c3f-8a87-b048874ac6aa</id> </session> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1013Unsupported

GET /directory List of items in the directory

Returns the list of items in the directory.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Path to the server directory.
show_unregistered	query	boolean	no	If `true`, output will contain unregistered files. Default value is `false`.

Body

empty content

Example

POST /directory Create the directory

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/directory?path=/DIRECTORY_PATH"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/";  //= path to the server directory

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/directory?path=$PATH",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "DirectoryResult", "list": [ { "name": "julia.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true }, { "name": "david.wav", "last_modified": "2015-08-03T11:32:41Z", "created": "2015-08-03T11:32:41Z", "size": 492204, "is_directory": false, "is_registered": true }, { "name": "test", "last_modified": "2015-07-29T14:20:38Z", "created": "2015-08-03T01:18:01Z", "size": 0, "is_directory": true, "is_registered": true } ] } } <?xml version="1.0"?> <result> <version>2</version> <name>DirectoryResult</name> <list> <item> <name>julia.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> </item> <item> <name>david.wav</name> <last_modified>2015-08-03T11:32:41Z</last_modified> <created>2015-08-03T11:32:41Z</created> <size>492204</size> <is_directory>false</is_directory> <is_registered>true</is_registered> </item> <item> <name>test</name> <last_modified>2015-07-29T14:20:38Z</last_modified> <created>2015-08-03T01:18:01Z</created> <size>0</size> <is_directory>true</is_directory> <is_registered>false</is_registered> </item> </list> </result>
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Create directory in current user's storage. All the required parent directories are created.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Path to the server directory.

Body

empty content

Example

DELETE /directory Delete the directory

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/directory?path=/DIRECTORY_PATH"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/my_directory";  //= path to the server directory

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/directory?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication

Delete the directory from the current user's storage. All files and sub-directories will be deleted.

If results from technologies are in the cache, all results assigned to deleted files will be deleted, too.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Path to the server directory.

Body

empty content

Example

/audiofile – audio file manipulation

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/directory?path=/DIRECTORY_PATH"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/my_directory";  //= path to the server directory

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/directory?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Resource locker

CHECK All files in the directory and sub-directories

GET /audiofile Download audio file from server

Download audio file from server.

See also Usage examples - Audio file manipulation for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file

Body

empty content

Example

POST /audiofile Upload audio file to server

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/audiofile?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the Phonexia Speech Engine

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile?path=$PATH",
  false,
  $context
);

file_put_contents('./audio.wav', $response); //= audio file saved on the PHP server
?>

Available responses

HTTP Status	Output
200OK	AUDIO DATA
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Upload audio file to the current user's storage. The request body contains audio file data.

If a file with the same name already exists on the server, it will be overwritten with uploaded file (if results from technologies are in the cache, all results assigned to overwritten file will be deleted).

By default server allows uploading files with unlimited size. This behavior can be changed in server configuration file by setting server.upload_max_filesize.

Server supports following encodings:

WAVE (*.wav) container including any of:
- signed 8-bit PCM (s8)
- signed 16-bit PCM (s16le)
- IEEE float 32-bit (f32le)
- A-law (alaw)
- µ-law (mulaw)
- ADPCM
FLAC codec inside FLAC (*.flac) container
OPUS codec inside OGG (*.opus) container
other audio formats can be used only if audio converter is enabled and if audio converter supports specific format

Audio converter always convert audio file to WAVE format and change file's extension to ".wav". Server checks if file has proper extension and is able to change it (for example uploaded OPUS audio file with requested name julia.ogg will be saved as julia.opus). If server change extension file and file with changed extension already exists, operation will be aborted and error with code 1039 will be returned.

See also Usage examples - Audio file manipulation for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file

Body

BINARY AUDIO DATA

Example

DELETE /audiofile Delete file from server

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST --data-binary @"FILE_PATH" "SERVER_ADDRESS:PORT/audiofile?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= destination path to the audiofile on the Phonexia Speech Engine

$audio = file_get_contents("./audio.wav"); //= path to the source file on the PHP server

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: audio/wav',
    'content'       => $audio,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile?path=$PATH",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI 1039It was necessary to rename uploaded file but it could not be done, because file with same name already exists 1038Resource is locked
401Unauthorized	1005The request requires user authentication
403Forbidden	1063Access to file is forbidden
413Request Entity Too Large	1014Size of uploaded file exceeds size limit
415Unsupported Media Type	1007Unsupported audio format

Resource locker

CHECK Target file (specified by parameter path)

Delete the audio file from current user's storage. If results from technologies are in the cache, all results assigned to deleted file will be deleted.

See also Usage examples - Audio file manipulation for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.

Body

empty content

Example

PUT /audiofile Move or copy audio file.

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/audiofile?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the Phonexia Speech Engine

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Resource locker

CHECK Target file (specified by parameter path)

Move or copy audio file.

This request supports extended possibility for path addressing. In path and new_path can be addressed file in storage, speaker model or calibration set. Paths addressing files in speaker model or calibration set have to start with symbol @. Speaker model or calibration will be created if necessary.

Example path to audio file in user's storage:

path=/my_directory/audio.wav

Example path to audio file stored in Speaker Model:

path=@speakerid/speakermodels/{SPEAKER_MODEL_NAME}/{RECORDING_NAME}

path=@speakerid4/speakermodels/{SPEAKER_MODEL_NAME}/{RECORDING_NAME}

Due to sharing speaker models between SID and SID4, both paths are equivalent.

Example path to audio file stored in Calibration Set:

path=@speakerid/calibsets/{CALIBRATION_SET_NAME}/{RECORDING_NAME}

See also Usage examples - Audio file manipulation for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Source audio file path.
new_path	query	string	yes	Target audio file path.
copy	query	string	no	When true, file is copied instead of moving. Default value is false.

Body

empty content

Example

/audiofile/metainfo – audiofile's metainfo manipulation

curl -H "X-SessionID:YOUR_SESSION_ID" -X PUT "SERVER_ADDRESS:PORT/audiofile?path=/AUDIO_FILE.wav&new_path=/NEW/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";         //= path to the original audio file on the Phonexia Speech Engine
$NEW_PATH = "/NEW/AUDIO_FILE.wav"; //= new path of audio file on the Phonexia Speech Engine
$COPY = "false";                   //= "true" for copying, "false" for moving

$options = array(
  'http' =>
  array (
    'method'        => 'PUT',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile?path=$PATH&new_path=$NEW_PATH&copy=$COPY",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
415Unsupported Media Type	1007Unsupported audio format

Resource locker

CHECK Source file (specified by parameter path) - when moving (parameter copy=false)
CHECK Target file (specified by parameter new_path) - if overwriting existing file
CHECK Speaker model - when moving from file from speaker model (path points to speaker model and parameter copy=false)
CHECK Speaker model - if target file is in speaker model (new_path points to speaker model)
CHECK Calibration set - when moving from file from calibration set (path points to calibration set and parameter copy=false)
CHECK Calibration set - if target file is in calibration set (new_path points to calibration set)

GET /audiofile/metainfo Get meta-information

Get audio file's meta-information

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file

Body

empty content

Example

POST /audiofile/metainfo Set meta-information

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/audiofile/metainfo?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the Phonexia Speech Engine

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create($options);
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile/metainfo?path=$PATH",
  false,
  $context
);

var_dump($response);
?>

Available responses

HTTP Status	Output
200OK	META DATA
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Set meta-information to exist audio file in current user's storage. The request body contains custom data. If file already contains meta-information it will be overwritten with new meta-information

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file

Body

BINARY META DATA

Example

DELETE /audiofile/metainfo Delete meta-information

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST --data-binary @"FILE_PATH" "SERVER_ADDRESS:PORT/audiofile/metainfo?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= destination path to the audiofile on the Phonexia Speech Engine

$content = "custom meta data";

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'content'       => $content,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create($options);
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile/metainfo?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
413Request Entity Too Large	1014Size of uploaded file exceeds size limit

Delete meta-information of audio file from current user's storage.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.

Body

empty content

Example

/audiofile/info – information about audio file

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/audiofile/metainfo?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the Phonexia Speech Engine

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile/metainfo?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

GET /audiofile/info Information about audio file

Returns information about audio file (such as frequency, length, number of channels)

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.

Body

empty content

Example

/audiofile/registration – audiofile's registration to system

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/audiofile/info?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the server

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile/info?path=$PATH",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1003A required query parameter was not specified for this request
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
415Unsupported Media Type	1007Unsupported audio format

POST /audiofile/registration Register audio file to system.

This function registers file to system. It is useful if file wasn't uploaded via API (request POST /audiofile), for example file was copied to file system.

The file has to be in server storage folder (typically in {SERVER_PATH}/home/{USER_NAME}/storage).

By default server allows registering files with unlimited size. This behavior can be changed in server configuration file by setting server.upload_max_filesize.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Path to audio file on server.

Body

empty content

Example

DELETE /audiofile/registration Unregister audio file from system.

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/audiofile/registration?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the server

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile/registration?path=$PATH",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1003A required query parameter was not specified for this request
401Unauthorized	1005The request requires user authentication
403Forbidden	1063Access to file is forbidden
404Not Found	1008File not found
413Request Entity Too Large	1059Size of registered file exceeds size limit
415Unsupported Media Type	1007Unsupported audio format

This function unregister file from system. All associated data are removed (results, meta information etc.), but file itself stays in filesystem.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.

Body

empty content

Example

/loadstatistics – information about server load statistics

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/audiofile/registration?path=/AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the server

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/audiofile/registration?path=$PATH",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1003A required query parameter was not specified for this request 1038Resource is locked
401Unauthorized	1005The request requires user authentication

Resource locker

CHECK File - file can not be unregistered when is locked

GET /loadstatistics Information about server load

Returns information about server load statistics.

Result parameters description:

`task_queue_count`	count of tasks currently waiting in queue
`task_queue_maximum`	task queue size
`streamed_task_running`	actual count of tasks processing stream
`streamed_task_maximum`	maximum of simultaneous tasks processing stream
`worker_running`	actual count of used workers
`worker_count`	count of initialized workers
`http_input_stream_running`	actual count of opened input HTTP streams
`websocket_input_stream_running`	actual count of opened input WebSocket streams
`rtp_input_stream_running`	actual count of opened input RTP streams
`rtp_input_stream_maximum`	maximum count of opened input RTP streams
`rtp_output_stream_running`	actual count of opened output RTP streams

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/loadstatistics"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/loadstatistics",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 4, "name": "LoadStatisticResult", "load_statistics": { "task_queue_count": 0, "task_queue_maximum": 1000, "streamed_task_running": 0, "streamed_task_maximum": 5, "worker_running": 1, "worker_count": 10, "http_input_stream_running": 0, "websocket_input_stream_running": 0, "rtp_input_stream_running": 0, "rtp_input_stream_maximum": 10, "rtp_output_stream_running": 1 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>4</version> <name>LoadStatisticResult</name> <load_statistics> <task_queue_count>0</task_queue_count> <task_queue_maximum>1000</task_queue_maximum> <streamed_task_running>0</streamed_task_running> <streamed_task_maximum>5</streamed_task_maximum> <worker_running>1</worker_running> <worker_count>10</worker_count> <http_input_stream_running>0</http_input_stream_running> <websocket_input_stream_running>0</websocket_input_stream_running> <rtp_input_stream_running>0</rtp_input_stream_running> <rtp_input_stream_maximum>10</rtp_input_stream_maximum> <rtp_output_stream_running>1</rtp_output_stream_running> </load_statistics> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication

HTTP Status

Output

200OK

/pending/{id} – information about asynchronous request

{
  "result": {
    "version": 4,
    "name": "LoadStatisticResult",
    "load_statistics": {
      "task_queue_count": 0,
      "task_queue_maximum": 1000,
      "streamed_task_running": 0,
      "streamed_task_maximum": 5,
      "worker_running": 1,
      "worker_count": 10,
      "http_input_stream_running": 0,
      "websocket_input_stream_running": 0,
      "rtp_input_stream_running": 0,
      "rtp_input_stream_maximum": 10,
      "rtp_output_stream_running": 1
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>4</version>
  <name>LoadStatisticResult</name>
  <load_statistics>
    <task_queue_count>0</task_queue_count>
    <task_queue_maximum>1000</task_queue_maximum>
    <streamed_task_running>0</streamed_task_running>
    <streamed_task_maximum>5</streamed_task_maximum>
    <worker_running>1</worker_running>
    <worker_count>10</worker_count>
    <http_input_stream_running>0</http_input_stream_running>
    <websocket_input_stream_running>0</websocket_input_stream_running>
    <rtp_input_stream_running>0</rtp_input_stream_running>
    <rtp_input_stream_maximum>10</rtp_input_stream_maximum>
    <rtp_output_stream_running>1</rtp_output_stream_running>
  </load_statistics>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

401Unauthorized

1005The request requires user authentication

GET /pending/{id} Information about asynchronous request

Returns information about asynchronous request with the specified asynchronous request id. When operation is done, 303 returns status is used and HTTP header contains address for final result in "Location" parameter. For more information about asynchronous requests, see Asynchronous request.

WebSocket

This request can be used for opening WebSocket. In this case header of request should contain WebSocket handshake parameters (Upgrade, Connection, Sec-WebSocket-Version, Sec-WebSocket-Key). Header must also contain session parameter (X-SessionID) or basic authorization (Authorization). Supported Sec-WebSocket-Version is 13. When asynchronous operation finishes, result is sent through WebSocket's message and WebSocket is closed. Only one WebSocket can be opened for one asynchronous operation.

Example header for create WebSocket:

 GET /pending/ec563083-3d9b-457d-a0ac-24b197bc222f HTTP/1.1
 Host: server.example.com
 Upgrade: websocket
 Connection: Upgrade
 Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
 Sec-WebSocket-Version: 13
 X-SessionID: 258f505c-a6fa-4c3f-8a87-b048874ac6aa
 Accept: application/json

Parameters

Name	Parameter Type	Data Type	Required	Description
id	path	string	yes	Determines the asynchronous request ID.

Body

empty content

Example

DELETE /pending/{id} Remove asynchronous request

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/pending/ASYNCHRONOUS_REQUEST_ID"

/* See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example */

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "PendingInfoResult", "info": { "id": "ec563083-3d9b-457d-a0ac-24b197bc222f", "state": "waiting", "priority": 50 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>2</version> <name>PendingInfoResult</name> <info> <id>a869ea70-980a-4497-99b4-3ef181f0b87d</id> <state>waiting</state> <priority>50</priority> </info> </result>
303See Other	JSON XML { "result": { "version": 2, "name": "PendingInfoResult", "info": { "id": "ec563083-3d9b-457d-a0ac-24b197bc222f", "state": "finished", "priority": 50 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>2</version> <name>PendingInfoResult</name> <info> <id>ec563083-3d9b-457d-a0ac-24b197bc222f</id> <state>finished</state> <priority>50</priority> </info> </result>
400Bad Request	1042WebSocket has already been opened for this operation 1043Can't create WebSocket
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found

Remove asynchronous request with the specified asynchronous request id. Requests can be removed only while they are in waiting state, i.e. while they are still waiting in a queue for being processed. Once the task processing starts, i.e. the task gets into running state, the processing cannot be cancelled and the task is always processed. See also Asynchronous request for more details about task states.

Parameters

Name	Parameter Type	Data Type	Required	Description
id	path	string	yes	Determines the asynchronous request ID.

Body

empty content

Example

/done/{id} – result of finished pending request

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/pending/ASYNCHRONOUS_REQUEST_ID"

/* See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example */

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found

GET /done/{id} Information about asynchronous request

Returns result of asynchronous request with the specified asynchronous request id. For more information about asynchronous requests, see Asynchronous request.

Parameters

Name	Parameter Type	Data Type	Required	Description
id	path	string	yes	Determines the asynchronous request ID.

Body

empty content

Example

/tasks – Information about current tasks

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/done/ASYNCHRONOUS_REQUEST_ID"

/* See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example */

Available responses

HTTP Status	Output
200OK	Variable output Contains response of done asynchronous request. For example, this response will contain `VoiceActivityDetectionResult` after processing `GET /technologies/vad`. See response output of specific asynchronous request for more details.
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found

GET /tasks Information about current tasks

Return information about all registered tasks. Finished tasks are removed after a client pick it up or after timeout period.

This request does not require user authentication.

Body

empty content

Example

curl -X GET "SERVER_ADDRESS:PORT/tasks"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/tasks",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "TasksResult", "tasks": [ { "id": "964b2969-396c-4e1c-b139-0ee1024bbab1", "state": "running", "priority": 50 }, { "id": "857d3674-045c-5a7b-b248-5ca9644dfab1", "state": "finished", "priority": 27 }, ... ] } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>2</version> <name>TasksResult</name> <tasks> <item> <id>964b2969-396c-4e1c-b139-0ee1024bbab1</id> <state>running</state> <priority>50</priority> </item> <item> <id>857d3674-045c-5a7b-b248-5ca9644dfab1</id> <state>finished</state> <priority>27</priority> </item> </tasks> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI

HTTP Status

Output

200OK

/technologies – list of the server supported technologies

{
  "result": {
    "version": 2,
    "name": "TasksResult",
    "tasks": [
      {
        "id": "964b2969-396c-4e1c-b139-0ee1024bbab1",
        "state": "running",
        "priority": 50
      },
      {
        "id": "857d3674-045c-5a7b-b248-5ca9644dfab1",
        "state": "finished",
        "priority": 27
      },
      ...
    ]
  }
}

<?xml version='1.0' encoding='UTF-8'?>
<result>
  <version>2</version>
  <name>TasksResult</name>
  <tasks>
    <item>
      <id>964b2969-396c-4e1c-b139-0ee1024bbab1</id>
      <state>running</state>
      <priority>50</priority>
    </item>
    <item>
      <id>857d3674-045c-5a7b-b248-5ca9644dfab1</id>
      <state>finished</state>
      <priority>27</priority>
    </item>
  </tasks>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

GET /technologies List technologies and models

List currently running technologies and returns a list of their respective models.

If the show_all parameter is set to true all available technologies will be listed.

This request does not require user authentication.

Parameters

Name	Parameter Type	Data Type	Required	Description
show_all	query	boolean	no	If `true`, the output will include disabled models (these models will have `n_total_instances` equal to zero). Default value is `false`.

Body

empty content

Example

curl -X GET "SERVER_ADDRESS:PORT/technologies"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;

$options = array(
  'http' =>
  array (
    'method'         => 'GET',
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

POST /technologies Configure technologies

{
  "result": {
    "version": 4,
    "name": "TechnologiesResult",
    "technologies": [
      {
        "name": "Age Estimation",
        "abbreviation": "AGE",
        "is_capacity_exceeded": false,
        "models": [
          {
            "name": "S",
            "version": "1.2.1",
            "n_total_instancies": 3,
            "n_busy_instancies": 0
          }
        ]
      },
      {
        "name": "Diarization",
        "abbreviation": "DIAR",
        "is_capacity_exceeded": true,
        "models": [
          {
            "name": "L",
            "version": "1.0.2",
            "n_total_instancies": 3,
            "n_busy_instancies": 0
          }
        ]
      },
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>4</version>
  <name>TechnologiesResult</name>
  <technologies>
    <item>
      <name>Age Estimation</name>
      <abbreviation>AGE</abbreviation>
      <is_capacity_exceeded>false</is_capacity_exceeded>
      <models>
        <item>
          <name>S</name>
          <version>1.2.1</version>
          <n_total_instancies>3</n_total_instancies>
          <n_busy_instancies>0</n_busy_instancies>
        </item>
      </models>
    </item>
    <item>
      <name>Diarization</name>
      <abbreviation>DIAR</abbreviation>
      <is_capacity_exceeded>true</is_capacity_exceeded>
      <models>
        <item>
          <name>L</name>
          <version>1.0.2</version>
          <n_total_instancies>3</n_total_instancies>
          <n_busy_instancies>0</n_busy_instancies>
        </item>
      </models>
    </item>
    ...
  </technologies>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

400Bad Request

1073An uknown parameter was submitted

This endpoint is used to configure technologies and their models running on the server. Only users with the admin role can access this endpoint.
Changes made through this endpoint require a server restart to take effect (use POST /server/restart endpoint).

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content.

Body

{
   "technologies": [
     {
       "abbreviation": "VAD",
       "models": [
         {
           "name": "GENERIC_3",
           "n_total_instancies": 3
         },
         {
           "name": "GENERIC",
           "n_total_instancies": 1
         }
       ]
     },
     {
       "abbreviation": "GID",
       "models": [
         {
           "name": "XL5",
           "n_total_instancies": 3
         }
       ]
     }
   ]
 }

<?xml version="1.0" encoding="UTF-8"?>
<technologies>
  <item>
    <abbreviation>VAD</abbreviation>
    <models>
      <item>
        <name>GENERIC_3</name>
        <n_total_instancies>3</n_total_instancies>
      </item>
      <item>
        <name>GENERIC</name>
        <n_total_instancies>1</n_total_instancies>
      </item>
    </models>
  </item>
  <item>
    <abbreviation>GID</abbreviation>
    <models>
      <item>
        <name>XL5</name>
        <n_total_instancies>3</n_total_instancies>
      </item>
    </models>
  </item>
</technologies>

technologies[]->abbreviation	Abbreviation of the technology. Server will validate if technology is present on the server.
technologies[]->models[]->name	Name of the model. Server will validate if this name is a valid model name for the associated technology.
technologies[]->models[]->n_total_instancies	Number of instances of this model to run. Must be greater than 0.

Example

GET /user information about current user

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"technologies.json" "SERVER_ADDRESS:PORT/technologies"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$user_data = array(
  'technologies' =>
  array (
    (object) [
      'abbreviation' => 'VAD',
      'models' =>
      array (
        (object) [
          'name'               => 'GENERIC_3',
          'n_total_instancies' => 3
        ],
        (object) [
          'name'               => 'GENERIC',
          'n_total_instancies' => 1
        ]
      )
    ],
    (object) [
      'abbreviation' => 'gid',
      'models' =>
      array (
        (object) [
          'name'               => 'XL5',
          'n_total_instancies' => 3
        ]
      )
    ]
  )
);
$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($user_data),
    'ignore_errors' => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1025An invalid value was specified for one of the header parameters in the request
400Bad Request	1019An invalid data was specified in the request content
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

/user – user information

Returns information about current user.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/user"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/user",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

PUT /user Change password.

{
  "result": {
    "version": 3,
    "name": "UserResult",
    "user": {
      "login": "james",
      "active": true,
      "roles": [
        "user",
        "admin"
      ]
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>3</version>
  <name>UserResult</name>
  <user>
    <login>james</login>
    <active>true</active>
    <roles>
      <item>user</item>
      <item>admin</item>
    </roles>
  </user>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

401Unauthorized

1005The request requires user authentication

Allows changing user password.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content.
password	json/xml content	string	yes	changed password

Body

{
  "user": {
    "password": "newpassword"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <password>newpassword</password>
</user>

Example

GET /status Server status

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X PUT --data-binary @"user_changes.json" "SERVER_ADDRESS:PORT/user"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$LOGIN = "james";  //= user's login

$user_data = array(
  'user_changes' =>
   array (
    'password' => 'newpassword'
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'PUT',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($user_data),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/user",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1025An invalid value was specified for one of the header parameters in the request
401Unauthorized	1005The request requires user authentication
404Not Found	1020User does not exist

/status – server status

Returns server status. This method does not require user authentication.

Body

empty content

Example

curl -X GET "SERVER_ADDRESS:PORT/status"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/status",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

{
  "result": {
    "version": 2,
    "name": "StatusResult",
    "database": "ok",
    "licenses": "ok",
    "internal_services": "ok",
    "reporting_service": "ok"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>StatusResult</name>
  <database>ok</database>
  <licenses>ok</licenses>
  <internal_services>ok</internal_services>
  <reporting_service>ok</reporting_service>
</result>

500Internal Server Error

/server/info – information about the server

{
  "result": {
    "version": 2,
    "name": "StatusResult",
    "database": "failed",
    "licenses": "failed",
    "internal_services": "failed",
    "reporting_service": "failed"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>StatusResult</name>
  <database>failed</database>
  <licenses>failed</licenses>
  <internal_services>failed</internal_services>
  <reporting_service>failed</reporting_service>
</result>

GET /server/info Information about the server

Returns information about the server

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/server/info"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/server/info",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

/server/restart – restart server

{
  "result": {
    "version": 6,
    "name": "ServerInfoResult",
    "info": {
      "version": "3.30.1",
      "build_number": "1597",
      "bsapi_version": "Phonexia s.r.o., build Apr  9 2020, 14:30:51, v3.30.1",
      "audio_converter_enabled": true,
      "maximum_upload_file_size": 0,
      "maximum_upload_meta_file_size": 0,
      "rtp_streams_enabled": true,
      "http_streams_enabled": true,
      "websocket_streams_enabled": true,
      "task_priorities_enabled": true,
      "default_task_priority": 50
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>6</version>
  <name>ServerInfoResult</name>
  <info>
    <version>3.30.1</version>
    <build_number>1597</build_number>
    <bsapi_version>Phonexia s.r.o., build Apr  9 2020, 14:30:51, v3.30.1</bsapi_version>
    <audio_converter_enabled>true</audio_converter_enabled>
    <maximum_upload_file_size>0</maximum_upload_file_size>
    <maximum_upload_meta_file_size>0</maximum_upload_meta_file_size>
    <rtp_streams_enabled>true</rtp_streams_enabled>
    <http_streams_enabled>true</http_streams_enabled>
    <websocket_streams_enabled>true</websocket_streams_enabled>
    <task_priorities_enabled>true</task_priorities_enabled>
    <default_task_priority>50</default_task_priority>
  </info>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

401Unauthorized

1005The request requires user authentication

POST /server/restart restarts the server

Restarts the server. Only users with the admin role can access this endpoint.
This request will fail if a task is running on the server. Use GET /tasks to get information about running tasks.

Note: While the server is restarting, any request to the server will fail. Use e.g. GET /status and/or GET /server/info to check the server readiness.
Caution: If some configuration has been inappropriately changed before restarting, the server may fail to start.

Note 2: Not recommended to use when Speech Engine is running on Windows as a service. Restarting the server this way creates a completely new process on Windows, out of the service context, and therefore cannot be managed as a service anymore (i.e. does not respond to stopping/restarting the service).

Body

empty content

Example

/server/shutdown – shutdown server

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/server/restart"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/server/restart",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1074Not available while a task is still running
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

POST /server/shutdown shutdown the server

Shuts down the server. Only users with the admin role can access this endpoint.
This request will fail if a task is running on the server. Use GET /tasks to get information about running tasks.

Caution: Use wisely, as you may not be able to start the server again (especially with remote servers).

Body

empty content

Example

/input_stream/rtp – Input RTP stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/server/shutdown"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/server/shutdown",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1074Not available while a task is still running
401Unauthorized	1005The request requires user authentication
403Forbidden	1011Execute access forbidden

Stream

POST /input_stream/rtp Open input RTP stream

Opens input RTP stream. Stream is opened on port, which is returned in result.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	no	Path to file where streamed data will be saved. If path is not set file will not be saved. File will be overwritten if already exists.

Body

empty content

Example

DELETE /input_stream/rtp Close opened input RTP stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/input_stream/rtp"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "RtpInputStreamResult", "port": "5000", "input_stream": "ec563083-3d9b-457d-a0ac-24b197bc222f" } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>RtpInputStreamResult</name> <port>5000</port> <input_stream>a869ea70-980a-4497-99b4-3ef181f0b87d</input_stream> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
403Forbidden	1026RTP sessions limit exceeded
405Method Not Allowed	1009Technology is not supported by server

Closes opened input RTP stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	ID of opened input RTP stream.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/input_stream/rtp?input_stream=OPENED_RTP_STREAM"

Available responses

HTTP Status Output

200OK

/input_stream/rtp/info – Information about input RTP stream

{
  "result": {
    "version": 1,
    "name": "RtpInputStreamDeleteResult",
    "number_of_received_packets": "100",
    "number_of_lost_packets": "1",
    "packet_loss": "1.0",
    "jitter": "10.24"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>RtpInputStreamDeleteResult</name>
  <number_of_received_packets>100</number_of_received_packets>
  <number_of_lost_packets>1</number_of_lost_packets>
  <packet_loss>1.0</packet_loss>
  <jitter>10.24</jitter>
</result>

Result description

`number_of_received_packets`	number of received packets.
`number_of_lost_packets`	number of lost packes.
`packet_loss`	packet loss as percentage.
`jitter`	jitter in milliseconds.

400Bad Request

1003A required query parameter was not specified for this request
1004An invalid value was specified for one of the query parameters in the request URI

404Not Found

1030Stream not found

405Method Not Allowed

1009Technology is not supported by server

GET /input_stream/rtp/info Information about input RTP stream

Return information about the input RTP stream such as source address, target address, and transfer statistics.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	ID of opened input RTP stream.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/input_stream/rtp/info?input_stream=OPENED_RTP_STREAM"

Available responses

HTTP Status Output

200OK

/input_stream/http – Input HTTP stream

{
  "result": {
    "version": 1,
    "name": "RtpInputStreamInfoResult",
    "source_address": {
      "ip": "127.0.0.1",
      "port": 54271
    },
    "target_address": {
      "ip": "0.0.0.0",
      "port": 10001
    },
    "statistics": {
      "number_of_received_packets": 631,
      "number_of_lost_packets": 0,
      "packet_loss": 0,
      "jitter": 3.0381560121013047
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>RtpInputStreamInfoResult</name>
  <source_address>
    <ip>127.0.0.1</ip>
    <port>58281</port>
  </source_address>
  <target_address>
    <ip>0.0.0.0</ip>
    <port>10001</port>
  </target_address>
  <statistics>
    <number_of_received_packets>353</number_of_received_packets>
    <number_of_lost_packets>0</number_of_lost_packets>
    <packet_loss>0</packet_loss>
    <jitter>3.0308383114718813</jitter>
  </statistics>
</result>

Statistics description

`number_of_received_packets`	number of received packets.
`number_of_lost_packets`	number of lost packes.
`packet_loss`	packet loss as percentage.
`jitter`	jitter in milliseconds.

400Bad Request

1003A required query parameter was not specified for this request
1004An invalid value was specified for one of the query parameters in the request URI

404Not Found

1030Stream not found

405Method Not Allowed

1009Technology is not supported by server

POST /input_stream/http Opens input HTTP stream

Opens input HTTP stream.

See also Usage examples - Speech To Text Stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
frequency	query	string	no	Frequency of streamed data. Default value is 8000.
n_channels	query	string	no	Number of channels. Default value is 1.
path	query	string	no	Path to file where streamed data will be saved. If path is not set file will not be saved. File will be overwritten if already exists.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/input_stream/http?frequency=8000"

Available responses

HTTP Status

Output

200OK

PUT /input_stream/http Send data to input stream via HTTP

{
  "result": {
    "version": 1,
    "name": "HttpInputStreamResult",
    "input_stream": "ec563083-3d9b-457d-a0ac-24b197bc222f"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>HttpInputStreamResult</name>
  <input_stream>a869ea70-980a-4497-99b4-3ef181f0b87d</input_stream>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

405Method Not Allowed

1009Technology is not supported by server

Sends data to input stream via HTTP request. Chunked HTTP stream is supported as well.

See also Usage examples - Speech To Text Stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	ID of opened input HTTP stream.

Body

RAW AUDIO DATA (s16le, frequency and number of channels depends on request
POST /input_stream/http?frequency={FREQ}&n_channels={N})

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server

DELETE /input_stream/http Close opened input HTTP stream

Closes opened input HTTP stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	ID of opened HTTP stream.

Body

empty content

Example

/input_stream/websocket – Input WebSocket stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/input_stream/http?input_stream=OPENED_HTTP_STREAM"

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server

GET /input_stream/websocket Opens input WebSocket stream

Opens input WebSocket stream.

WebSocket handshake request must contains the following parameters in the header: Upgrade, Connection, Sec-WebSocket-Version, Sec-WebSocket-Key and session parameter (X-SessionID) or basic authorization (Authorization).

 GET /input_stream/websocket?frequency=8000&n_channels=1 HTTP/1.1
 Host: server.example.com
 Upgrade: websocket
 Connection: Upgrade
 Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
 Sec-WebSocket-Version: 13
 X-SessionID: 258f505c-a6fa-4c3f-8a87-b048874ac6aa
 Accept: application/json

Ther result of this request is delivered via WebSocket as a first frame. Data must be sent in a binary format in s16le format. If an error occurs during the upgrading connection, the error is delivered as an HTTP response. If an error occurs after a WebSocket connection is established, the WebSocket is closed with the corresponding WebSocket's status code. The maximum frame size is 4 MiB by default. When the WebSocket connection is closed, the input stream stops automatically. This can be changed in the server configuration file using the input_stream.websocket.max_payload_size option.

See also Usage examples - Speech To Text Stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
frequency	query	string	no	Frequency of streamed data. Default value is 8000.
n_channels	query	string	no	Number of channels. Default value is 1.
path	query	string	no	Path to file where streamed data will be saved. If path is not set file will not be saved. File will be overwritten if already exists.

Body

empty content

Available responses

HTTP Status

Output

WebSocket

/output_stream/rtp – Output RTP stream

{
  "result": {
    "version": 1,
    "name": "WebSocketInputStreamResult",
    "input_stream": "ec563083-3d9b-457d-a0ac-24b197bc222f"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>WebSocketInputStreamResult</name>
  <input_stream>a869ea70-980a-4497-99b4-3ef181f0b87d</input_stream>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1043Can't create WebSocket

405Method Not Allowed

1009Technology is not supported by server

GET /output_stream/rtp List status of RTP stream

Lists status of opened output RTP streams for a user. If the user has admin role, all of the opened output RTP streams are listed.

Note that output RTP streams are automatically deleted after the timeout specified in SPE property file. This timeout fires when no task is attached to the output stream, or the attached task is already finished for a given amount of time.

See also Usage examples - External Text To Speech stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
output_stream	query	string	yes	ID of opened output RTP stream.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/output_stream/rtp?output_stream=OPENED_RTP_STREAM"

Available responses

HTTP Status

Output

200OK

POST /output_stream/rtp Open output RTP stream

{
  "result": {
    "version": 1,
    "name": "RtpOutputStreamsListResult",
    "user_output_streams": [
      {
        "user": "admin",
        "output_streams": ["tc548623-3d9b-445d-a8ac-24b17bc222fa", "35cb19b9-9a1e-430f-89a4-2eb33c8a1337"]
      },
      {
        "user": "john",
        "output_streams": ["32ee0cf9-c7a4-4999-a321-241e668db831"]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>RtpOutputStreamsListResult</name>
  <user_output_streams>
    <item>
      <user>admin</user>
      <output_streams>
        <item>tc548623-3d9b-445d-a8ac-24b17bc222fa</item>
        <item>35cb19b9-9a1e-430f-89a4-2eb33c8a1337</item>
      </output_streams>
    </item>
    <item>
      <user>john</user>
      <output_streams>
        <item>32ee0cf9-c7a4-4999-a321-241e668db831</item>
      </output_streams>
    </item>
  </user_output_streams>
</result>

405Method Not Allowed

1009Technology is not supported by server

Opens output RTP stream. Opened stream sends data to host address and port specified. In specified RTP payloadType.

See also Usage examples - External Text To Speech stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
host	query	string	yes	Host in format `address:port`. E.g. myserver.com:6789
payload_type	query	number	yes	Payload type. Supported payloads are `0` (PCMU) and `8` (PCMA). See RTP/HTTP streams for more information.
source_port	query	number	no	Source port. When omitted, the source port is automatically assigned.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/output_stream/rtp?host=127.0.0.1:6789&payload_type=0"

Available responses

HTTP Status

Output

200OK

DELETE /output_stream/rtp Close opened output RTP stream

{
  "result": {
    "version": 1,
    "name": "RtpOutputStreamResult",
    "output_stream": "tc548623-3d9b-445d-a8ac-24b17bc222f"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>RtpOutputStreamResult</name>
  <output_stream>tc548623-3d9b-445d-a8ac-24b17bc222f</output_stream>
</result>

400Bad Request

1003A required query parameter was not specified for this request
1004An invalid value was specified for one of the query parameters in the request URI

405Method Not Allowed

1009Technology is not supported by server

Closes opened output RTP stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
output_stream	query	string	yes	ID of opened output RTP stream.

Body

empty content

Example

/stream/rtp – RTP stream Deprecated

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/output_stream/rtp?output_stream=OPENED_RTP_STREAM"

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server

POST /stream/rtp DeprecatedOpen RTP stream for listening

This endpoint is deprecated since SPE 3.23.x. Use POST /input_stream/rtp instead.

Opens RTP stream for listening. Stream is opened on port, which is returned in result.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	no	Path to file where streamed data will be saved. If path is not set file will not be saved. File will be overwritten if already exists.

Body

empty content

Example

DELETE /stream/rtp DeprecatedClose opened RTP stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/stream/rtp"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "RtpStreamResult", "port": "5000", "stream": "ec563083-3d9b-457d-a0ac-24b197bc222f" } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>RtpStreamResult</name> <port>5000</port> <stream>a869ea70-980a-4497-99b4-3ef181f0b87d</stream> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
403Forbidden	1026RTP sessions limit exceeded
405Method Not Allowed	1009Technology is not supported by server

This endpoint is deprecated since SPE 3.23.x. Use DELETE /input_stream/rtp instead.

Closes opened RTP stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
stream	query	string	yes	ID of opened RTP stream.

Body

empty content

Example

/stream/http – HTTP stream Deprecated

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/stream/rtp?stream=OPENED_RTP_STREAM"

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server

POST /stream/http DeprecatedOpen HTTP stream for listening

This endpoint is deprecated since SPE 3.23.x. Use POST /input_stream/http instead.

Opens HTTP stream for listening.

Parameters

Name	Parameter Type	Data Type	Required	Description
frequency	query	string	no	Frequency of streamed data. Default value is 8000.
n_channels	query	string	no	Number of channels. Default value is 1.
path	query	string	no	Path to file where streamed data will be saved. If path is not set file will not be saved. File will be overwritten if already exists.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/stream/http?frequency=8000"

Available responses

HTTP Status

Output

200OK

PUT /stream/http DeprecatedSend data to stream via HTTP

{
  "result": {
    "version": 1,
    "name": "HttpStreamResult",
    "stream": "ec563083-3d9b-457d-a0ac-24b197bc222f"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>HttpStreamResult</name>
  <stream>a869ea70-980a-4497-99b4-3ef181f0b87d</stream>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI

405Method Not Allowed

1009Technology is not supported by server

This endpoint is deprecated since SPE 3.23.x. Use PUT /input_stream/http instead.

Sends data to stream via HTTP request. Chunked HTTP stream is supported as well.

Parameters

Name	Parameter Type	Data Type	Required	Description
stream	query	string	yes	ID of opened HTTP stream.

Body

RAW AUDIO DATA (s16le, frequency and number of channels depends on request
POST /stream/http?frequency={FREQ}&n_channels={N})

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server

DELETE /stream/http DeprecatedClose opened HTTP stream

This endpoint is deprecated since SPE 3.23.x. Use DELETE /input_stream/http instead.

Closes opened HTTP stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
stream	query	string	yes	ID of opened HTTP stream.

Body

empty content

Example

/utils/audiofile/concatenate – concatenate two audio files

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/stream/http?stream=OPENED_HTTP_STREAM"

Available responses

HTTP Status	Output
200OK
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server

Utils

POST /utils/audiofile/concatenate (asynchronous)Concatenate two audio files to new one.

Concatenate two audio files with the same number of channels and the same frequency. Output file is always WAV. Function concatenate channels on channel level, so that target wav file will have the same number of channels as first file.

Audio file in path1:

channel 1

channel 2

Audio file in path2:

channel 1

channel 2

Audio file in target:

channel 1	channel 1
channel 2	channel 2

Parameters

Name	Parameter Type	Data Type	Required	Description
path1	query	string	yes	Server path to first audio file.
path2	query	string	yes	Server path to second audio file.
target	query	string	yes	Server path where will be stored new audio file. Extension `.wav` is automatically added.

Body

empty content

Example

/utils/audiofile/cut – audio file cutter

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/utils/audiofile/concatenate?path1=/julia.wav&path2=/john.wav&target=/julia_john.wav"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/utils/audiofile/concatenate',
  uri_params: {
    path1: '/julia.wav',
    path2: '/john.wav',
    target: '/julia_john.wav'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
415Unsupported Media Type	1007Unsupported audio format

Resource locker

LOCK File specified by path1
LOCK File specified by path2
CHECK File specified by target (if overwriting existing file)

POST /utils/audiofile/cut (asynchronous)Cut audio file and create new one based on given segmentation

Create new file which will contain data determined by segmentation. Input time values are in 100ns units (value 10000000 is 1sec). Output file is always WAV.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
path	query	string	yes	Server path to the audio file.
keep_original_length	query	boolean	no	If set to true, the new file will keep original length of audio file. Default false.
target	query	string	yes	Server path where will be stored new audio file. Extension `.wav` is automatically added.

Body

{
  "cut_segments": [
    {
      "start": 0,
      "end": 10000000
    },
    {
      "start": 20000000,
      "end":  100000000
    }
    ...
  ]
}

<cut_segments>
  <item>
    <start>0</start>
    <end>1000000</end>
  </item>
  <item>
    <start>2000000</start>
    <end>10000000</end>
  </item>
  ...
</cut_segments>

Example

/utils/audiofile/merge – merging two audio files

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"segmentation.json" "SERVER_ADDRESS:PORT/utils/audiofile/cut?path=/julia.wav&target=/julia_cut.wav"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */

var segments = {
  "cut_segments": [
    {
      "start": 0,
      "end": 10000000
    },
    {
      "start": 20000000,
      "end":  100000000
    }
  ]
};

var options = {
  method: 'POST',
  content: segments,
  uri_path: '/utils/audiofile/cut',
  uri_params: {
    path: '/julia.wav',
    target: '/julia_cut.wav'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Resource locker

LOCK File specified by path
CHECK File specified by target (if overwriting existing file)

POST /utils/audiofile/merge (asynchronous)Merge two audio files to new one.

Merge two audio files to new one. First are stored channels from first source file, then channels from second source file. Frequency of both files has to be identical. Output file is always WAV.

Audio file in path1:

channel 1

channel 2

Audio file in path2:

channel 1

channel 2

Audio file in target:

channel 1
channel 2
channel 3	silent
channel 4	silent

Parameters

Name	Parameter Type	Data Type	Required	Description
path1	query	string	yes	Server path to first audio file.
path2	query	string	yes	Server path to second audio file.
target	query	string	yes	Server path where will be stored new audio file. Extension `.wav` is automatically added.

Body

empty content

Example

/utils/audiofile/split – audio file channel splitter

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/utils/audiofile/merge?path1=/julia.wav&path2=/john.wav&target=/julia_john.wav"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/utils/audiofile/merge',
  uri_params: {
    path1: '/julia.wav',
    path2: '/john.wav',
    target: '/julia_john.wav'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
415Unsupported Media Type	1007Unsupported audio format

Resource locker

LOCK File specified by path1
LOCK File specified by path2
CHECK File specified by target (if overwriting existing file)

POST /utils/audiofile/split (asynchronous)Split channels from record to new files. One new file for each channel.

Take audio file from parameter path and split its channels to separate files. Names will be generated by adding "_X.wav" to target parameter. X represent channel number.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file to be splitted.
target	query	string	yes	Server path which will be used as base for new files.

Body

empty content

Example

/utils/player/output_stream – Player of audio files into output stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/utils/audiofile/split?path=/julia.wav&target=/julia/channel"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/utils/audiofile/split',
  uri_params: {
    path: '/julia.wav',
    target: '/julia/channel'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "AudioFileMultiInfoResult", "info": [ { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } ... ] } } <?xml version="1.0"?> <result> <version>2</version> <name>AudioFileMultiInfoResult</name> <info> <item> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </item> ... </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

Resource locker

LOCK File specified by path
CHECK File(s) specified by target (if overwriting existing file)

GET /utils/player/output_stream Get playback status for given player

Get status of audio file playback for player identified by player ID. Playback time and total length values of result are in seconds (floating point numbers).

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Task ID of player for which the playback status should be retreived

Body

empty content

Example

POST /utils/player/output_stream Start task playing audio file into specified output stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/utils/player/output_stream?task=PLAYER_TASK_ID"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "PlayerOutputStreamTaskInfoResult", "task_id": "8asd2f1c-a78d-42f6-56sa-casd5f4d8s6a", "playback_position": 10.1, "total_length": 55.368 } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>PlayerOutputStreamTaskInfoResult</name> <task_id>8asd2f1c-a78d-42f6-56sa-casd5f4d8s6a</task_id> <playback_position>10.1</playback_position> <total_length>55.368</total_length> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found

Start task playing audio file into specified output stream

Only mono audio files can be played. If needed, use /utils/audiofile/split to obtain channels separately.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Path to audio file which should be played.
output_stream	query	string	yes	Output stream ID where audio file data should be sent.

Body

empty content

Example

DELETE /utils/player/output_stream Stop player task

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/utils/player/output_stream?path=AUDIO_FILE&output_stream=OUTPUT_STREAM_ID"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserOutputStreamTaskInfoResult", "stream_task_info": { "id": "8506180c-e87d-42f6-ac9a-c5ca3a3a3202", "state": "running", "output_stream_id": "29eae856-0004-46a2-a761-9e9a72bad719" } } } <result> <version>1</version> <name>UserOutputStreamTaskInfoResult</name> <stream_task_info> <id>8506180c-e87d-42f6-ac9a-c5ca3a3a3202</id> <state>running</state> <output_stream_id>29eae856-0004-46a2-a761-9e9a72bad719</output_stream_id> </stream_task_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1041Multichannel recording is not allowed
401Unauthorized	1005The request requires user authentication
404Not Found	1030Stream not found 1008File not found

Resource locker

LOCK Audio file

Stop task playing the audio file into output stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Task ID of player which should be stopped.

Body

empty content

Example

/technologies/agestim – age of speaker

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/utils/player/output_stream?task=PLAYER_TASK_ID"

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found

Age Estimation

GET /technologies/agestim (asynchronous)Age estimation - analyze recording

Returns estimated age of speaker in record. This request is asynchronous (see Asynchronous request).

See also Usage examples - Age Estimation for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file
model	query	string	yes	Name of age estimation model
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in cache yet, only 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/agestim?path=/julia.wav&model=S"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/agestim',
  uri_params: {
    path: '/julia.wav',
    model: 'S'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

The time_range parameter in the output is serialized only when query parameters from_time or to_time are specified.

POST /technologies/agestim (asynchronous)Age estimation - analyze voiceprint

{
  "result": {
    "version": 2,
    "name": "AgeEstimationResult",
    "file": "julia_1.wav",
    "model": "L",
    "time_range": {
      "from_time": 2.5,
      "to_time": 5.5
    },
    "channel_scores": [
      {
        "channel": 0,
        "scores": [
          {
            "name": "0",
            "score": 0
          },
          {
            "name": "1",
            "score": 0
          },
          ...
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>AgeEstimationResult</name>
  <file>julia_1.wav</file>
  <model>L</model>
  <time_range>
    <from_time>2.5</from_time>
    <to_time>5.5</to_time>
  </time_range>
  <channel_scores>
    <item>
      <channel>0</channel>
      <scores>
        <item>
          <name>0</name>
          <score>0</score>
        </item>
        <item>
          <name>1</name>
          <score>0</score>
        </item>
        ...
      </scores>
    </item>
  </channel_scores>
</result>

Scores object description

`channel_scores[]`	list of scores for each channel of recording
`channel_scores[]->channel`	index of channel
`channel_scores[]->scores[]`	list of scores for each age class
`channel_scores[]->scores[]->name`	name of age class (estimated number of years)
`channel_scores[]->scores[]->score`	probability of an estimated age. Only one age class has score = 1 and other classes are 0.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1008File not found
1024Result not found

405Method Not Allowed

1009Technology is not supported by server

406Not Acceptable

1035Invalid time range

415Unsupported Media Type

1007Unsupported audio format

Required technologies

Age Estimation (AGE)

Resource locker

LOCK Analyzed file

Returns estimated age of speaker in SID voiceprint. Use request GET /technologies/speakerid/extractvp to extract voiceprint from recording. It is necessary to use same name of AGE model as name of SID model used for voiceprint extraction (for example: voiceprint extracted with model XL3 must be processed only with AGE model XL3) otherwise server returns http error 500.

This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of age estimation model. Use the same model name as used during the voiceprint extraction.
Content-Type	header	string	yes	`application/json` for JSON content (Default value) `application/xml` for XML content `application/octet-stream` for raw voiceprint content

Body

{
  "voiceprint": "<Base64 Data>"
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint>[Base64 Data]</voiceprint>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"voiceprint.json" "SERVER_ADDRESS:PORT/technologies/agestim?model=S"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */

var options = {
  method: 'POST',
  uri_path: '/technologies/agestim',
  uri_params: {
    model: 'S'
  },
  content: {
    "voiceprint": "VlBUIAYA//+pCQAAWAIAAAAAAABwMEofIAAAAKkJAABYAgAAAAAAAAA8HEYAPBxGAAAAAAYAAADL9Xw/UcsevyAbFD/iCuA/tmphP/TqzT8Sjx+/48ocPyme/D/RcrA+JNspP9c+iT+xBog+sEcuwAhV77/2f4+/DHG/PxnnCr8bYi++i6HEvrrOGr9zdLK+nUqTP7+ZGT4asAA/KDGNva4ynjxhphtAYmVFwCoxkL9ba+u+lbajPmc9wr/SzQ1AftyevwQoOz8o6Ya+9JCLP7mRyr8ZIlW/bQDnPZeXmr8RwhDA7VaSv6VfwT1YUcS/EqGMP92z2D/Rz4E/QktnP7ZrVD9rfpO+XapPvjbyCD8aabI+bcFUv7ho2r2ARg28eIilv0KYVb+0x8e+H0rdv613tj/5pay+4vpUvgAdcbu7H5A/0U/cPwV4E79AGmU/W1gUv8w5KsCcDDQ/vpBQPu1mhL9BBVQ/FecMvgxJq76e9ms9WJWPP2jZKL+WHfG+zuk9PrPQMz6cSxk/tc6nP5eREb8YIiU+NY8xP6M2mr8IIKq/qPWVPyl+3T8eNdI/0U6qv0N4+j+S9qU/KogNv3R7AsB+ghc/q8AFP/4iI76Z9s2/lgypPhmlkz9uJti/uvDtv8h2CL/iFgE/XHv8vvvzb789+68/peZgPrrdmr24teK/APQNOQS3BT+qdS8/Vxptv/z0677zkcA+v+jMvwJM3DyDbIa/R62TvpaLTr7KCRe/7cLZvnlVyj6gArQ+WKCpPna1770Qpg8/42l8vzlj4D/ACCi/QFc3v4U3Zr0z9yJA26BvP6ylO77Cgg/AQYrKvmF2iD+mABS+zoGNP/kRzL+zhR+/gryIP89Pcb8gAAAAqQkAAEAGAAAAAAAAADwcRgA8HEYAAAAAPAAAAFwDZb2irbc82pYLPSxOAbzlRAa8L6sSvXc0FDyHpFI9+QejPQw/Lr2cGJ69VPO/O1Wgzr0hSza9a83oPV+Qhb1kOAC9sPOeOzZeDrwHPQA+Wx6iPJTXlDwpgxs8tWqXvF2rYb2ejgG9QlNXPcMr+jwv0RQ8q5qXvZSFXrwrKZo9jC5mPTlQWbwvVZU7nJGyvea5kb1TsEo82SgbvTLaxLucciW8mPBjvRd06DyFzNs82OhGPTwkRbuJa1w9oviTO/fWGjwtlxM9Lsg1PUwDJb37imO91cjCO844wrtABpE9ZxAQvT3ACrzoBqU9zlwfvbCAvz3sAXC9o7raPOTqLD3C7q49sOhhOy7uAT2o3YA9SdfLPBKWgz0iqmU9vHX5PBIgPLw85LC9wrgCvVTg3DyEOko9eamvurK7rrwXtoU91oxBvbPS1b0FAta9ohUEu/mdWb2WMlA8aE8KPVxRtb0NOoI9Xe4FPQ+LqLzz7/q85pNqPbzOer3nkJu9A0y2ulXiXL3BneY7Vz8JvTbCMj15dae7wjowvXT+bby1Gv88ZeMQvBmgA70nLSE8f9IZPXN78jyJe8A8uz9LPQqdTb1KFpe9GycRPez5fTxGW4k8M/u1uuUB3r2dYGw8Uu/xvLd8ibvVYZs8soW0Pd8W8zs088A8KA0hvGLA+TqXHoA9FPuLvaX3Ij3HP9y57QqTPR18Azzs7ta7tuURPWv6IL35gyS9zMHtvETMprxvQC89YR2wPV21ET3t4gk8cqyOPSyTGj3t/GO9uwn6vES6Xz2KOSA8BBWSOwikeDz/84y9piQzvUkyMjtjNuM7A2Qbva2s77tPQHo9q58NPmqAHr0VdsQ9VJ2LPH4+zbudDYO9wEEQvdXzHj2iOY+9yuF1PcujDb3k3ro8xZ1APX878jwdf548Cew5vfKDST1RtWo9ayFwvdRxzzyIL2S7O+AvOidql71jlfS9cpLNPVG7GLzXInu8zLOwPemHHT4Sgi09ynCoPU9fjz2dOcQ8NoaBPS9E4rxrtUk9EK2zPa5ALT3u5DM9jvv7PE9ukLxADfw8wVMjPe6mULxmxms9dxtFvZwhj7338U285zg7PQXRrjuTYnO9y9j3PFZAHbxHDgc9Y5kVvApPMj1pC3Q6hDMpO3kDVLwQ5sq8gKsUvOJK8Dv5gC68mP8oPNV1QD1Q0ke7hBc/PI3qUr3Zp7g85RBzvah4yLwRwWa7WLmdvLb3ibuGrp68NlFNvDKC1Txx7VW9ngYOPb+8sTyuEEq8YwBzPV030TydMky97tAaPf+x4r1kxYE9VgWSPdcltTwjFVq9IxXhPFCchD1HrpI9f8OBPd8aAb359ba9zEAzvPWiwb0X5ws9DbvbvUpl4TxP98y8Y6SwOc1c7TxjBZ49KpMyO9cepzzeu8Q9/mRqPBKi+7vp4L28ldwavU03xT2Q1MW98gMrvb2DILwQctI8iLQOPYS5Zj2nT788CdCkPEdD7z0gDGo99oa4PNwkAjyHl/w8uRVQPeElaL2Uj607HreQPBYFSz3ifVG9LRSqO243Ur3ox2e8d4E5vQKn8DyrmL69Nwq6PEX3Dz3gMVu9BbCEvAhclry3sBS+WIKovFi1lz2EJrM86qLHPVmK1rz+xRS+hRcPPSLJZjypsWK7WbaCvB3TmT1M0+a9PAjAu+RFVzzVFwk+xSlmPDCgvD29XXA93bbqOeAd8LxTriQ9FK5xOyMNHjyBPQm5XaWGvZGolrwe97Y7QnUDPecDtrxr/qg89nZ/PXkAoz0zpDe6/Xc+vWunJz2Vhck9d3ItPWPfh71VAvw8ZGZuPTKLK7v0cqE98dEnPLcgcz0uCq283QyIPRE7kbq0O/U6JGmSPD8Ke7rVceO8zn0/PRy6WT1FBBU9XpsmPVOUK71dU9y8i0VvPS9Wgj2LAIE8ThOePBvAl7wUFTK8WCRcvRrYo7kNfa89eS4IvdF9wDy6Sdq73ADmvSU8+boFOFE8ao6fvbQVHr39zi09mqJVO1lcTr2ZCFO9Ae2DvTVpX73zufK8ES6nutk3vzwIWUw9GYGcPVIfOr1Rv0Y9QT0ZvXb3Dz25w4i7TePvvL4t97uqna889sOsvO5iQb1cWJ09vXwRvbSuAL4="
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

/technologies/agestim/benchmark – age estimation technology benchmark

{
  "result": {
    "version": 2,
    "name": "AgeEstimationResult",
    "file": "{voiceprint}",
    "model": "L",
    "channel_scores": [
      {
        "channel": 0,
        "scores": [
          {
            "name": "0",
            "score": 0
          },
          {
            "name": "1",
            "score": 0
          },
          ...
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>AgeEstimationResult</name>
  <file>{voiceprint}</file>
  <model>L</model>
  <channel_scores>
    <item>
      <channel>0</channel>
      <scores>
        <item>
          <name>0</name>
          <score>0</score>
        </item>
        <item>
          <name>1</name>
          <score>0</score>
        </item>
        ...
      </scores>
    </item>
  </channel_scores>
</result>

Scores object description

`channel_scores[]`	list of scores for each channel of recording
`channel_scores[]->channel`	index of channel
`channel_scores[]->scores[]`	list of scores for each age class
`channel_scores[]->scores[]->name`	name of age class (estimated number of years)
`channel_scores[]->scores[]->score`	probability of an estimated age. Only one age class has score = 1 and other classes are 0.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1025An invalid value was specified for one of the header parameters in the request
1018The requested URI requires content
1019An invalid data was specified in the request content
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Age Estimation (AGE)

GET /technologies/agestim/benchmark (asynchronous)Age estimation technology Benchmark

Benchmark of Age Estimation technology with default set of recordings or specified recording (by parameter path).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Age Estimation technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.

Body

empty content

Example

/technologies/denoiser – denoise recording

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/agestim/benchmark?model=S"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/agestim/benchmark',
  uri_params: {
    model: 'S'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AgeEstimBenchmarkResult", "dataset_version": "1.0", "model_name": "S", "benchmark_result": { "processed_length": 21.31999969482422, "processing_time": 0.502251, "faster_than_realtime": 42.448894466759086 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>AgeEstimBenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>S</model_name> <benchmark_result> <processed_length>21.31999969482422</processed_length> <processing_time>0.502251</processing_time> <faster_than_realtime>42.448894466759086</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Age Estimation (AGE)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file (if used parameter path)

Denoiser

POST /technologies/denoiser (asynchronous)Denoise recording

Create denoised recording from source recording.

Output audio file is always WAV. If file specified by parameter target has no extension or extension is other than .wav, then extension .wav is appended.

This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to source audio file
target	query	string	yes	Server path to target audio file
model	query	string	yes	Name of Denoiser model
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

/technologies/denoiser/benchmark – denoiser technology benchmark

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/denoiser?path=julia_1.wav&target=julia_1_denoised.wav&model=EN_US"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/denoiser',
  uri_params: {
    path: '/julia_1.wav',
    target: '/julia_1_denoised.wav',
    model: 'EN_US'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1035Invalid time range

Required technologies

Denoiser (DENOISER)

Resource locker

LOCK File specified by path

GET /technologies/denoiser/benchmark (asynchronous)Denoiser technology Benchmark

Benchmark of Denoiser technology with default set of recordings or specified recording (by parameter path).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Denoiser technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.

Body

empty content

Example

/external/technologies/tts/info – TTS connectors info

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/denoiser/benchmark?model=EN_US"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/denoiser/benchmark',
  uri_params: {
    model: 'EN_US'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "DenoiserBenchmarkResult", "dataset_version": "1.0", "model_name": "EN_US", "benchmark_result": { "processed_length": 901.930118560791, "processing_time": 191.034012, "faster_than_realtime": 8.379610791963618 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>DenoiserBenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>EN_US</model_name> <benchmark_result> <processed_length>901.930118560791</processed_length> <processing_time>191.034012</processing_time> <faster_than_realtime>8.379610791963618</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Denoiser (DENOISER)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file (if used parameter path)

External Text To Speech

GET /external/technologies/tts/info Text to speech - external connectors info

Returns information about available external TTS connectors.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/external/technologies/tts/info"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;

$options = array(
  'http' =>
  array (
    'method'         => 'GET',
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/external/technologies/tts/info",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

/external/technologies/tts – Generate audio by TTS

{
  "result": {
    "version": 3,
    "name": "ExternalTTSResult",
    "connectors": [
      {
        "vendor": "Acapela",
        "author": "Phonexia",
        "version": "1.0.1",
        "voices": [
          {
            "language_codes": [ "en-US", "cs-CZ" ],
            "name": "Laura",
            "natural_sample_rate_hertz": 8000
          }
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>3</version>
  <name>ExternalTTSResult</name>
  <connectors>
    <item>
      <vendor>Acapela</vendor>
      <author>Phonexia</author>
      <version>1.0.1</version>
      <voices>
        <item>
          <language_codes>
            <item>en-US</item>
            <item>cs-CZ</item>
          </language_codes>
          <name>Laura</name>
          <natural_sample_rate_hertz>8000</natural_sample_rate_hertz>
        </item>
      </voices>
    </item>
  </connectors>
</result>

401Unauthorized

1005The request requires user authentication

POST /external/technologies/tts (asynchronous)Generate audio by external Text To Speech technology

Create new file which will contain speech audio data determined by JSON text content. Generated audio is stored on SPE server on path specified in query parameters. Speech audio is created with voice specified by vendor, name and language_code parameters. To see available voices call /external/technologies/tts/info.
Output file is always WAV in PCM 8k format. Server returns info about audio file with speech which was created. This request is asynchronous (see Asynchronous request).

See also Usage examples - External Text To Speech for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
vendor	query	string	yes	Vendor identifying connector to use.
path	query	string	yes	Server path where will be stored new audio file. Extension of the result is .wav, if user specifies extension different than .wav, it is automatically changed, if no extension is specified, .wav is automatically added.

Body

{
  "tts_input": {
    "text": "The best way to predict the future is to invent it.",
    "voice": {
        "name": "Laura",
        "language_code": "en-US"
     }
   }
}

<tts_input>
  <text>The best way to predict the future is to invent it.</text>
  <voice>
    <name>Laura</name>
    <language_code>en-US</language_code>
  </voice>
</tts_input>

Example

/external/technologies/tts/output_stream – Generate audio by TTS into output stream

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"tts_input.json" "SERVER_ADDRESS:PORT/external/technologies/tts?vendor=VENDOR&path=/julia_1.wav"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */

var tts_input = {
  "tts_input": {
    "text": "The best way to predict the future is to invent it.",
    "voice": {
        "name": "Laura",
        "language_code": "en-US"
     }
  }
};

var options = {
  method: 'POST',
  content: tts_input,
  uri_path: '/external/technologies/tts',
  uri_params: {
    path: '/julia_1.wav',
    vendor: 'VENDOR'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1018The requested URI requires content 1019An invalid data was specified in the request content 1025An invalid value was specified for one of the header parameters in the request 1038Resource is locked
401Unauthorized	1005The request requires user authentication
404Not Found	1062External technology not found

Resource locker

CHECK File specified by path (if overwriting existing file)

POST /external/technologies/tts/output_stream Stream audio generated by external Text To Speech technology

Generate speech audio data determined by JSON text content and send through specified output stream out of Speech Engine. Speech audio is created with voice specified by vendor, name and language_code parameters. To see available voices call /external/technologies/tts/info.
Server returns info about audio file with speech which was created.

See also Usage examples - External Text To Speech stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
vendor	query	string	yes	Vendor identifying connector to use.
output_stream	query	string	yes	Output stream ID where the result will be sent. (see /output_stream/rtp)

Body

{
  "tts_input": {
    "text": "The best way to predict the future is to invent it.",
    "voice": {
        "name": "Laura",
        "language_code": "en-US"
     }
   }
}

<tts_input>
  <text>The best way to predict the future is to invent it.</text>
  <voice>
    <name>Laura</name>
    <language_code>en-US</language_code>
  </voice>
</tts_input>

Example

GET /external/technologies/tts/output_stream Get status of external TTS speech generation task

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"tts_input.json" "SERVER_ADDRESS:PORT/external/technologies/tts?vendor=VENDOR&output_stream=29eae856-0004-46a2-a761-9e9a72bad719"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */

var tts_input = {
  "tts_input": {
    "text": "The best way to predict the future is to invent it.",
    "voice": {
        "name": "Laura",
        "language_code": "en-US"
     }
  }
};

var options = {
  method: 'POST',
  content: tts_input,
  uri_path: '/external/technologies/tts',
  uri_params: {
    output_stream: '29eae856-0004-46a2-a761-9e9a72bad719',
    vendor: 'VENDOR'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserOutputStreamTaskInfoResult", "stream_task_info": { "id": "8506180c-e87d-42f6-ac9a-c5ca3a3a3202", "state": "running", "output_stream_id": "29eae856-0004-46a2-a761-9e9a72bad719" } } } <result> <version>1</version> <name>UserOutputStreamTaskInfoResult</name> <stream_task_info> <id>8506180c-e87d-42f6-ac9a-c5ca3a3a3202</id> <state>running</state> <output_stream_id>29eae856-0004-46a2-a761-9e9a72bad719</output_stream_id> </stream_task_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1018The requested URI requires content 1019An invalid data was specified in the request content 1025An invalid value was specified for one of the header parameters in the request
401Unauthorized	1005The request requires user authentication
404Not Found	1062External technology not found 1030Stream not found

Get status of external TTS speech generation task identified by task ID.
Generated speech length value of result is in seconds (floating point numbers).
Status of task can be either running or finished.
Note that if you're using your own connector, the internal errors of your connector are reported as internal error of SPE.
For further investigation of connector error(s) consult the SPE log file.

See also Usage examples - External Text To Speech stream for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Task ID of external TTS task for which the speech generation status should be retreived

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/external/technologies/tts/output_stream?task=TTS_TASK_ID"

Available responses

HTTP Status

Output

200OK

DELETE /external/technologies/tts/output_stream Stop Text To Speech task

{
  "result": {
    "version": 1,
    "name": "TextToSpeechOutputStreamResult",
    "state": "finished",
    "generated_audio_length": 3.68
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>TextToSpeechOutputStreamResult</name>
  <state>finished</state>
  <generated_audio_length>3.68</generated_audio_length>
</result>

401Unauthorized

1005The request requires user authentication

404Not Found

1010Task not found

Stop task generating the speech audio into output stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Task ID of TTS task which should be stopped.

Body

empty content

Example

/technologies/diarization – diarization of recording

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/external/technologies/tts/output_stream?task=TTS_TASK_ID"

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found

Diarization

GET /technologies/diarization (asynchronous)Diarization - Analyze recording

Returns diarization of recording. By diarization it is possible to split recording by speakers. Diarization results can be improved by setting query parameters properly. Note that this technology does not identify found speakers. This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file
model	query	string	yes	Name of diarization model
max_speakers	query	int	no	Maximum number of speakers, i.e. you know that there is at maximum this number of speakers in the audio. Default value is 2. This parameter applies to models `O`, `S` and `L`.
total_speakers	query	int	no	Total number of speakers, i.e. you know that there is exactly this number of speakers in the audio. This parameter applies only to model `O`.
per_channel	query	boolean	no	If `true`, recording is processed per channel. Processing context is reinitialized for each channel. If `false`, the channels are concatenated to mono and then processed. Default value is `false`.
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in cache yet, only 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/diarization?path=julia_1.wav&model=S"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/diarization',
  uri_params: {
    path: '/julia.wav',
    model: 'S'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

The time_range parameter in the output is serialized only when query parameters from_time or to_time are specified.

/technologies/diarization/benchmark – diarization technology benchmark

{
  "result": {
    "version": 3,
    "name": "DiarizationResult",
    "file": "julia_1.wav",
    "model": "S",
    "max_speakers": 2,
    "total_speakers": 2,
    "per_channel": true,
    "time_range": {
      "from_time": 2.5,
      "to_time": 5.5
    },
    "segmentation": [
      {
        "channel_id": 0,
        "score": 0,
        "confidence": 0,
        "start": 0,
        "end": 6700000,
        "word": "silence"
      },
      {
        "channel_id": 0,
        "score": 0,
        "confidence": 0,
        "start": 6700000,
        "end": 10200000,
        "word": "1"
      },
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>3</version>
  <name>DiarizationResult</name>
  <file>julia_1.wav</file>
  <model>S</model>
  <max_speakers>2</max_speakers>
  <total_speakers>2</total_speakers>
  <per_channel>true</per_channel>
  <time_range>
    <from_time>2.5</from_time>
    <to_time>5.5</to_time>
  </time_range>
  <segmentation>
    <item>
      <channel_id>0</channel_id>
      <score>0</score>
      <confidence>0</confidence>
      <start>0</start>
      <end>6700000</end>
      <word>silence</word>
    </item>
    <item>
      <channel_id>0</channel_id>
      <score>0</score>
      <confidence>0</confidence>
      <start>6700000</start>
      <end>10200000</end>
      <word>1</word>
    </item>
    ...
  </segmentation>
</result>

Result description

segmentation[]	list of segments
segmentation[]->channel_id	channel index
segmentation[]->score	not used, always 0
segmentation[]->confidence	not used, always 0
segmentation[]->start	start time of word (HTK time units - 100ns)
segmentation[]->end	end time of word (HTK time units - 100ns)
segmentation[]->word	contains number of speaker or `silence`

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1008File not found
1024Result not found

405Method Not Allowed

1009Technology is not supported by server

406Not Acceptable

1035Invalid time range

415Unsupported Media Type

1007Unsupported audio format

Required technologies

Diarization (DIAR)

Resource locker

LOCK Analyzed file

GET /technologies/diarization/benchmark (asynchronous)Diarization technology Benchmark

Benchmark of Diarization technology with default set of recordings or specified recording (by parameter path).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Diarization technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.
max_speakers	query	int	no	Maximum number of speakers, i.e. you know that there is at maximum this number of speakers in the audio. Default value is 2. This parameter applies to models `O`, `S` and `L`.
total_speakers	query	int	no	Total number of speakers, i.e. you know that there is exactly this number of speakers in the audio. This parameter applies only to model `O`.
per_channel	query	boolean	no	If `true`, recording is processed per channel. Processing context is reinitialized for each channel. If `false`, the channels are concatenated to mono and then processed. Default value is `false`.

Body

empty content

Example

/technologies/diarization/split – make multi-channel file by diarization

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/diarization/benchmark?model=S"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/diarization/benchmark',
  uri_params: {
    model: 'S'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "DiarizationBenchmarkResult", "dataset_version": "1.0", "model_name": "L", "benchmark_result": { "processed_length": 21.31999969482422, "processing_time": 4.0397680000000005, "faster_than_realtime": 5.277530713353889 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>DiarizationBenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>L</model_name> <benchmark_result> <processed_length>21.31999969482422</processed_length> <processing_time>4.0397680000000005</processing_time> <faster_than_realtime>5.277530713353889</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Diarization (DIAR)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file (if used parameter path)

POST /technologies/diarization/split (asynchronous)Make multi-channel file by diarization

Create new multi-channel file by diarization. Each channel in target file will correspond to one speaker in original recording.

Output audio file is always WAV. If file specified by parameter target has no extension or extension is other than .wav, then extension .wav is appended.

This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file
target	query	string	yes	Server path to created audio file. The file must not exist
model	query	string	yes	Name of diarization model
max_speakers	query	int	no	Maximum number of speakers, i.e. you know that there is at maximum this number of speakers in the audio. Default value is 2. This parameter applies to models `O`, `S` and `L`.
total_speakers	query	int	no	Total number of speakers, i.e. you know that there is exactly this number of speakers in the audio. This parameter applies only to model `O`.
cache_disable	query	boolean	no	If true, result cache will be disabled. Ensures that file will be always processed by diarization and result of diarization will not be stored in cache.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

/technologies/genderid – gender of speaker

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/diarization/split?path=julia_kelly_1.wav&target=splitted_by_diarization.wav&model=S"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/diarization/split',
  uri_params: {
    path: '/julia_kelly_1.wav',
    target: '/splitted_by_diarization.wav',
    model: 'S'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1041Multichannel recording is not allowed 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1024Result not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1035Invalid time range
415Unsupported Media Type	1007Unsupported audio format

Required technologies

Diarization (DIAR)

Resource locker

LOCK Source file

Gender Identification

GET /technologies/genderid (asynchronous)Gender identification - analyze recording

Returns gender of speaker in record. Depending on available models even multichannel records can be processed. This request is asynchronous (see Asynchronous request).

See also Usage examples - Gender Identification for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file
model	query	string	yes	Name of gender identification model
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in cache yet, only 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

POST /technologies/genderid (asynchronous)Gender identification - analyze voiceprint

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/genderid?model=GENERIC&path=julia_1.wav"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/genderid',
  uri_params: {
    path: '/julia.wav',
    model: 'DEFUALT'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	The `score` is posterior probability of speaker being male or female (in range 0.0-1.0) whereas `score_llr` is the log likelihood ratio. The `time_range` parameter in the output is serialized only when query parameters `from_time` or `to_time` are specified. JSON XML { "result": { "version": 3, "name": "GenderIdentificationResult", "file": "julia_1.wav", "model": "GENERIC", "time_range": { "from_time": 2.5, "to_time": 5.5 }, "channel_scores": [ { "channel": 0, "scores": [ { "name": "Female", "score": 0.9989388, "score_llr": 3.4236698 }, { "name": "Male", "score": 0.00106118135, "score_llr": -3.423641 } ] } ] } } <result> <version>3</version> <name>GenderIdentificationResult</name> <file>julia_1.wav</file> <model>GENERIC</model> <time_range> <from_time>2.5</from_time> <to_time>5.5</to_time> </time_range> <channel_scores> <item> <channel>0</channel> <scores> <item> <name>Female</name> <score>0.9989388</score> <score_llr>3.4236698</score_llr> </item> <item> <name>Male</name> <score>0.00106118135</score> <score_llr>-3.423641</score_llr> </item> </scores> </item> </channel_scores> </result>
400Bad Request	1003A required query parameter was not specified for this request 1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1024Result not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1035Invalid time range
415Unsupported Media Type	1007Unsupported audio format

Required technologies

Gender Identification (GID)

Resource locker

LOCK Analyzed file

Returns gender of speaker in SID voiceprint. Use request GET /technologies/speakerid/extractvp to extract voiceprint from recording. It is necessary to use same name of GID model as name of SID model used for voiceprint extraction (for example: voiceprint extracted with model XL3 must be processed only with GID model XL3) otherwise server returns http error 500.

This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of gender identification model. Use the same model name as used during the voiceprint extraction.
Content-Type	header	string	yes	`application/json` for JSON content (Default value) `application/xml` for XML content `application/octet-stream` for raw voiceprint content

Body

{
  "voiceprint": "<Base64 Data>"
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint>[Base64 Data]</voiceprint>

Example

/technologies/genderid/benchmark – gender identification benchmark

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"voiceprint.json" "SERVER_ADDRESS:PORT/technologies/genderid?model=XL3"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */

var options = {
  method: 'POST',
  uri_path: '/technologies/genderid',
  uri_params: {
    model: 'XL3'
  },
  content: {
    "voiceprint": "VlBUICgA\/\/+pCQAA6AMAAAAAAABRgSS6IAAAAKkJAADoAwAAAAAAAAA8HEYAPBxGAAAAACgAAAC9LLZAKIR0QIBYR0DmeYnAqrlsQOP3b7\/vP43AwUMhPy7O5T+Dbey+64AdwEQCkb89SkPA4OSlv5tOcsBbm0K\/Gk6gP86Ihb8vxdW\/55ARP+GogcBZeRhAibl\/P1vBrEAF6AA\/qmIyPnZcWD7kJbk\/6IbFPUp0K8B7v0m\/DvdgPrl4oT9h+as\/88CkQJE4PL+lD58\/D7ZcPTGWmT8x\/8Q\/9u2evkPRK79T+IbAmZB+Pzfwij8M+TNALXLuP0F1Nr+7VoY\/BkzrPgAX7L+qlRrAEmHIva2fFkC\/jWS\/iB1UvwKdOcCrkAtAJkYAvwhxlL8QbpS\/2EjOvI9EBkDzUjM\/kYmYv3uYoz\/y4pa\/F83JPhcTUr9DdWJAtNhAwKULtr\/IaWW\/mUnZPYHUHMCSzWvAfDseQI41qz+\/i6o+uccNvvxhKz99svS+ZlR7PsEu\/L+1IIG\/w\/a+P8DenT8jSFVAb5+xP4bBQz5mnwq9tcGGvdPoxT6+o6o+A5EOPk00Hb9N+4A\/Lh13P5nCIsCFbuU+ELo2QP4rTr9GawvASHKFv5O0kL88HQM\/UAXnv+VawD\/1BCdA\/CCkP4nb+7404HM\/hkAMQP5npz74KijA9+pAPnHzZj5hMYQ\/15Z3vq7kMEBPQQ3A9x0Yv8qWA0DfNos\/qV4PwDQcf7+GBXc\/FTWKvwlJfz1wM6i\/K03avy8HGMAD\/X4\/1arSP1i1sT+mTlu9CTbVPsnuI7\/4ui1AOKQSv1eQKb\/1gA5Aputvv1Hvij96T6u8S5mhvxI73L8qJxnASC0PwI59Cb\/mjo893ygJv1kf2DxVKz2\/31fsvinqAsC\/WCo\/zZKiv3g3Z78bL5a\/xbq\/v9PyhD9iG9c+wL\/IP2TmQb+bLXG\/Gpawv35eOj679gM\/hBYavwZeZcAjmTa\/xDxfPxpNtz9xyy1AmskTwEiWu79q9gxAGBP4vyLqBEBsDCFAJ6DeP5AVwD84ZUPA5Z3TP8uNvT\/w\/gfAm3gfv\/+QJ79Jzsi\/p59vP2JbFkAG08e8K\/7HPxek\/b6gqv2\/nIchwBckQEBqY0+\/nnBNQMb0rb8E1ENAnKKzvkYZBb8TFbI+ijaQQDorDcDwMwY+q0NWwBHJFcAqX9I+C5vfvzJ60r8DJtW+JX\/nv1W9Rj75J8G\/BWN3PxzIar\/DUwrAVX6hPQHRdD+4Auy+RoMDwLkVIMAmBqQ\/EVOcPx9zmT+Zaq49RFEqwEgF871Ec2RAeVWsPw6JBD+YnmpAvrxzPw46iz598ytAXLJgP8mxJj8Rej49MxgPQKsB8z4cGUW\/hBjPvwTXc72wq8G\/NAbVvumhvb\/tP2o\/IAAAAKkJAABgCQAAAAAAAAA8HEYAPBxGAAAAAJABAADOdYc\/LaH4P5bqTD\/A9Rc\/T9amP2UCaz7CQCvA3uYqwPtXUD8odXQ9AIYRPaTzLsBOEja+Ptc\/vyPWhT9BE0Q\/WDGNPkL6n74oRAU\/wU6VP5wkTT\/k2Fa\/r9E7QOK0FsA0RZ2+C2s9vwC5H7+PAo2++BtPv7wioL8Qo8i8QxpJvi+O37+iVdG\/aV6RP7J3CcBbIXy\/NkWXP+ZCx78HH7M\/YrJ+Phxauj0e2ZM\/uqP7vaxn5D8MXCU\/ilc8P5CLazzQ0YY\/Q3TlP+KSSb8IP3s+MFN5vzj+XD4GJNw+O3+1PTCwyryMBjY\/2OXmv34B6L7kscM9sO69PyrVEj58mipApfNCvoQ2rr+LZiy\/z0kTP3o8ob8QgT49EGNBwEbkm77LXQs\/jVlaPpkiSb9ag3W\/mjUVPu8Wp7+oD78+S+MQv5BOnj\/Yh8E9IiToP\/CP8D9MKf4+U37tPzw73b+cZfG9XD9ePzRAqL\/eWRE\/4DfAvqlRY7\/a8Uc\/lx\/CPzrxgr8AANk8TPdxvsf5rT\/wsAG\/c4xmP069+7+iiIm\/\/eWzv36AXz8SFWO\/sCtJvUDi9b5Vaze\/ziVKvYA+5r+s3Ws\/Cu9gP+IUAsBwrTu\/gqz1v9zfiT5qsSy\/ilVJPyIJ4j\/wEge++Bi3PyJZBsBVshDAo1l0vsV6N79gEdS\/mNquP0wvNkCmOG0\/\/I1iv6SBBkDHmAzA36Ngv3v\/o76+dei+5n3UvsLy4D5R0Jg\/TjmgvocBib\/w3A5A0BHYP0LxWz\/gZ8I9qLM3PZdaBL9y9lc+s\/YewFL0mr+4GifACVIFP7lz77+vk6U+HowYP423uz8akKq\/9JA8PqD5rT5bH8k\/kqUIwGBa7T\/f89e\/pbsRv2Qq8z\/GIla\/UEIrP+HlIL+d32U\/aAiKvarhg74qTzBAMFS1PK2zib8AoGM7iFX0v+hd0j+YeiHAYXj\/viwYy77k5Uo+LJF9Pzz1DkDwg3U9yJK+PxxEpbwnOaI\/nSc\/P7KOyr88iio+4OTTvGn8gL6rvmM\/OMhVv4Rgjj+N97w\/YKmTvKjxxj93TxS\/J++aP8jUDMCTPm8\/FhWoPydSxr4PMoU\/y8pXv1gIOD82iEW\/EZR1v7Ggjb6GkUu\/vygkvxS6wb+A4cu+j\/tuv3A8Qz\/AuRk\/acrMP7odmz\/qDxa\/Cq6iP6X7+L40HvI\/Hw8tQE6dT7+c5cE\/d4eJP+z9qb7a1AxASRONP\/0lT8BlIoW\/fBYgv1jiqz\/S2K6\/oqkKwAieSz1RkwFAUEIgPrRusT4IHqe\/nOwuv5JWBEAoJLc94MnlvFSbOj41kpW+0HQgvyowjT9nMgM\/bloyQBpeTj\/l+L4\/th74PoBcAcCeGJw\/TRyEP7zyBL64BW6\/rn0FQOhyDMByJP2\/MqaDv71umT\/M4Q8\/003Av5juyz\/UBAA+4GOePPOw9T+Kzso\/AGo1vJg8V7+cAEg\/pii8P6J6v7\/eiqm\/HdUwQGeQmj8+rsW\/kZguv3TBub7Y4Aa\/rZlvv9L1KL\/MXTrAMm+EP1banj5Xyse\/iu\/cPmhswz8+9Yw\/YOuNvVzXDcAZL4U\/AVsfP8EEi7\/kOTa+vhsQwCP8F8Bo+2+\/TqByv0BrRr5H5cW\/hrk9v0hJV76W5xa+sQEvQLY65z+Ozye\/ERu4Pyxxvb7Hos8\/CgJmPzXKB8BoF\/O\/5+zRv4QmlT\/w1aA8Y0uSP7YNOkDcYU2\/jLZVwP8KCkDT7ri+DiPqPgSyxL\/gQMu\/AhAyP8FTg79Btxy\/LVTRPmDwi79IpT4\/\/mMJv1hnZT\/qfxu\/Zt3SPt6+Qb9xEYg+bLHXPsp4v7\/U\/DBAfCeOP8bVuz7eTCa\/1ke2v8pFt7+YkWa++lUxv+v6vL9QIyi9QgEiwCTSjr+Y3Y8\/K1akPtaSmb\/ZLtA+pbsFQNAIsz\/2XFK\/inzrPiYOIz\/ylRVAx3i5vguVBkBKQug+rJcxvO5adj9mL42\/MbOGv67mhD7A2vk8knqaP4kXqz5F5eg\/0GgLv+t1rz+SAqW\/CxCuP3YxgT93Iao+1Mu4v27RGD\/ohZA\/B8O8P5wb2z+hYX0\/AY\/KPrNikj8453S\/UG6pvxPNo7\/OS7I\/dDGQPn4N9j2j8I6+iKqyv8RWH78R6h1AmiEkP\/CZzD\/O6Uy\/gKNCv+RppT9cBAY\/sCuAPpaFqD54Hmc\/vzxpv\/cH+z4tJh4\/wPmXPbxu0z9xaGC\/qnd2P8SPa7\/lajA\/ukVxP17Wh7+S6cy+GKPdP4BDUr9m95W\/eJjFvxjttD+Mp7E\/0tYNwOK4Fb9eXI+\/laVQv0ozMj8dYic\/eDFTvnQDHz9A2Iu9cbZsPy5OEsAaYAk\/sIccPyCVmD4P8y4\/+L8GPisnab8Yyh5Ay54UPy+Web+\/Qqq\/AHwev9Zl6T\/Jhfg\/\/pViP4GRAj+RNHy\/gtGAQGb+hz55MeQ\/ElDAP308EcBXz5Y\/x7oewGBmfL5KT\/Q+zDlnPyXHtD9A9Q+\/dYcqv0Y\/IT\/oEQ5ABaWNPTz09D\/44e+\/ya1FP5QOOD+QHoy\/6BbNP6rogz\/2vDw\/Ktzsv\/jGKD7YraG9gmxiP9zZ3b70ibW\/AM5TO9Z\/Pz+wsYs+0lEmv+qV8r44r8K\/GvL0Pw3xXz90+vu+zybOP\/9pzb75kxk\/27ASP78ziz8EJFK\/rp2av8u1tL95tyhAiBdcv8R9wj74NMC+lGdLvjT13z9+mdW\/guOzPgf3EEAAXQM\/0IRUvZR5sr8dz1i\/gSjrP80k4T9OCJA\/gjKOv8qoTz9A75U8jU24P940C8DWj1q+5TfHv586m791RqG\/GmsTP4T7mb8It2k+GE20vyApn78yxDXAkGxcvcJKMb74pRO\/BrqdPnlqvb\/gAR69GOtkP4xpfj8R2hJAmFckQBYlzj5AozC8F\/zXP5jMrT\/\/kwhAEFrmP3ybib90rec\/JaF6v8d5bz\/WziZAVC3aP5BYE8BGe62\/JD3KvkiXEL7M9YU+8uqivqDyDT8qYJs\/IQPOP4jCFL9OgA7ANZkFwCUCbz8qIRw\/HRtGvix5k7\/IZHO+AmEmv5BVNsCLMKy+oJi3vfCHNr96878+gEkewP57EsA8z8S\/d15GwMHViD4juEVAnO9dvvPL7L+o8nO\/tCcxv3ZB9D+uaRFAb9pqv3haA8A35JpAYCh0v7BKPTzB92tA9teFwFEj3kCwQq6\/N2uEP+AdsT8="
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	The `score` is posterior probability of speaker being male or female (in range 0.0-1.0) whereas `score_llr` is the log likelihood ratio. JSON XML { "result": { "version": 3, "name": "GenderIdentificationResult", "file": "{voiceprint}", "model": "XL3", "channel_scores": [ { "channel": 0, "scores": [ { "name": "Female", "score": 0.9989388, "score_llr": 3.4236698 }, { "name": "Male", "score": 0.00106118135, "score_llr": -3.423641 } ] } ] } } <result> <version>3</version> <name>GenderIdentificationResult</name> <file>{voiceprint}</file> <model>XL3</model> <channel_scores> <item> <channel>0</channel> <scores> <item> <name>Female</name> <score>0.9989388</score> <score_llr>3.4236698</score_llr> </item> <item> <name>Male</name> <score>0.00106118135</score> <score_llr>-3.423641</score_llr> </item> </scores> </item> </channel_scores> </result>
400Bad Request	1003A required query parameter was not specified for this request 1025An invalid value was specified for one of the header parameters in the request 1018The requested URI requires content 1019An invalid data was specified in the request content 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Gender Identification (GID)

GET /technologies/genderid/benchmark (asynchronous)Gender identification Benchmark

Benchmark of Gender Identification technology with default set of recordings or specified recording (by parameter path).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Gender Identification technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.

Body

empty content

Example

/technologies/keywordspotting – searching keywords

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/genderid/benchmark?model=GENERIC"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/genderid/benchmark',
  uri_params: {
    model: 'GENERIC'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "GenderIdentificationBenchmarkResult", "dataset_version": "1.0", "model_name": "GENERIC", "benchmark_result": { "processed_length": 21.31999969482422, "processing_time": 0.094189, "faster_than_realtime": 226.35339259174873 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>GenderIdentificationBenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>GENERIC</model_name> <benchmark_result> <processed_length>21.31999969482422</processed_length> <processing_time>0.094189</processing_time> <faster_than_realtime>226.35339259174873</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Gender Identification (GID)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file (if used parameter path)

Keyword Spotting

GET /technologies/keywordspotting (asynchronous)Searching keywords

Search for keywords in the given audio file. A list of searched keywords is determined by the kwlist parameter. Keyword spotting is language dependent technology and therefore has the model parameter that determines desired language (see model parameter description).

Returns list of found words. Every found word contains start and end time in the HTK units (hundreds of nanoseconds), raw score, confidence in the range from zero to one, channel id for identifying in which the word was said and text of word with suffix separate by the underscore character that contains either the number of the pronunciation or directly text of the pronunciation (see example output).

This request is asynchronous (see Asynchronous request).

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.
model	query	string	yes	Name of keyword spotting model. For list of supported models use object /technologies/.
kwlist	query	string	yes	Name of keyword list.
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in cache yet, only 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting?path=/julia.wav&model=EN_US_6&kwlist=test"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/keywordspotting',
  uri_params: {
    path: '/julia.wav',
    model: 'EN_US_6',
    kwlist: 'test'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

The time_range parameter in the output is serialized only when query parameters from_time or to_time are specified.

/technologies/keywordspotting/benchmark – keyword spotting benchmark

{
  "result": {
    "version": 2,
    "name": "KeywordSpottingResult",
    "file": "julia_1.wav",
    "keyword_list": "test",
    "model": "EN_US_6",
    "time_range": {
      "from_time": 2.5,
      "to_time": 5.5
    },
    "words": [
      {
        "channel_id": 0,
        "score": 0.7887516,
        "confidence": 0.6875632,
        "start": 94900000,
        "end": 96400000,
        "word": "this_1"
      },
      {
        "channel_id": 0,
        "score": 0.1522667,
        "confidence": 0.5379933,
        "start": 99900000,
        "end": 101900000,
        "word": "this_1"
      },
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>KeywordSpottingResult</name>
  <file>julia_1.wav</file>
  <keyword_list>test</keyword_list>
  <model>EN_US_6</model>
  <time_range>
    <from_time>2.5</from_time>
    <to_time>5.5</to_time>
  </time_range>
  <words>
    <item>
      <channel_id>0</channel_id>
      <score>0.7887516</score>
      <confidence>0.6875632</confidence>
      <start>94900000</start>
      <end>96400000</end>
      <word>this_1</word>
    </item>
    <item>
      <channel_id>0</channel_id>
      <score>0.1522667</score>
      <confidence>0.5379933</confidence>
      <start>99900000</start>
      <end>101900000</end>
      <word>this_1</word>
    </item>
    ...
  </words>
</result>

Result description

keyword_list	name of used keyword list
words[]	list of detected keywords
words[]->channel_id	channel index
words[]->score	raw score (log likelihood ratio in range (-∞, +∞) )
words[]->confidence	keyword confidence (probability in range [0, 1] )
words[]->start	start time of word (HTK time units - 100ns)
words[]->end	end time of word (HTK time units - 100ns)
words[]->word	keyword text

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1052Invalid keyword list
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1008File not found
1024Result not found
1012Keyword list not found

405Method Not Allowed

1009Technology is not supported by server

406Not Acceptable

1035Invalid time range

415Unsupported Media Type

1007Unsupported audio format

Required technologies

Keyword Spotting (KWS)

Resource locker

LOCK Analyzed file
LOCK Keyword list

GET /technologies/keywordspotting/benchmark (asynchronous)Keyword spotting Benchmark

Benchmark of Keyword Spotting technology with specified recording and keyword list.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Keyword Spotting technology model.
kwlist	query	string	yes	Name of keyword list.
path	query	string	yes	Server path to the audio file.

Body

empty content

Example

/technologies/keywordspotting/input_stream – stream keyword spotting

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/benchmark?path=/julia_1.wav&model=EN_US_6&kwlist=test"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/keywordspotting/benchmark',
  uri_params: {
    path: '/julia.wav',
    model: 'EN_US_6',
    kwlist: 'test'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "KeywordSpottingBenchmarkResult", "model_name": "EN_US_6", "file": "/julia_1.wav", "keyword_list": "test", "benchmark_result": { "processed_length": 22.970001220703125, "processing_time": 0.772678, "faster_than_realtime": 29.72777951579199 }, "cpu_info": { "vendor": "AuthenticAMD", "brand": "AMD Ryzen Threadripper 1950X 16-Core Processor ", "n_cores": 16, "n_logical_cores": 32, "l1_data_cache": 32768, "l1_instruction_cache": 65536, "l2_cache": 524288, "l3_cache": 33554432 }, "memory_info": { "total_ram": 33586036736, "free_ram": 12178698240, "total_swap": 4000313344, "free_swap": 3997679616 } } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>1</version> <name>KeywordSpottingBenchmarkResult</name> <model_name>EN_US_6</model_name> <file>/julia_1.wav</file> <keyword_list>test</keyword_list> <benchmark_result> <processed_length>22.970001220703125</processed_length> <processing_time>0.766164</processing_time> <faster_than_realtime>29.98052795576812</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>AuthenticAMD</vendor> <brand>AMD Ryzen Threadripper 1950X 16-Core Processor </brand> <n_cores>16</n_cores> <n_logical_cores>32</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>65536</l1_instruction_cache> <l2_cache>524288</l2_cache> <l3_cache>33554432</l3_cache> </cpu_info> <memory_info> <total_ram>33586036736</total_ram> <free_ram>12187668480</free_ram> <total_swap>4000313344</total_swap> <free_swap>3997679616</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1052Invalid keyword list 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1012Keyword list not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file
LOCK Keyword list

GET /technologies/keywordspotting/input_stream Get partial result from input stream task

Get partial result from task analyzing input stream identified by task ID. A list of searched keywords is determined by the kwlist parameter in http POST for creating keyword spotting task. Keyword spotting is language dependent technology and therefore has the model parameter that determines desired language (see model parameter description).

This request also can be used for registration of Webhook callback or WebSocket handshake.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Input stream Task ID which the request will be attached to
interval	query	double	no	Time interval (in seconds) used for delivery updates of task results via WebSocket or WebHook (it does not affect when using polling). The default value is `0`, which ensures that results are delivered as soon as possible.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/input_stream?task=INPUT_STREAM_TASK_ID"

Available responses

HTTP Status

Output

200OK

POST /technologies/keywordspotting/input_stream Start task analyzing input stream

{
  "result": {
    "version": 2,
    "name": "KeywordSpottingStreamResult",
    "model": "EN_US_6",
    "is_last": false,
    "task_id": "42afa238-412b-4673-9bb7-170a762503c1",
    "task_execution_time": 32.4365,
    "input_stream_id": "fe9525ef-d18a-4826-869e-b5a31b1c57c5",
    "keyword_list": "test_keywordlist",
    "words": [
      {
        "channel_id": 0,
        "score": 0.7887516,
        "confidence": 0.6875632,
        "start": 94900000,
        "end": 96400000,
        "word": "this_1"
      },
      {
        "channel_id": 0,
        "score": 0.1522667,
        "confidence": 0.5379933,
        "start": 99900000,
        "end": 101900000,
        "word": "this_1"
      },
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>KeywordSpottingStreamResult</name>
  <model>EN_US_6</model>
  <is_last>false</is_last>
  <task_id>42afa238-412b-4673-9bb7-170a762503c1</task_id>
  <task_execution_time>32.43656</task_execution_time>
  <input_stream_id>fe9525ef-d18a-4826-869e-b5a31b1c57c5</input_stream_id>
  <keyword_list>test_keywordlist</keyword_list>
  <words>
    <item>
      <channel_id>0</channel_id>
      <score>0.7887516</score>
      <confidence>0.6875632</confidence>
      <start>94900000</start>
      <end>96400000</end>
      <word>this_1</word>
    </item>
    <item>
      <channel_id>0</channel_id>
      <score>0.1522667</score>
      <confidence>0.5379933</confidence>
      <start>99900000</start>
      <end>101900000</end>
      <word>this_1</word>
    </item>
    ...
  </words>
</result>

Result description

is_last	if true, this is the last result of this input stream
task_execution_time	current time of execution
input_stream_id	Input stream ID
task_id	Task ID
keyword_list	name of used keyword list
words[]	list of detected keywords
words[]->channel_id	channel index
words[]->score	raw score (log likelihood ratio in range (-∞, +∞) )
words[]->confidence	keyword confidence (probability in range [0, 1] )
words[]->start	start time of word (HTK time units - 100ns)
words[]->end	end time of word (HTK time units - 100ns)
words[]->word	keyword text

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1050Technology does not support multichannel stream
1052Invalid keyword list
1042WebSocket has already been opened for this operation
1043Can't create WebSocket
1044Can't create WebSocket because user has registered webhook
1069WebHook has already been registered
1070Can't register WebHook because WebSocket has been registered
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1010Task not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Keyword Spotting Stream (KWS_STREAM)

Start analyzing input stream.

This technology can not be attached to multichannel input stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	Input stream ID which the request will be attached to
model	query	string	yes	Name of KWS model. Not all KWS models support stream feature, you can check your server configuration by `GET /technologies`
kwlist	query	string	yes	Name of keyword list.
result_mode	query	string	no	Mode of getting result. Allowed modes are `complete`, `incremental` (default `complete`). See RTP/HTTP streams for more information.

Body

empty content

Example

DELETE /technologies/keywordspotting/input_stream Stop task analyzing input stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/keywordspotting/input_stream?input_stream=INPUT_STREAM_ID&model=EN_US_6&kwlist=test"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserStreamTaskInfoResult", "stream_task_info": { "id": "8506180c-e87d-42f6-ac9a-c5ca3a3a3202", "state": "running", "input_stream_id": "29eae856-0004-46a2-a761-9e9a72bad719" } } } <result> <version>1</version> <name>UserStreamTaskInfoResult</name> <stream_task_info> <id>8506180c-e87d-42f6-ac9a-c5ca3a3a3202</id> <state>running</state> <input_stream_id>29eae856-0004-46a2-a761-9e9a72bad719</input_stream_id> </stream_task_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server
503Service Unavailable	1028Worker limit exceeded 1031Resource not available

Required technologies

Keyword Spotting Stream (KWS_STREAM)

Resource locker

LOCK Keyword list

Stop task analyzing input stream identified by task ID.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Input stream Task ID which the request will be attached to

Body

empty content

Example

/technologies/keywordspotting/kwlists – list of keyword lists

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/keywordspotting/input_stream?task=STREAM_TASK_ID"

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting Stream (KWS_STREAM)

GET /technologies/keywordspotting/kwlists List of keyword lists

Returns list of user's keyword lists. Technology model must be specified as keyword list depends on language.

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of keyword spotting technology model.

Body

empty content

Example

/technologies/keywordspotting/kwlists/{name} – keyword list

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/kwlists?model=EN_US_6"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "EN_US_6";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/keywordspotting/kwlists?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "KeywordSpottingListsResult", "model_name": "EN_US_6", "kwlists": [ "test" ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>KeywordSpottingListsResult</name> <model_name>EN_US_6</model_name> <kwlists> <item>test</item> </kwlists> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

GET /technologies/keywordspotting/kwlists/{name} Get keyword list

Returns keyword list information.

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Determines the name of keyword list.
model	query	string	yes	Name of keyword spotting model.

Body

empty content

Example

POST /technologies/keywordspotting/kwlists/{name} Add keyword list

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/kwlists/test?model=EN_US_6"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$MODEL = "EN_US_6";
$KWLIST_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/keywordspotting/kwlists/$KWLIST_NAME?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "KeywordSpottingListResult", "model_name": "EN_US_6", "keyword_list": "test", "keywords": [ { "name": "angels", "enabled": true, "threshold": 0.5, "pronunciations": [ ] }, { "name": "there", "enabled": true, "threshold": 0, "pronunciations": [ ] }, { "name": "test", "enabled": true, "threshold": 0.4, "pronunciations": [ { "phonemes": "t E s t", "enabled": true, "probability": 0, "is_valid": true } ] } ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>2</version> <name>KeywordSpottingListResult</name> <model_name>EN_US_6</model_name> <keyword_list>test</keyword_list> <keywords> <item> <name>angels</name> <enabled>true</enabled> <threshold>0.5</threshold> <pronunciations/> </item> <item> <name>there</name> <enabled>true</enabled> <threshold>0</threshold> <pronunciations/> </item> <item> <name>test</name> <enabled>true</enabled> <threshold>0.4</threshold> <pronunciations> <item> <phonemes>t E s t</phonemes> <enabled>true</enabled> <probability>0</probability> <is_valid>true</is_valid> </item> </pronunciations> </item> </keywords> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1015User model not found 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

Add keyword list to server. If the keyword list with the same name already exists, it automatically overwrites the newly uploaded content. The request body contains keyword list. Each keyword may contain "threshold" property. The result of KWS will only contain keywords whose confindence is higher or equeal than the "threshold".

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	yes	`application/json` for JSON content (Default value) `application/xml` for XML content
name	path	string	yes	Determines the name of keyword list.
model	query	string	yes	Name of keyword spotting model

Body

{
  "keywords": [
    {
      "name": "angels",
      "enabled": true,
      "threshold": 0.5
    },
    {
      "name": "there",
      "enabled": true,
      "threshold": 0
    },
    {
      "name": "test",
      "enabled": true,
      "threshold": 0.4,
      "pronunciations": [
        {
          "phonemes": "t E s t",
          "enabled": true
        }
      ]
    }
  ]
}

<keywords>
  <item>
    <name>angels</name>
    <enabled>true</enabled>
    <threshold>0.5</threshold>
  </item>
  <item>
    <name>there</name>
    <enabled>true</enabled>
    <threshold>0</threshold>
  </item>
  <item>
    <name>test</name>
    <enabled>true</enabled>
    <threshold>0.4</threshold>
    <pronunciations>
      <item>
        <phonemes>t E s t</phonemes>
        <enabled>true</enabled>
      </item>
    </pronunciations>
  </item>
</keywords>

keywords[]	List of keywords
keywords[]->name	Keyword consist of graphemes. Use this request to obtain allowed graphemes. Using invalid graphemes in keyword causes HTTP error 400 (error code 1019)
keywords[]->enabled	Enables or disables this keyword
keywords[]->threshold	If the confidence of occurrence of the keyword is above the threshold, the occurrence is passed into the result. Parameter is optional (default value is 0.0).
keywords[]->pronunciations[]	Array of custom pronunciations of keyword. Parameter is optional. If parameter is not specified, default pronunciation is used. See also this request to obtain default pronunciation.
keywords[]->pronunciations[]->phonemes	Pronunciation of keyword consist of phonemes separed by space. Use this request to obtain allowed phonemes. Using invalid phonemes in pronunciation causes HTTP error 400 (error code 1019)
keywords[]->pronunciations[]->enabled	Enables or disables this pronunciation

Example

DELETE /technologies/keywordspotting/kwlists/{name} Delete keyword list

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"kwlist.json" "SERVER_ADDRESS:PORT/technologies/keywordspotting/kwlists/test?model=EN_US_6"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$MODEL = "EN_US_6";
$KWLIST_NAME = "test";

$keywords = array(
  'keywords' =>
  array (
    array (
      'name'    => "angels",
      'enabled' => true,
    ),
    array (
      'name'    => "there",
      'enabled' => true,
    ),
    array (
      'name'    => "test",
      'enabled' => true,
      'pronunciations' =>
      array (
        array (
          'phonemes' => "t E s t",
          'enabled'  => true,
        )
      )
    ),
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($keywords),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/keywordspotting/kwlists/$KWLIST_NAME?model=$MODEL",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1025An invalid value was specified for one of the header parameters in the request 1038Resource is locked 1019An invalid data was specified in the request content 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

Resource locker

CHECK Keyword list

Delete keyword list with specified name.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Determines the name of keyword list.
model	query	string	yes	Name of keyword spotting model.

Body

empty content

Example

/technologies/keywordspotting/graphemes – return graphemes for given model

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/keywordspotting/kwlists/test?model=EN_US_6"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$MODEL = "EN_US_6";
$KWLIST_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'content'       => json_encode($keywords),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/keywordspotting/kwlists/$KWLIST_NAME?model=$MODEL",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked 1015User model not found 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

Resource locker

CHECK Keyword list

GET /technologies/keywordspotting/graphemes Return supported graphemes

Return supported graphemes for given kws model.

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of keyword spotting model.

Body

empty content

Example

/technologies/keywordspotting/phonemes – return phonemes for given model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/graphemes?model=EN_US_6"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$MODEL = "EN_US_6";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/keywordspotting/graphemes?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "GraphemeResult", "graphemes": [ "a", "b", ... ], "word_separator": "+" } } <result> <version>2</version> <name>GraphemeResult</name> <graphemes> <item>a</item> <item>b</item> ... </graphemes> <word_separator>+</word_separator> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

GET /technologies/keywordspotting/phonemes Return supported phonemes

Return supported phonemes for given kws model.

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of keyword spotting model.

Body

empty content

Example

/technologies/keywordspotting/pronunciation – pronunciation of keyword

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/phonemes?model=EN_US_6"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$MODEL = "EN_US_6";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/keywordspotting/phonemes?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "PhonemesListResult", "phonemes": [ "@", "@r", ... ] } } <result> <version>1</version> <name>PhonemesListResult</name> <phonemes> <item>@</item> <item>@r</item> ... </phonemes> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

GET /technologies/keywordspotting/pronunciation (asynchronous)Pronunciation of keyword

Returns pronunciation list for keyword. This request is asynchronous, after first call returns pending operation path in header of reply. By sending request with this path is possible to acquire result of operation (see Asynchronous request).

Important notice: The + sign (used in phrases to separate words) in the URL must be encoded as %2B. For example if you want pronunciation of hello+world phrase you have to use: keyword=hello%2Bworld

See also Usage examples - Keyword Spotting for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
keyword	query	string	yes	Keyword.
model	query	string	yes	Name of keyword spotting model

Body

empty content

Example

/technologies/phnrec – phoneme transcription

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/pronunciation?keyword=hello%2Bworld&model=EN_US_6"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/keywordspotting/pronunciation',
  uri_params: {
    keyword: 'hello%2Bworld',
    model: 'EN_US_6'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "KeywordSpottingPronunciationResult", "model": "EN_US_6", "keyword": "hello+world", "pronunciations": [ "h E l oU w @r l d" ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>KeywordSpottingPronunciationResult</name> <model>EN_US_6</model> <keyword>hello+world</keyword> <pronunciations> <item>h E l oU w @r l d</item> </pronunciations> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting (KWS)

GET /technologies/phnrec (asynchronous)Phoneme transcription - Analyze record

Returns phoneme transcription for specified audio file. This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file
model	query	string	yes	Name of technology model
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in cache yet, only 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

/technologies/phnrec/benchmark – phoneme transcription benchmark

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/phnrec?path=julia.wav&model=EN_US_6"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/phnrec',
  uri_params: {
    path: '/julia.wav',
    model: 'EN_US_6'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	Parameter `time_range` in output is present only when query parameters `from_time` or `to_time` are specified. JSON XML { "result": { "version": 1, "name": "PhonemeRecognitionResult", "file": "julia_1.wav", "model": "EN_US_6", "time_range": { "from_time": 2.5, "to_time": 5.5 }, "segmentation": [ { "channel_id": 0, "score": -10.173214, "confidence": -10.173214, "start": 300000, "end": 1100000, "word": "sil" }, { "channel_id": 0, "score": -28.361546, "confidence": -28.361546, "start": 1100000, "end": 2500000, "word": "aU" }, ... ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>PhonemeRecognitionResult</name> <file>julia_1.wav</file> <model>EN_US_6</model> <time_range> <from_time>2.5</from_time> <to_time>5.5</to_time> </time_range> <segmentation> <item> <channel_id>0</channel_id> <score>-10.173214</score> <confidence>-10.173214</confidence> <start>300000</start> <end>1100000</end> <word>sil</word> </item> <item> <channel_id>0</channel_id> <score>-28.361546</score> <confidence>-28.361546</confidence> <start>1100000</start> <end>2500000</end> <word>aU</word> </item> ... </segmentation> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1024Result not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1035Invalid time range
415Unsupported Media Type	1007Unsupported audio format

Required technologies

Phoneme Recognition (PHNREC)

Resource locker

LOCK Analyzed file

GET /technologies/phnrec/benchmark (asynchronous)Phoneme Transcription Benchmark

Benchmark of Phoneme Transcription technology with default set of recordings or specified recording (by parameter path).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Phoneme Transcription technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.

Body

empty content

Example

/technologies/keywordspotting/stream – stream keyword spotting Deprecated

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/phnrec/benchmark?model=EN_US_6"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/phnrec/benchmark',
  uri_params: {
    model: 'EN_US_6'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "PhonemeRecognitionBenchmarkResult", "dataset_version": "1.0", "model_name": "EN_US_6", "benchmark_result": { "processed_length": 1017.0399360656738, "processing_time": 25.795139, "faster_than_realtime": 39.42758114486896 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>PhonemeRecognitionBenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>EN_US_6</model_name> <benchmark_result> <processed_length>1017.0399360656738</processed_length> <processing_time>25.279305</processing_time> <faster_than_realtime>40.23211619408341</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Phoneme Recognition (PHNREC)
Voice Activity Detection (VAD)

GET /technologies/keywordspotting/stream DeprecatedGet partial result from stream task

This endpoint is deprecated since SPE 3.23.x. Use GET /technologies/keywordspotting/input_stream instead.

Get partial result from task analyzing stream identified by task ID. A list of searched keywords is determined by the kwlist parameter in http POST for creating keyword spotting task. Keyword spotting is language dependent technology and therefore has the model parameter that determines desired language (see model parameter description).

This request also can be used for registration of Webhook callback or WebSocket handshake.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Stream Task ID which the request will be attached to
interval	query	double	no	Time interval (in seconds) used for delivery updates of task results via WebSocket or WebHook (it does not affect when using polling). The default value is `0`, which ensures that results are delivered as soon as possible.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/keywordspotting/stream?task=STREAM_TASK_ID"

Available responses

HTTP Status

Output

200OK

POST /technologies/keywordspotting/stream DeprecatedStart task analyzing stream

{
  "result": {
    "version": 1,
    "name": "KeywordSpottingStreamResult",
    "model": "EN_US_6",
    "is_last": false,
    "task_id": "42afa238-412b-4673-9bb7-170a762503c1",
    "task_execution_time": 32.4365,
    "stream_id": "fe9525ef-d18a-4826-869e-b5a31b1c57c5",
    "keyword_list": "test_keywordlist",
    "words": [
      {
        "channel_id": 0,
        "score": 0.7887516,
        "confidence": 0.6875632,
        "start": 94900000,
        "end": 96400000,
        "word": "this_1"
      },
      {
        "channel_id": 0,
        "score": 0.1522667,
        "confidence": 0.5379933,
        "start": 99900000,
        "end": 101900000,
        "word": "this_1"
      },
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>KeywordSpottingStreamResult</name>
  <model>EN_US_6</model>
  <is_last>false</is_last>
  <task_id>42afa238-412b-4673-9bb7-170a762503c1</task_id>
  <task_execution_time>32.43656</task_execution_time>
  <stream_id>fe9525ef-d18a-4826-869e-b5a31b1c57c5</stream_id>
  <keyword_list>test_keywordlist</keyword_list>
  <words>
    <item>
      <channel_id>0</channel_id>
      <score>0.7887516</score>
      <confidence>0.6875632</confidence>
      <start>94900000</start>
      <end>96400000</end>
      <word>this_1</word>
    </item>
    <item>
      <channel_id>0</channel_id>
      <score>0.1522667</score>
      <confidence>0.5379933</confidence>
      <start>99900000</start>
      <end>101900000</end>
      <word>this_1</word>
    </item>
    ...
  </words>
</result>

Result description

is_last	If true, this is the last result of this streaming task
task_execution_time	current time of execution
stream_id	Stream ID
task_id	Task ID
keyword_list	name of used keyword list
words[]	list of detected keywords
words[]->channel_id	channel index
words[]->score	raw score (log likelihood ratio in range (-∞, +∞) )
words[]->confidence	keyword confidence (probability in range [0, 1] )
words[]->start	start time of word (HTK time units - 100ns)
words[]->end	end time of word (HTK time units - 100ns)
words[]->word	keyword text

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1050Technology does not support multichannel stream
1052Invalid keyword list
1042WebSocket has already been opened for this operation
1043Can't create WebSocket
1044Can't create WebSocket because user has registered webhook
1069WebHook has already been registered
1070Can't register WebHook because WebSocket has been registered

401Unauthorized

1005The request requires user authentication

404Not Found

1010Task not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Keyword Spotting Stream (KWS_STREAM)

This endpoint is deprecated since SPE 3.23.x. Use POST /technologies/keywordspotting/input_stream instead.

Start analyzing stream.

This technology can not be attached to multichannel stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
stream	query	string	yes	Stream ID which the request will be attached to
model	query	string	yes	Name of KWS model. Not all KWS models support stream feature, you can check your server configuration by `GET /technologies`
kwlist	query	string	yes	Name of keyword list.
result_mode	query	string	no	Mode of getting result. Allowed modes are `complete`, `incremental` (default `complete`). See RTP/HTTP streams for more information.

Body

empty content

Example

DELETE /technologies/keywordspotting/stream DeprecatedStop task analyzing stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/keywordspotting/stream?stream=STREAM_ID&model=EN_US_6&kwlist=test"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserStreamTaskInfoResult", "stream_task_info": { "id": "8506180c-e87d-42f6-ac9a-c5ca3a3a3202", "state": "running", "stream_id": "29eae856-0004-46a2-a761-9e9a72bad719" } } } <result> <version>1</version> <name>UserStreamTaskInfoResult</name> <stream_task_info> <id>8506180c-e87d-42f6-ac9a-c5ca3a3a3202</id> <state>running</state> <stream_id>29eae856-0004-46a2-a761-9e9a72bad719</stream_id> </stream_task_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded
401Unauthorized	1005The request requires user authentication
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server
503Service Unavailable	1028Worker limit exceeded 1031Resource not available

Required technologies

Keyword Spotting Stream (KWS_STREAM)

Resource locker

LOCK Keyword list

This endpoint is deprecated since SPE 3.23.x. Use DELETE /technologies/keywordspotting/input_stream instead.

Stop task analyzing stream identified by task ID.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Stream Task ID which the request will be attached to

Body

empty content

Example

/technologies/languageid – analyze record

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/keywordspotting/stream?task=STREAM_TASK_ID"

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Keyword Spotting Stream (KWS_STREAM)

Language Identification

GET /technologies/languageid (asynchronous)Analyze record

Returns language identification scores for specified audio file. This request is asynchronous (see Asynchronous request).

See also Usage examples - Language Identification for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.
model	query	string	yes	Name of LID model.
language_pack	query	string	yes	Name of language pack.
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in cache yet, only 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid?path=/julia_1.wav&model=L4&language_pack=default"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/languageid',
  uri_params: {
    path: '/julia_1.wav',
    model: 'L4',
    language_pack: 'default'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

The time_range parameter in the output is serialized only when query parameters from_time or to_time are specified.

/technologies/languageid/benchmark – language identification benchmark

{
  "result": {
    "version": 2,
    "name": "LanguageIdentificationResult",
    "file": "julia_1.wav",
    "language_pack": "default",
    "model": "L4",
    "time_range": {
      "from_time": 2.5,
      "to_time": 5.5
    },
    "channel_scores": [
      {
        "channel": 0,
        "scores": [
         {
            "name": "am-ET",
            "score": -12.136661
          },
          {
            "name": "ar-EG",
            "score": -6.9975476
          },
          ...
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>2</version>
  <name>LanguageIdentificationResult</name>
  <file>julia_1.wav</file>
  <language_pack>default</language_pack>
  <model>L</model>
  <time_range>
    <from_time>2.5</from_time>
    <to_time>5.5</to_time>
  </time_range>
  <channel_scores>
    <item>
      <channel>0</channel>
      <scores>
        <item>
          <name>am-ET</name>
          <score>-12.136661</score>
        </item>
        <item>
          <name>ar-EG</name>
          <score>-6.9975476</score>
        </item>
        ...
      </scores>
    </item>
  </channel_scores>
</result>

Scores object description

`channel_scores[]`	list of scores for each channel of recording
`channel_scores[]->channel`	index of channel
`channel_scores[]->scores[]`	list of scores for each language
`channel_scores[]->scores[]->name`	name of language
`channel_scores[]->scores[]->score`	probability of an estimated language.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1008File not found
1024Result not found

405Method Not Allowed

1009Technology is not supported by server

406Not Acceptable

1035Invalid time range

415Unsupported Media Type

1007Unsupported audio format

Required technologies

Language Identification LanguagePrint Extractor (LIDE)
Language Identification LanguagePrint Comparator (LIDC)

Resource locker

LOCK Analyzed file
LOCK Language pack

GET /technologies/languageid/benchmark (asynchronous)Language identification Benchmark

Benchmark of Language Identification technology with default set of recordings or specified recording (by parameter path).

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Language Identification technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.
language_pack	query	string	no	Name of language pack. If not specified, language pack 'default' will be used.

Body

empty content

Example

/technologies/languageid/extractlp – extract language print

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/benchmark?model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/languageid/benchmark',
  uri_params: {
    model: 'L4'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "LanguageIdentificationBenchmarkResult", "dataset_version": "1.0", "model_name": "L4", "benchmark_result": { "processed_length": 21.31999969482422, "processing_time": 1.348421, "faster_than_realtime": 15.811085480591164 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>LanguageIdentificationBenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>L4</model_name> <benchmark_result> <processed_length>21.31999969482422</processed_length> <processing_time>1.348421</processing_time> <faster_than_realtime>15.811085480591164</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Language Identification LanguagePrint Extractor (LIDE)
Language Identification LanguagePrint Comparator (LIDC)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file (if used parameter path)

GET /technologies/languageid/extractlp (asynchronous)Extract language print from audio file

Extract language print(s) from audio file. This request is asynchronous (see Asynchronous request).

Note: Language prints in result->languageprints[]->languageprint are encoded in Base64. To create *.lp file you will need to decode it first.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.
model	query	string	yes	Name of LID model.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.

Body

empty content

Example

/technologies/languageid/comparelp – compare language print

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/extractlp?path=kelly_julia.wav&model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/languageid/extractlp',
  uri_params: {
    path: '/kelly_julia.wav',
    model: 'L4',
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	The `time_range` parameter in the output is serialized only when query parameters `from_time` or `to_time` are specified. JSON XML { "result": { "version": 2, "name": "LanguagePrintResult", "file": "/kelly_julia.wav", "model": "L4", "time_range": { "from_time": 2.5, "to_time": 5.5 }, "languageprints": [ { "languageprint": <Base64 Data>, "speech_length": 21.34 }, { "languageprint": <Base64 Data>, "speech_length": 26.35 }, ... ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>2</version> <name>LanguagePrintResult</name> <file>/kelly_julia.wav</file> <model>L4</model> <time_range> <from_time>2.5</from_time> <to_time>5.5</to_time> </time_range> <languageprints> <item> <languageprint>[Base64 Data]</languageprint> <speech_length>21.34</speech_length> </item> <item> <languageprint>[Base64 Data]</languageprint> <speech_length>26.35</speech_length> </item> ... </languageprints> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1035Invalid time range
415Unsupported Media Type	1007Unsupported audio format

Required technologies

Language Identification LanguagePrint Extractor (LIDE)

Resource locker

LOCK Analyzed file

POST /technologies/languageid/comparelp (asynchronous)Compare languageprint to language pack

Compare languageprint in POST body to defined language pack in parameter.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
model	query	string	yes	Name of LID model.
language_pack	query	string	yes	Name of language pack.

Body

{
  "languageprint": <Base64 Data>
}

<languageprint>[Base64 Data]</languageprint>

Example

/technologies/languageid/lpinfo – information about languageprint

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST -H "Content-Type:application/json" --data-binary @"lprint.json" "SERVER_ADDRESS:PORT/technologies/languageid/comparelp?model=L4&language_pack=default"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/languageid/comparevp',
  uri_params: {
    model: 'L4'
  },
  content: {
      "languageprint": <Base64 Data>
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "LanguagePrintCompareToLanguagePackResult", "language_pack": "default", "model": "L4", "scores": [ { "name": "am-ET", "score": -12.136661 }, { "name": "ar-EG", "score": -6.9975476 }, ... ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>LanguagePrintCompareToLanguagePackResult</name> <language_pack>default</language_pack> <model>L</model> <scores> <item> <name>am-ET</name> <score>-12.136661</score> </item> <item> <name>ar-EG</name> <score>-6.9975476</score> </item> ... </scores> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1025An invalid value was specified for one of the header parameters in the request 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Language Identification LanguagePrint Comparator (LIDC)

Resource locker

LOCK Language pack

POST /technologies/languageid/lpinfo Information about languageprint

Returns information about the languageprint posted in the request body. The languageprint can contains multiple sub-languageprints. For each sub-languageprint the server returns version, speech_length (in seconds) and user_data (base64 encoded).

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	yes	`application/json` for JSON content (Default value) `application/xml` for XML content `application/octet-stream` for raw languageprint content

Body

{
  "languageprint": "<Base64 Data>"
}

<?xml version="1.0" encoding="UTF-8"?>
<languageprint>[Base64 Data]</languageprint>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"languageprint.json" "SERVER_ADDRESS:PORT/technologies/languageid/lpinfo"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$languageprint = array(
  'languageprint' => 'VlBUIP8BAABLCgAAAAgAAAAAAADyOwRMaWI0QIPrdr8Nb0y/i3hEv0vUgL9k2xi/6PuUP4/raz8QvQbAKMtJwBjmesBEihO/NwxNvmZQtz+IfRm/JUegv9SSJ0DzF08/p7rBP8PoA7/2cybAPfUZwD6i8L9lwz0/pRNnP3NARkC4Zb6+BXzkP0ep7D9Ygry/AX+BQJb5d758EGu/i/6hv0Wbqj8UQxBATbSZv4NwDz8Cu1BA7raUv7A6e0ACuh/AgcERP1swyL1CeNm+zN3Mu3OSRD+HZR/AT2wfQGlHUEDUV8y/FJY6P0FA772KLoRAR9eZvzZaIUBv3j8/dnTxv2BpZcDB+6G/gMOAwIa1E8A6FqW/amzCP6Ld4r+oRyq/rZxqP/Ay3z/8gaE/QcWSQE66Wb5aofM//4JOvxdmcb/uADg/CsC+PXU1dL7GiaQ+nVWtP+BKcz3NAH8+vFOCP+1HBL9nU64/HfC3vjsLkb1kiKy+4SMpv3FlVL/VEPo/jACVv5Kso78uqEjAPQ0fQO1XEsD3sXc+7uwFQOoqSEBpN2/AfvMswBd3gj6ebTe/lBN2PTTn4r+IrrA/ntwOwBq1F0DnERXAS/qmvwMtdj/un0ZAcNZzPkWfU0B4nS6/v67xvzrw0r3YjRA/w3SQv0KKS78GJlVA4+asQPuMdT/g5V5ATSMyPz/E7L9JlwRA1/Wjv9N9gD/PJJK+dcc5wHbhG7/oF0m9d92EP5klnj6F36c/mB6YvnsSZr9EGbs/bmfHv6dxr79VHtC/6JuFP+VD075asKC/yIttPxzaZkA9hw1AoZofPo9j5z44//i/QoUdwBStiL8wkKm/WlWPPzJtR8DxHJQ/MpDuvkts8D/XTYU/HmghQM3hWkBfC6++7BseQLi/lkCo78u/CQAcwE9Htz4eFK0/Ko/dP3M8vL8zfCZAg+uOPjP1zz8/vQg/qEhAPzRfK8D4Q8a+xSjqP2iZ1bv/k0S/bhrjv/3F5r/kAD3A9b0AwMKAb73JAdQ/c7tfQNg4uj8NvHBArfckwD2+M8BTQ0fAsIwrQHL+WL4mbgE/u8qHP/tDnz8hjB/AHeztvy/8FkBWAuw9S1oDQGOMLT9pJSa+saRsvgk/D798GSJAx5ZtQLpCjUAMqB7AuO6fQBilJ75kcy3AsfyXvriD9j7aj1u/ReDFvvDTEsDO292/CK7Hv2tPPMDRtLw/O17BvojZJ79F+xc/Nhg/P+qj6T9SzNC8Yu7jPrUVnL/txuu+u/oCQB6G6z2Vlzm/UCMxv8ZnRD89aV6/CTamvycDSkD+GlnALb6HwCM3PcCAyfs/iH3FP2I3UT5q725ARqbcvSAaZkDAooRAKGqjv3fHK7/6BlBApE1Jv2D1ij8DKDRA8n4AwINBCkCBRm+/fEszQFR5gUAmAR+/OMsgvhy+jsAaqu0/VB4JP+6Sc79ylx++Gei8Pd/4+r9Qqg9Akj/oPgy56b+b4Vs+P1CjP1von7+Lm4BAwol5QNgdLr0X1g6+XXiXQPySOMAraxG/nVL0vTckOUB8kJw/c78iQB/Cqr+OTTdAWKQpQFjCe75LqkNAcTkMwNiUZb5FoBnAxakZQPysA8BJ3AZAnac0wKnLGEDdNVw9/UjaP2uj0z42GZy/FmGeP/Y3okB0wSBA8kQsQFBvtr7j59Y/rzUeQJOlo0AfxBlAzVGYv7xhXr9LnWk/yDh5v8KhhD3gA26/8ZhmQEkfDb8QKJM/KSDJv2o+hj8NVzI/vUYFP/3Ah7+vjoa+ejc7QEJpXb532Yo/v5bQvwPW5D8zZcVAzMvov8k73D63gkG+HYvcP1133j/duSy/XIsdwPdRBr9kHxjA0bQZvx7klT/8lI89Wfr+v3z82D+G4No/e6IAQOsE/D6GxaC/1QQMP8UzD8Dw0jbA/k+XP99iiz8q6xW/Gsx0vufRqT7eNCY+QPDAPyqSgcCqGIA/DpXIPnhyREAqBEm+RKb7vl0hpT58xiw/0Asdvje6qL86QxxAfFIjwFy6ksANazVA+Fz9vynRmL8OoZE/tRHcvrfsy772/7o/pw+iv1jwqr/uEbG/cITMwOSsCcCy9kW+k3PCv757cL9hMCZAu8qzP4VnD0DzFY8/tRL1vqXvgj9mQYVAe3yxP821nsBsRWhAzcorwFqk/T9YfX6/qhjqPqlHzL8Npc492V68PhtATT66GEO/DOO0P4rJEkDXu+S/Bpj1vpXy0j6syd0++Iyzv9+lkcDn1zJA6gW2v5JLmL/GU7s/ZoDKPw0yzT+k9AW+evFmP3tL277ggq+/UxatP7Q3v78WlmDAhz2BvyPc0rzCS5a/OruTv3K7iT/bJKm/Yxs9v4+ECUCeRpQ/ThgPPm42mD7lAfk/jBV3v+roPEAdnEdAA1kkvnx2/b8F1w0/wclOwHx317+HKPi/EQx9vWt96L5PL8w/to2VP+yqdz96Day/23V2P4o1KEAgMyTAiDgCPnlwv79dt5i/000ewHRWoz+mO+y+u1MsQKIuIUCCHqC+PKCBv6Q/lj8ZJN6/TTq1vnu4jz/rFuM/fqpXP9KidMDX/6C/+aLTP68/QMDRRZe/ylmZP1uX274WA0C/DR+8P7DvPsB9TbS+x/FAPs05A0Bw4EzAfeirP1AOrj9DYhs+AGIfv7SUVj+HMaS/xIP8v7tp376/Dx1AW+3OP1bcLkBK6L89WtFxv3dgNT+AC6i/GiljwPmphL9vL4o/Ljt2QELduD9xowI+cuKPv5C2378='
);

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($languageprint),
    'ignore_errors' => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/lpinfo",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

/technologies/languageid/languagemodels – list of language models

{
  "result": {
    "version": 1,
    "name": "LanguagePrintInfoResult",
    "languageprint_info": [
      {
        "index": 0,
        "version": 511,
        "speech_length": 26.35,
        "user_data": "<Base64 encoded user data>"
      }
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>LanguagePrintInfoResult</name>
  <languageprint_info>
    <item>
      <index>0</index>
      <version>511</version>
      <speech_length>26.35</speech_length>
      <user_data>[Base64 encoded user data]</user_data>
    </item>
    ...
  </languageprint_info>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1025An invalid value was specified for one of the header parameters in the request
1018The requested URI requires content
1019An invalid data was specified in the request content
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

GET /technologies/languageid/languagemodels List of language models

Returns the list of language models for the specified technology model.

A list of language models can be used for training new language packs.
See POST /technologies/languageid/languagepacks/{name}

See also Usage examples - Language Identification - Create custom language model for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of LID technology model.

Body

empty content

Example

/technologies/languageid/languagemodels/{name} – language model information

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "LanguageModelsResult", "model": "L4", "builtin_language_models": [ "am-ET", "ar-EG", ... ], "custom_language_models": [ "Custom-model-1", "Custom-model-2", ... ] } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>1</version> <name>LanguageModelsResult</name> <model>L4</model> <builtin_language_models> <item>am-ET</item> <item>ar-EG</item> ... </builtin_language_models> <custom_language_models> <item>Custom-model-1</item> <item>Custom-model-2</item> ... </custom_language_models> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found

GET /technologies/languageid/languagemodels/{name} Language model information

Returns information about language model.

See also Usage examples - Language Identification - Create custom language model for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language model.
model	query	string	yes	Name of LID technology model.

Body

empty content

Example

POST /technologies/languageid/languagemodels/{name} Create empty language model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels/custom-language-model?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_MODEL = "custom-language-model";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels/$LANGUAGE_MODEL?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "LanguageModelInfoResult", "model": "L4", "language_model": { "name": "custom-language-model", "files": [ { "name": "en-US.lpa", "type": "language-print-archive", "language_print_archive_info": { "file_size": 320968720 } }, { "name": "001.lp", "type": "language-print", "language_print_info": [ { "index": 1, "version": 511, "speech_length": 119.49997, "user_data": "<Base64 encoded user data>" } ... ] } ] } } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>1</version> <name>LanguageModelInfoResult</name> <model>L4</model> <language_model> <name>custom-language-model</name> <files> <item> <name>en-US.lpa</name> <type>language-print-archive</type> <language_print_archive_info> <file_size>320968720</file_size> </language_print_archive_info> </item> <item> <name>001.lp</name> <type>language-print</type> <language_print_info> <item> <index>1</index> <version>511</version> <speech_length>119.49997</speech_length> <user_data>[Base64 encoded user data]</user_data> </item> ... </language_print_info> </item> </files> </language_model> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found

Create empty language model.

See also Usage examples - Language Identification - Create custom language model for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language model.
model	query	string	yes	Name of LID technology model.

Body

empty content

Example

DELETE /technologies/languageid/languagemodels/{name} Delete language model

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels/custom-language-model?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_MODEL = "custom-language-model";

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels/$LANGUAGE_MODEL?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1016User model already exist 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication

Required technologies

Language Identification LanguagePrint Comparator (LIDC)

Delete language model.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language model.
model	query	string	yes	Name of LID technology model.

Body

empty content

Example

/technologies/languageid/languagemodels/{name}/file – upload new file(s) to language model

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels/custom-language-model?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_MODEL = "custom-language-model";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels/$LANGUAGE_MODEL?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found

GET /technologies/languageid/languagemodels/{name}/file Dowload file from language model

Dowload file from language model. Note that query parameter path here does not refer to the location on the server, but it is the name of your file within the language model. Therefore, the name of the file should not contain any slash characters ('/').

See also Usage examples - Language Identification - Create custom language model for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language model.
model	query	string	yes	Name of LID technology model.
path	query	string	yes	Name of uploaded file. File must have extension `.lp` or `.lpa`.

Body

empty content

Example

POST /technologies/languageid/languagemodels/{name}/file Upload new file to language model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels/custom-language-model/file?path=001.lp&model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "001.lp";
$MODEL = "L4";
$LANGUAGE_MODEL = "custom-language-model";
$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels/$LANGUAGE_MODEL/file?path=$PATH&model=$MODEL",
  false,
  $context
);

file_put_contents("./$PATH", $response); //= file saved on the PHP server
?>

Available responses

HTTP Status	Output
200OK	BINARY DATA
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found 1008File not found

Upload new file to language model. If the file already exists it is overwritten. The language model must exists. Note that query parameter path here does not refer to the location on the server, but it is the name of your file within the language model. Therefore, the name of the file should not contain any slash characters ('/').

See also Usage examples - Language Identification - Create custom language model for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language model.
model	query	string	yes	Name of LID technology model.
path	query	string	yes	Name of uploaded file. File must have extension `.lp` or `.lpa`.

Body

BINARY LANGUAGE PRINT DATA (*.lp file/Decoded <Base64 Data>)

Example

DELETE /technologies/languageid/languagemodels/{name}/file Delete file in language model

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST --data-binary @"LANGUAGE_PRINT" "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels/custom-language-model/file?path=001.lp&model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "001.lp";
$MODEL = "L4";
$LANGUAGE_MODEL = "custom-language-model";

$language_print = file_get_contents("./001.lp"); //= path to the source file on the client

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/octet-stream',
    'content'       => $language_print,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels/$LANGUAGE_MODEL/file?path=$PATH&model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "LanguageModelFileInfoResult", "model": "L4", "file": { "name": "5_engl.lp", "type": "language-print", "language_print_info": [ { "index": 0, "version": 511, "speech_length": 61.33, "user_data": "" } ] } } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>1</version> <name>LanguageModelFileInfoResult</name> <model>L4</model> <file> <name>5_engl.lp</name> <type>language-print</type> <language_print_info> <item> <index>0</index> <version>511</version> <speech_length>61.33</speech_length> <user_data/> </item> </language_print_info> </file> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
413Request Entity Too Large	1014Size of uploaded file exceeds size limit
415Unsupported Media Type	1068Unsupported format

Delete file in language model. Note that query parameter path here does not refer to the location on the server, but it is the name of your file within the language model. Therefore, the name of the file should not contain any slash characters ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language model.
model	query	string	yes	Name of LID technology model.
path	query	string	yes	Name of deleted file. File must have extension `.lp` or `.lpa`.

Body

empty content

Example

/technologies/languageid/languagepacks – list of language packs

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/languageid/languagemodels/custom-language-model/file?path=001.lp&model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "001.lp";
$MODEL = "L4";
$LANGUAGE_MODEL = "custom-language-model";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagemodels/$LANGUAGE_MODEL/file?path=$PATH&model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found 1008File not found
415Unsupported Media Type	1068Unsupported format

GET /technologies/languageid/languagepacks List of language packs

Returns list of language packs for specific model for language identification.

See also Usage examples - Language Identification - Create language pack for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of LID model.

Body

empty content

Example

/technologies/languageid/languagepacks/{name} – manipulation with language pack

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "LanguageIdentificationPacksResult", "language_packs": [ "default" ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>LanguageIdentificationPacksResult</name> <language_packs> <item>default</item> </language_packs> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Language Identification LanguagePrint Comparator (LIDC)

GET /technologies/languageid/languagepacks/{name} Information about the model

Returns the list of languages in specific language pack for language identification.

See also Usage examples - Language Identification - Create language pack for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language pack.
model	query	string	yes	Name of LID model.

Body

empty content

Example

POST /technologies/languageid/languagepacks/{name} (asynchronous)Create a new language pack

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/default?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_PACK = "default";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 2, "name": "LanguageIdentificationPackResult", "language_pack": "default", "model": "L4", "languages": [ "am-ET", "arb", ... ], "metafiles": [ { "name": "abc.txt", "last_modified": "2021-02-10T08:37:40Z", "created": "2021-02-10T08:37:40Z", "size": 4, "is_directory": false, "is_registered": true }, ... ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>2</version> <name>LanguageIdentificationPackResult</name> <language_pack>default</language_pack> <model>L4</model> <languages> <item>am-ET</item> <item>arb</item> ... </languages> <metafiles> <item> <name>abc.txt</name> <last_modified>2021-02-10T08:37:40Z</last_modified> <created>2021-02-10T08:37:40Z</created> <size>4</size> <is_directory>false</is_directory> <is_registered>true</is_registered> </item> ... </metafiles> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Language Identification LanguagePrint Comparator (LIDC)

Create a new language pack from available language models and register language pack to the system. Each language contains a name and a list of language models. A multiple of language models can be used to create a combined language. At least 2 languages must be specified. Use GET /technologies/languageid/languagemodels to get list of available language models.

With successfuly created language pack comes metafile report which allows to additionaly check, from which languages this language pack was created. You can retrive this metafile by endpoint GET /technologies/languageid/languagepacks/{name}/metafile and specify name of the metafile report.

Show report description

Example report metafile content:

{
  "version": 1,
  "languages":[
    {
      "name":"English",
      "builtin_language_models":[
        {
          "name":"en-US",
          "files":[
            {
              "name":"en-US.lpa",
              "hash":"bdb042b6bf6d30d4"
            },
            ...
          ]
        }
      ],
      "custom_language_models":[
        ...
      ]
    },
    {
      "name":"es-ES-enhanced",
      "builtin_language_models":[
        {
          "name":"es-ES",
          "files":[
            {
              "name":"es-ES.lpa",
              "hash":"f781a98b61f441b3"
            },
            ...
          ]
        }
      ],
      "custom_language_models":[
        {
          "name":"custom-es-model",
          "files":[
            {
              "name":"001.lp",
              "hash":"06f90fe7c1ba00ae"
            },
            ...
          ]
        }
      ]
    },
    ...
  ]
}

Report attributes description

languages[]	list of all languages that were used for creation of LPack
languages[]->name	language name
languages[]->builtin_language_models[]	builtin language models
languages[]->custom_language_models[]	custom language models

Attributes of language models
languages[]->builtin_language_models[] and languages[]->custom_language_models[]

name	name of the language model
files[]	list of files that were used in training of this model
files[]->name	filename
files[]->hash	64 bit hash computed by the `xxHash` algorithm. It allows to identify the file even if it was renamed or moved to another directory. Some Linux package managers provide utility `xxhsum` which reads and checks `xxHash` checksums of files.

See also Usage examples - Language Identification - Create language pack for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language pack.
model	query	string	yes	Name of LID model.

Body

{
  "languages": [
    {
      "name": "English",
      "builtin_language_models": [
        "en-US",
        ...
      ],
      "custom_language_models": [
        ...
      ]
    },
    {
      "name": "Enhanced spanish",
      "builtin_language_models": [
        "es-ES",
        ...
      ],
      "custom_language_models": [
        "custom-es-model"
      ]
    },
    ...
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<languages>
  <item>
    <name>English</name>
    <builtin_language_models>
      <item>
        en-US
      </item>
      ...
    </builtin_language_models>
    <custom_language_models>
      ...
    </custom_language_models>
  </item>
  <item>
    <name>es-ES-enhanced</name>
    <builtin_language_models>
      <item>
        es-ES
      </item>
      ...
    </builtin_language_models>
    <custom_language_models>
      <item>
        custom-es-model
      </item>
    </custom_language_models>
  </item>
    ...
</languages>

Example

DELETE /technologies/languageid/languagepacks/{name} Remove an existing language pack

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" --data-binary @"languagepack_data.json" -X POST "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/new_lpack?model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var content = {
  "languages": [
    {
      "name": "English",
      "builtin_language_models": [
        "en-US"
      ],
      "custom_language_models": []
    },
    {
      "name": "Enhanced spanish",
      "builtin_language_models": [
        "es-ES"
      ],
      "custom_language_models": [
        "custom-es-model"
      ]
    }
  ]
}

var options = {
  method: 'POST',
  content: content,
  uri_path: '/technologies/languageid/languagepacks/new_lpack',
  uri_params: {
    model: 'L4',
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1016User model already exist 1019An invalid data was specified in the request content 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Language Identification LanguagePrint Comparator (LIDC)

Remove an existing language pack. Language pack default is not possible to delete via this endpoint.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language pack.
model	query	string	yes	Name of LID model.

Body

empty content

Example

/technologies/languageid/languagepacks/{name}/metafile – language Pack metafile

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/new_lpack?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_PACK = "new_lpack";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found

Resource locker

CHECK Language pack specified by name in the request path

GET /technologies/languageid/languagepacks/{name}/metafile Download metafile from Language Pack

Downloads a metafile from an Language Pack. The The metafile is determined by the path parameter. Note that the path parameter in the request does not refer to the location of the metafile on the server, but it is the name of the metafile within the Language Pack. Therefore the name of the metafile should not contain any slashes ('/').

See also Usage examples - Language Identification - Create language pack for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the Language Pack.
model	query	string	yes	Name of LID model.
path	query	string	yes	Name of the metafile in the Language Pack.

Body

empty content

Example

POST /technologies/languageid/languagepacks/{name}/metafile Add metafile to Language Pack

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/LANGUAGE_PACK_NAME/metafile?model=L4&path=METAFILE"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "METAFILE";  //= path to the meta file on the Phonexia Speech Engine
$MODEL = "L4";
$LANGUAGE_PACK_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK_NAME/metafile?model=$MODEL&path=$PATH",
  false,
  $context
);

file_put_contents('./METAFILE', $response); //= audio file saved on the PHP server
?>

Available responses

HTTP Status	Output
200OK	METADATA
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found

Uploads a metafile to Language Pack. The request body contains the metafile data. Note that the path parameter in the request does not refer to the location of the metafile on the server, but it is the name of the metafile within the Language Pack. Therefore the name of the metafile should not contain any slashes ('/').

See also Usage examples - Language Identification - Create language pack for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the Language Pack.
model	query	string	yes	Name of LID model.
path	query	string	yes	Name of the metafile in the Language Pack.

Body

metafile

Example

DELETE /technologies/languageid/languagepacks/{name}/metafile Removes metafile from Language Pack

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST --data-binary "@FILE_PATH" "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/LANGUAGE_PACK_NAME/metafile?model=L4&path=METAFILE"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "METAFILE";  //= destination path to the meta file on the Phonexia Speech Engine
$MODEL = "L4";
$LANGUAGE_PACK_NAME = "test";

$content = file_get_contents("./METAFILE"); //= path to the source file on the PHP server

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: text/plain',
    'content'       => $content,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK_NAME/metafile?model=$MODEL&path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1019An invalid data was specified in the request content 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server
413Request Entity Too Large	1014Size of uploaded file exceeds size limit

Remove metafile from Language Pack. The metafile is determined by the path parameter. Note that the path parameter in the request does not refer to the location of the metafile on the server, but it is the name of the metafile within the Language Pack. Therefore the name of the metafile should not contain any slashes ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the Language Pack.
model	query	string	yes	Name of LID model.
path	query	string	yes	Name of the metafile in the Language Pack.

Body

empty content

Example

/technologies/languageid/languagepacks/{name}/registration – language pack registration

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/LANGUAGE_PACK_NAME/metafile?model=L4&path=METAFILE"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "METAFILE";  //= path to the meta file on the Phonexia Speech Engine
$MODEL = "L4";
$LANGUAGE_PACK_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK_NAME/metafile?model=$MODEL&path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found

POST /technologies/languageid/languagepacks/{name}/registration Register language pack to the system

Register language pack to the system. Registration is necessary only when language pack files were manually copied to the server file system without using a proper API request (see POST /technologies/languageid/languagepacks/{name} or POST /technologies/languageid/languagepacks/{name}/file).

Language pack files have to be placed into the server file system according to the following template:
{SERVER_PATH}/home/{USER_NAME}/data/lid/languagepack/{TECHNOLOGY_MODEL}/{LANGUAGE_PACK_NAME}/mlr

User home directory {SERVER_PATH}/home may differ according to server settings
Technology model name {TECHNOLOGY_MODEL} must be upper case (e.g. L4)
Directory /mlr must contain files: mlr.names and *.htk

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language pack.
model	query	string	yes	Name of LID model.

Body

empty content

Example

DELETE /technologies/languageid/languagepacks/{name}/registration Unregister language pack from the system

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/LPACK_NAME/registration?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_PACK = "LPACK_NAME";

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK/registration?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1016User model already exist 1066Unable to register language pack. See server log for additional information. 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication

This function unregisters the language pack from the system. All associated results are removed, but language pack files itself stays in the filesystem.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of language pack.
model	query	string	yes	Name of LID model.

Body

empty content

Example

/technologies/speakerid4 – analyze recording or voiceprint

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/languageid/languagepacks/LPACK_NAME?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$MODEL = "L4";
$LANGUAGE_PACK = "LPACK_NAME";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/languageid/languagepacks/$LANGUAGE_PACK/registration?model=$MODEL",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found

Resource locker

CHECK Language pack specified by name in the request path

Speaker Identification 4

GET /technologies/speakerid4 (asynchronous)Analyze recording

Speaker Identification 4 compares a recording with either a speaker model or speaker group. A speaker model consists of recordings of one speaker. A speaker group consists of several speaker models. Optionally, an Audio Source Profile can be used for the analyzed recording (parameter audio_source_profile_1) as well as for the speaker model / group (parameter audio_source_profile_2) to ensure that the results are optimized for your data. This request is asynchronous (see Asynchronous request).

See also Usage examples - Speaker Identification 4 - process recording for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.
model	query	string	yes	Name of the SID4 model.
speaker_model	query	string	yes if group is not specified	Name of the speaker model.
group	query	string	yes if speaker_model is not specified	Determines the speaker group. To select all speaker models use the virtual group "all".
audio_source_profile_1	query	string	no	Name of the Audio Source Profile for the recording. If the profile name starts with a '/' symbol it is taken as a path in the storage. In that case, the result is not saved to the cache. See Usage examples for more information.
audio_source_profile_2	query	string	no	Name of the Audio Source Profile for the speaker model (or speaker group). If the profile name starts with a '/' symbol it is taken as a path in the storage. In that case, the result is not saved to the cache. See Usage examples for more information.
cache_only	query	boolean	no	If true, `cache_only` ensures that the result is returned only if it is already in the cache (the result is stored in the cache if the file has already been processed by the technology). If the result isn't in the cache yet, 404 status is returned. This parameter is not mandatory and if it is not set by the user, the recording is processed by the given technology automatically if the result is not already in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
cache_disable	query	boolean	no	If true, the result cache is disabled. `cache_disable` ensures that the recording is always processed and the result is not stored in the cache. Parameters `cache_only` and `cache_disable` can not be used together.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Using this parameter causes that the result is not saved to the cache. Time is given in seconds.
min_score_threshold	query	float	false	Only scores above and equal to this threshold will be sent back to client. Using this parameter disables cache.
max_score_threshold	query	float	false	Only scores below and equal to this threshold will be sent back to client. Using this parameter disables cache.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4?path=julia.wav&model=L4&group=group1&audio_source_profile_1=test_profile_1&audio_source_profile_2=test_profile_2"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/speakerid4',
  uri_params: {
    path: '/julia.wav',
    model: 'L4',
    group: 'group1',
    audio_source_profile_1: 'test_profile_1',
    audio_source_profile_2: 'test_profile_2'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

POST /technologies/speakerid4 (asynchronous)Analyze voiceprint

{
  "result": {
    "version": 1,
    "name": "SpeakerIdentification4MultiResult",
    "model": "L4",
    "speaker_group": "group1",
    "time_range": {
      "from_time": 2.5,
      "to_time": 5.5
    },
    "results": [
      {
        "file": "julia_1.wav",
        "speaker_model": "test1",
        "audio_source_profile_1": "test_profile_1",
        "audio_source_profile_2": "test_profile_2",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": 15.753671
              }
            ]
          }
        ]
      },
      {
        "file": "julia_1.wav",
        "speaker_model": "test2",
        "audio_source_profile_1": "test_profile_1",
        "audio_source_profile_2": "test_profile_2",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": -14.8087845
              }
            ]
          }
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>SpeakerIdentification4MultiResult</name>
  <model>L4</model>
  <speaker_group>group1</speaker_group>
  <time_range>
    <from_time>2.5</from_time>
    <to_time>5.5</to_time>
  </time_range>
  <results>
    <item>
      <file>julia_1.wav</file>
      <speaker_model>test1</speaker_model>
      <audio_source_profile_1>test_profile_1</audio_source_profile_1>
      <audio_source_profile_2>test_profile_2</audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>15.753671</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
    <item>
      <file>julia_1.wav</file>
      <speaker_model>test2</speaker_model>
      <audio_source_profile_1>test_profile_1</audio_source_profile_1>
      <audio_source_profile_2>test_profile_2</audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>-14.8087845</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
  </results>
</result>

Result description

model	Name of SID4 model
speaker_group	Name of speaker group or empty when no group is used.
time_range	This parameter is serialized only when query parameters `from_time` or `to_time` are specified.
results[]	An array containing results for each speaker of a group, or exactly one item when using a speaker model.

Results array item description

file	Path of the processed file.
speaker_model	Name of speaker model for which this result is.
audio_source_profile_1	Name of Audio Source Profile for the recording.
audio_source_profile_2	Name of Audio Source Profile for the speaker model (or speaker group).
channel_scores[]	Array of scores for each audio channel.

Channel score item description

channel	Channel index
scores[]	Array of scores. This response always contains only one score.
scores[]->score	LLR (Log-likelihood ratio) based on natural logarithm.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1017User model not ready
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1008File not found
1015User model not found
1024Result not found

405Method Not Allowed

1009Technology is not supported by server

406Not Acceptable

1035Invalid time range

415Unsupported Media Type

1007Unsupported audio format

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

LOCK Analyzed file
LOCK Speaker model (if parameter speaker_model is used)
LOCK Speaker group (if parameter group is used). Also all speaker models contained in group are locked as well.
LOCK Audio Source Profile (if parameters audio_source_profile_1 or audio_source_profile_2 is used)

Speaker Identification 4 compares a voiceprint with a speaker model or speaker group. A speaker model consists of recordings of one speaker. A speaker group consists of several speaker models. The speaker model or speaker group has to be prepared first (see speaker model or groups)

It is necessary to use the same SID4 model for processing as the SID4 model used for voiceprint extraction otherwise the server returns HTTP error 500.

Optionally, an Audio Source Profile for analyzed voceprint (parameter audio_source_profile_1) and for speaker model / group (audio_source_profile_2) can be specified, to ensure that provided system results are the best for your data. This request is asynchronous (see Asynchronous request).

See also Usage examples - Speaker Identification 4 - process recording for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of the SID4 model.
speaker_model	query	string	yes if group is not specified	Name of the speaker model.
group	query	string	yes if speaker_model is not specified	Determines the speaker group. To select all speaker models use the virtual group "all".
audio_source_profile_1	query	string	false	Name of the Audio Source Profile for the analyzed voiceprint. If the profile name starts with a '/' symbol it is taken as a path in the storage. See Usage examples for more information.
audio_source_profile_2	query	string	false	Name of the Audio Source Profile for the speaker model (or speaker group). If the profile name starts with a '/' symbol it is taken as a path in the storage. See Usage examples for more information.
min_score_threshold	query	float	false	Only scores above and equal to this threshold will be sent back to client. Using this parameter disables cache.
max_score_threshold	query	float	false	Only scores below and equal to this threshold will be sent back to client. Using this parameter disables cache.
Content-Type	header	string	yes	`application/json` for JSON content (Default value) `application/xml` for XML content `application/octet-stream` for raw voiceprint content

Body

{
  "voiceprint": "<Base64 Data>"
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint>[Base64 Data]</voiceprint>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"voiceprint.json" "SERVER_ADDRESS:PORT/technologies/speakerid4?model=L4&group=group1&audio_source_profile_1=test_profile_1&audio_source_profile_2=test_profile_2"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/speakerid4',
  uri_params: {
    model: 'L4',
    group: 'group1',
    audio_source_profile_1: 'test_profile_1',
    audio_source_profile_2: 'test_profile_2'
  },
  content: {
    "voiceprint": "VlBUIP4BAACJCQAAAAgAAAAAAAAHyZdwk4qWvwNxD8A6LFW/DMgPwGj+CUCC8kfAGGZlv+4djr+A9OG/yU08wPOfLMBdIA8/UwB2P6rCGcCTbDDA/CoAwN+IF8DEfhdAhgAswN12L8CN5iQ/mWWBwMlukMBtsXzAnTQqwP5Ntz8vWTfAb7N1vU+lCECt3InAcXinvxPb6j5Mv0HARHgzvzT4nD8sphpArDjWv0qpaD+W5p0/1T7RvyTvNsCOpdW/02r1v/sOur/o1jxA0E2ov1aUV8AGWwPAnAnrvyRJsb/OjQNAJ55hwER2PMB4JLc/e1C+Pz4b1r2nITTAwALzPnhxuj84LwbAehiDQMISKsA+ZIS/I2DEv9R0kz/O+RPARHRfQFoHXT9eIq2/pNMDQMI/FEDqtCjAvXZBwO+ATsClLE9AfHzhu+5CgL+c/njANobSP1sutz/IMGhA6AfCPe48DUAAB8c+NysJP5xXfkARt5w/2VtFv/cMiMASnodAOdb+vmMTD8CXONi+GmAMvnRFtz8GqiPAj/4FQOqzIkAFydE/+PEKwOb60j/CJt8/Sp1AQFkm5TwQ+RfAviwtQCjsEUA53Xo/CFHDP21zvr/dYPY/hEYqwAzS5D9w5/a/646KwCeKQ8DaSQNAkuviP/4XC0AaUBdAksI7Pmb7OEBwhExA912iPwNriUBWDJc/WPoMwLA8MMC9pWo/8kJdvzx9GsBNogNAfIxHwL/Q+L+Loi/A/iKkPxCDHkDAFTI/YlNUQDjwvj/ThBxALWr5P31H0z835Bc/FzEpwBO0HcB6PKA/ivGAwKrZj79P+J2/l0h/wFpcUkCJTK6//ccFwM98IMAaO/Y+MtsDwJt0776GxBw/WXEMwPHUHr/NLg6+xtoLQDCcd76/Fp0/rEtuwLwTGj30/p8/Qq6IwPQkbL/hYTrAbgY9QL+ROcCv26I+zyc9P113nj1F0qO/pbqdwKbEzD89ghxALSJ4P8j4Lj+/ZHLAKPTPP4Qovb8o0sy+UZeMvq4OhkD1qCpAfOg9Ph8IjT8twD3AWv4zQK87lj8aTS3Ax/Z0v0sWqr2Qp00/SzcdQKB/ID2oRN8/S9RcQC36kz9E6JW+sGJ6QJGJHsAKsm0+kJXCP2/FST777/g/+g1RwFokrj+uE6G/qUZnP+2ueMB7v1RAF9QdQPYH4z94Oz3Ak8EbP1uLicDiXR1AGSc+QDnLJEDgdarAh9tawLLACMAwI/4/wFQ0wKP7msB//JC/qIStwB5jOD/T/n/AMimhPrprA0D256Y/4UoBwNeOjz+ev+g/AEeVwFit/z/zjxVAzD2SPylGr79HHgPALOVTwFIvA0DhzlzAIudLwLvbwT8hxlQ+jSFEwO7Ekz8YPq0+s7+fwFsWasAu+SZAKvqFP9q9WECIvP4/KlWavyCtCcASE/i+JgX0P5ZW679oWUpAodU6Pu4/HcBMOEK/cNmTP36Wab98+Sw/fO2+P5QV0L/vLZM/TDFQP+DNSr8LG0HAMGBRQNTLjcDd2U3ADvrjPxyvAMCVRiRADvmcP21tgsASYZk/0a4WwEYp17/P8Gu/vktKwD3lNMDlxWzAtLwiwBZTfsBVxSFAwVWUv91hcsDmkX4/Fk2Ivw48lD2j8N2+s5GoP6c+IMC48HtAm0xVwB2QdcBxeRfAKLfdP1abJMDpNda+EY0rwN0ZvD8yDklAcFITQPFRMcBEdxY/CvKXPyzFDL8tPwlA+bllv/R0LsCm08E/pt9PvXCH9j6bzzW/MKdZP3kzbkAvftA/FS0KQCHS/D6ydknARZMjwBsOCMDrRkBA8APtPxE9NUB1qThAl5WbwIxT3D/gwB1APTkWwKtl+z8LyPW+O8mOPwi4H8Acv+Q/S6SLvjdsEL8ePzhA8FJLvzVdGsDFndQ/5dOPPkAdM78NUBDADbVRwEFbij/NiCJA6Gg5QNqsX8Bf6z4+z59qPvAzzD+lrIw/akYVvxarQMAiaIJAWm7hvyOpjcAqktQ/oPNoP6xMKcBvWp4/fpQewBNwSMDe+8s/ME6kP1ipvT+oSANAanwvv4kFTsAoz+2/8IQmQBMqCECFgpg+PQ0IwNGz+r7xoDbAZGWNP3vtor5Usi7AUX0lwG+HRcCm8xK/LIeDQAvst8C/m6Q/WlANQIF/IcBhuS5ArUsJv5XoxD7YPo/ARtfWPnsEYkD50eu+hooZP52T8r9RUWM+arh4v1YhkT/e/hvAixDMP8kk0MC0jEhAFNqGwILOM0AT3AdAo7I4wBysFMCjowI/X10WwHFJ4b1y+KM/F8D1Ph5aAsAeIjfAP5n9v+Hnzz/6FE/A0vM+QKq9Yr97OUvAXW9bwCr1ZsCwO9k/yNPOv8rXH75lE6w/VcTgv45pV0BbFxo+3lrnv89vYb8Zq4S/9mccQJqumj/G26A/BBgePlvz7L4zD7++FeQjQC52pDz4wzLAWgZgQPcENMBRtc6/bJEBQKowSD5ajRLAUkMgQL4cdT/hdFJAnOaNPib4BD+f9CC/y1tCv0wO27/Q6SbA20MpwIswFsBjIa+/65XavQXlTsAUFSbA8H/kvw68AMBQTZ2/eYSIQD0mX8Bnvu8/6P+tviXLH7/fnQbAiAoZQJQagMC3FXTAPphEPvrvIcDIMDNAatxiwDsnMcB9eUzAv4wswO8cjD4xRVbAn7kZwH6fVb7NeRW/mM7Ov1RWh7+VfzhAEGeFPyOwV70Xp1zAy252wE/qVD/dlhs/QZt1P2FN9b4="
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

/technologies/speakerid4/input_stream – analyze input stream

{
  "result": {
    "version": 1,
    "name": "SpeakerIdentification4MultiResult",
    "model": "L4",
    "speaker_group": "group1",
    "results": [
      {
        "file": "{voiceprint}",
        "speaker_model": "test1",
        "audio_source_profile_1": "test_profile_1",
        "audio_source_profile_2": "test_profile_2",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": 15.753671
              }
            ]
          }
        ]
      },
      {
        "file": "{voiceprint}",
        "speaker_model": "test2",
        "audio_source_profile_1": "test_profile_1",
        "audio_source_profile_2": "test_profile_2",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": -14.8087845
              }
            ]
          }
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>SpeakerIdentification4MultiResult</name>
  <model>S</model>
  <speaker_group>group1</speaker_group>
  <results>
    <item>
      <file>{voiceprint}</file>
      <speaker_model>test1</speaker_model>
      <audio_source_profile_1>test_profile_1</audio_source_profile_1>
      <audio_source_profile_2>test_profile_2</audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>15.753671</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
    <item>
      <file>{voiceprint}</file>
      <speaker_model>test2</speaker_model>
      <audio_source_profile_1>test_profile_1</audio_source_profile_1>
      <audio_source_profile_2>test_profile_2</audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>-14.8087845</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
  </results>
</result>

Result description

model	Name of SID4 model
speaker_group	Name of speaker group or empty when no group is used.
results[]	An array containing results for each speaker of a group, or exactly one item when using a speaker model.

Results array item description

file	It always contains the string `"{voiceprint}"`.
speaker_model	Name of speaker model for which this result is.
audio_source_profile_1	Name of Audio Source Profile for the recording.
audio_source_profile_2	Name of Audio Source Profile for the speaker model (or speaker group).
channel_scores[]	Array of scores for each audio channel. It contains only one item because Voiceprint should only contain data for one audio channel.

Channel score item description

channel	Channel index
scores[]	Array of scores. This response always contains only one score.
scores[]->score	LLR (Log-likelihood ratio) based on natural logarithm.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1017User model not ready
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1015User model not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

LOCK Speaker model (if parameter speaker_model is used)
LOCK Speaker group (if parameter group is used). Also all speaker models contained in group are locked as well.
LOCK Audio Source Profile (if parameters audio_source_profile_1 or audio_source_profile_2 is used)

GET /technologies/speakerid4/input_stream Get partial result from input stream task

Get partial result from task analyzing input stream identified by task ID.

This request also can be used for registration of Webhook callback or WebSocket handshake.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Input stream Task ID
interval	query	double	no	Time interval (in seconds) used for delivery updates of task results via WebSocket or WebHook (it does not affect when using polling). The default value is `0`, which ensures that results are delivered as soon as possible.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/input_stream?task=STREAM_TASK_ID"

Available responses

HTTP Status

Output

200OK

POST /technologies/speakerid4/input_stream Start task analyzing input stream

{
  "result": {
    "version": 1,
    "name": "SpeakerIdentification4InputStreamMultiResult",
    "model": "L4",
    "is_last": true,
    "task_id": "bfc641a4-37a4-4983-8276-5f63dcc70fd0",
    "task_execution_time": 19.28692,
    "input_stream_id": "6fdb15f6-4c01-48fc-ba4e-832c9da69acd",
    "speaker_group": "all",
    "utterance_length": 9.9,
    "min_utterance_length_limit": 0,
    "results": [
      {
        "file": "",
        "speaker_model": "david_1",
        "audio_source_profile_1": "",
        "audio_source_profile_2": "",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": 14.225391
              }
            ]
          }
        ]
      },
      {
        "file": "",
        "speaker_model": "david_2",
        "audio_source_profile_1": "",
        "audio_source_profile_2": "",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": 8.92917
              }
            ]
          }
        ]
      },
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>SpeakerIdentification4InputStreamMultiResult</name>
  <model>L4</model>
  <is_last>true</is_last>
  <task_id>dcae1de7-341e-40ac-a868-864e6f671181</task_id>
  <task_execution_time>6.008333</task_execution_time>
  <input_stream_id>1f693724-9183-45d7-8051-829887d47c75</input_stream_id>
  <speaker_group>all</speaker_group>
  <utterance_length>1.11</utterance_length>
  <min_utterance_length_limit>0</min_utterance_length_limit>
  <results>
    <item>
      <file/>
      <speaker_model>david_1</speaker_model>
      <audio_source_profile_1></audio_source_profile_1>
      <audio_source_profile_2></audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>2.6890395</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
    <item>
      <file/>
      <speaker_model>david_2</speaker_model>
      <audio_source_profile_1></audio_source_profile_1>
      <audio_source_profile_2></audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>1.9447069</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
    ...
  </results>
</result>

Result description

is_last	If true, this is the last result of this streaming task.
model	Name of SID4 model
task_execution_time	Current time of execution [s].
task_id	Task ID
input_stream_id	Input stream ID
speaker_group	Name of speaker group or empty when no group is used.
utterance_length	Length of speech [s].
min_utterance_length_limit	Obsolete. Always zero.
results[]	An array containing results for each speaker of a group, or exactly one item when using a speaker model.

Results array item description

file	Always empty for stream
speaker_model	Name of speaker model for which this result is.
audio_source_profile_1	Name of Audio Source Profile for the input stream.
audio_source_profile_2	Name of Audio Source Profile for the speaker model (or speaker group).
channel_scores[]	Array of scores for each audio channel. It contains only one item because this technology only supports single-channel audio for the input stream.

Channel score item description

channel	Channel index
scores[]	Array of scores. This response always contains only one score.
scores[]->score	LLR (Log-likelihood ratio) based on natural logarithm.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1050Technology does not support multichannel stream
1060The capacity for technology has been exceeded
1061The result is not available
1042WebSocket has already been opened for this operation
1043Can't create WebSocket
1044Can't create WebSocket because user has registered webhook
1069WebHook has already been registered
1070Can't register WebHook because WebSocket has been registered
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1010Task not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Stream Extractor (SID4E_STREAM)
Speaker Identification 4 VoicePrint Stream Comparator (SID4C_STREAM)

Start analyzing input stream identified by stream ID. Speaker identification compares audio from input stream with specified speaker model or speaker group - a voiceprint is extracted (internally, in the background) from the incoming stream audio and the voiceprint is compared to the speaker model or speaker group.

By default, speech from all incoming audio (since the start of the analysis) is used for creation of the internal voiceprint.
If the floating_window parameter is used, only the last N seconds of speech from incoming audio is used for creation of the internal voiceprint; this feature is useful for detecting changes of speaker over time (NOTE: the recommended value is 5 seconds; using lower values may produce unreliable results, using higher values prolongs the reaction time to speaker change).

When both speaker model (speaker_model) and speaker group (group) parameters are omitted, then getting result by GET /technologies/speakerid4/input_stream is not possible but it is still possible to obtain current voiceprint by GET /technologies/speakerid4/input_stream/voiceprint.

Note that since SPE 3.32.0 it is suggested to use POST /technologies/speakerid4/input_stream/voiceprint for voiceprint results

Speaker model consists of recordings of one speaker. Speaker group consists of several speaker models. Speaker model and Speaker group have to be prepared before analyzing starts (see PUT /technologies/speakerid4/speakermodels/{name}/prepare and PUT /technologies/speakerid4/groups/{name}/prepare). Prepare requests requires Speaker Identification 4 VoicePrint Extractor (SID4E) technology.

Optionally, an Audio Source Profile can be used for the analyzed input stream (parameter audio_source_profile_1) as well as for the speaker model / group (parameter audio_source_profile_2) to ensure that the results are optimized for your data.

This technology can not be attached to multichannel input stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	Input stream ID which the request will be attached to
model	query	string	yes	Name of SID4 model.
speaker_model	query	string	no	Name of the speaker model.
group	query	string	no	Determines the speaker group. For select all speaker models use virtual group "all".
floating_window	query	double	no	Voiceprint will be extracted only from last N seconds of speech if the parameter is set. The value must be greater than 0.0. The recommended value is 5 seconds. Using lower values may produce unreliable results, using higher values prolongs the reaction time to speaker change.
audio_source_profile_1	query	string	no	Name of the Audio Source Profile for the input stream. If the profile name starts with a '/' symbol it is taken as a path in the storage.
audio_source_profile_2	query	string	no	Name of the Audio Source Profile for the speaker model (or speaker group). If the profile name starts with a '/' symbol it is taken as a path in the storage.

Body

empty content

Example

DELETE /technologies/speakerid4/input_stream Stop task analyzing input stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/speakerid4/input_stream?input_stream=STREAM_ID&model=L4&group=GROUP_NAME"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserStreamTaskInfoResult", "stream_task_info": { "id": "8506180c-e87d-42f6-ac9a-c5ca3a3a3202", "state": "running", "input_stream_id": "29eae856-0004-46a2-a761-9e9a72bad719" } } } <result> <version>1</version> <name>UserStreamTaskInfoResult</name> <stream_task_info> <id>8506180c-e87d-42f6-ac9a-c5ca3a3a3202</id> <state>running</state> <input_stream_id>29eae856-0004-46a2-a761-9e9a72bad719</input_stream_id> </stream_task_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1017User model not ready 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server
503Service Unavailable	1028Worker limit exceeded 1031Resource not available

Required technologies

Speaker Identification 4 VoicePrint Stream Extractor (SID4E_STREAM)
Speaker Identification 4 VoicePrint Stream Comparator (SID4C_STREAM)
Note that SID4C_STREAM is not required if both speaker_model and group parameters are omitted.

Resource locker

LOCK Speaker model (if parameter speaker_model is used)
LOCK Speaker group (if parameter group is used). Also all speaker models contained in group are locked as well.
LOCK Audio Source Profile (if parameters audio_source_profile_1 or audio_source_profile_2 is used)

Stop task analyzing input stream identified by task ID.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Input stream Task ID which the request will be attached to

Body

empty content

Example

/technologies/speakerid4/input_stream/voiceprint – get voiceprint from input stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/speakerid4/input_stream?task=STREAM_TASK_ID"

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found
405Method Not Allowed	1009Technology is not supported by server

GET /technologies/speakerid4/input_stream/voiceprint Get current voiceprint from stream task

Get current voiceprint from input stream identified by task ID.

Result voiceprint (result->voiceprint) may be empty string until first data are processed.

This request also can be used for registration of Webhook callback or WebSocket handshake.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Input stream Task ID
interval	query	double	no	Time interval (in seconds) used for delivery updates of task results via WebSocket or WebHook (it does not affect when using polling). The default value is `0`, which ensures that results are delivered as soon as possible.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/input_stream/voiceprint?task=STREAM_TASK_ID"

Available responses

HTTP Status

Output

200OK

POST /technologies/speakerid4/input_stream/voiceprint Start voiceprint extraction from input stream

{
  "result": {
    "version": 4,
    "name": "SpeakerIdentification4VoiceprintInputStreamResult",
    "model": "L4",
    "is_last": false,
    "task_id": "bfc641a4-37a4-4983-8276-5f63dcc70fd0",
    "task_execution_time": 19.28692,
    "input_stream_id": "6fdb15f6-4c01-48fc-ba4e-832c9da69acd",
    "voiceprint": <Base64 Data>,
    "speech_length": 12.7
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>4</version>
  <name>SpeakerIdentification4VoiceprintInputStreamResult</name>
  <model>L4</model>
  <is_last>false</is_last>
  <task_id>bfc641a4-37a4-4983-8276-5f63dcc70fd0</task_id>
  <task_execution_time>19.28692</task_execution_time>
  <input_stream_id>6fdb15f6-4c01-48fc-ba4e-832c9da69acd</input_stream_id>
  <voiceprint>[Base64 Data]</voiceprint>
  <speech_length>12.7</speech_length>
</result>

Result description

is_last	If true, this is the last result of this streaming task.
model	Name of SID4 model
task_execution_time	Current time of execution [s].
task_id	Task ID
input_stream_id	Input stream ID
speech_length	Length of speech [s].
voiceprint	Voiceprint data in Base64 encoding. This may be empty until first data are processed.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1050Technology does not support multichannel stream
1060The capacity for technology has been exceeded
1042WebSocket has already been opened for this operation
1043Can't create WebSocket
1044Can't create WebSocket because user has registered webhook
1069WebHook has already been registered
1070Can't register WebHook because WebSocket has been registered
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1010Task not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Stream Extractor (SID4E_STREAM)

Start voiceprint extraction from input stream identified by stream ID.

By default, speech from all incoming audio (since the start of the analysis) is used for creation of the voiceprint.
If the floating_window parameter is used, only the last N seconds of speech from incoming audio is used for creation of the voiceprint; this feature is useful for detecting changes of speaker over time (NOTE: the recommended value is 5 seconds; using lower values may produce unreliable results, using higher values prolongs the reaction time to speaker change).

This technology can not be attached to multichannel input stream.

Parameters

Name	Parameter Type	Data Type	Required	Description
input_stream	query	string	yes	Input stream ID which the request will be attached to
model	query	string	yes	Name of SID4 model.
floating_window	query	double	no	Voiceprint will be extracted only from last N seconds of speech if the parameter is set. The value must be greater than 0.0. The recommended value is 5 seconds. Using lower values may produce unreliable results, using higher values prolongs the reaction time to speaker change.
voiceprint_backward_compatibility	query	bool	no	Applicable only to XL5 model, ignored for other models. If enabled, the extracted voiceprint will contain also XL4-compatible part. Such voiceprint can be then compared with either XL5, or XL4 voiceprints. NOTE: Voiceprint with the XL4-compatible part is bigger than voiceprint with only XL5 part (3 KiB vs. 2 KiB).

Body

empty content

Example

DELETE /technologies/speakerid4/input_stream/voiceprint Stop task analyzing input stream

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/speakerid4/input_stream/voiceprint?input_stream=STREAM_ID&model=L4"

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "UserStreamTaskInfoResult", "stream_task_info": { "id": "8506180c-e87d-42f6-ac9a-c5ca3a3a3202", "state": "running", "input_stream_id": "29eae856-0004-46a2-a761-9e9a72bad719" } } } <result> <version>1</version> <name>UserStreamTaskInfoResult</name> <stream_task_info> <id>8506180c-e87d-42f6-ac9a-c5ca3a3a3202</id> <state>running</state> <input_stream_id>29eae856-0004-46a2-a761-9e9a72bad719</input_stream_id> </stream_task_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1017User model not ready 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1030Stream not found
405Method Not Allowed	1009Technology is not supported by server
503Service Unavailable	1028Worker limit exceeded 1031Resource not available

Required technologies

Speaker Identification 4 VoicePrint Stream Extractor (SID4E_STREAM)

Stop task analyzing input stream identified by task ID.

Parameters

Name	Parameter Type	Data Type	Required	Description
task	query	string	yes	Input stream Task ID which the request will be attached to

Body

empty content

Example

/technologies/speakerid4/extractvp – extract voiceprint

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/speakerid4/input_stream/voiceprint?task=STREAM_TASK_ID"

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1010Task not found
405Method Not Allowed	1009Technology is not supported by server

GET /technologies/speakerid4/extractvp (asynchronous)Extract voiceprints from audio file

Extracts the voiceprint from an audio file. A resulted voiceprint is not saved to the cache. This request is asynchronous (see Asynchronous request).
Voiceprint size: L4: 2 KiB, XL4: 1 KiB, XL5: 2-3 KiB (see voiceprint_backward_compatibility parameter)

Parameters

Name	Parameter Type	Data Type	Required	Description
path	query	string	yes	Server path to the audio file.
model	query	string	yes	Name of the SID4 model.
from_time	query	double	no	`from_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed from the beginning. Time is given in seconds.
to_time	query	double	no	`to_time` specifies the time range of the recording to be processed. If the parameter is not specified or equals "0" the recording is processed to the end. Time is given in seconds.
voiceprint_backward_compatibility	query	bool	no	Applicable only to XL5 model, ignored for other models. If enabled, the extracted voiceprint will contain also XL4-compatible part. Such voiceprint can be then compared with either XL5, or XL4 voiceprints. NOTE: Voiceprint with the XL4-compatible part is bigger than voiceprint with only XL5 part (3 KiB vs. 2 KiB).

Body

empty content

Example

/technologies/speakerid4/comparevp – compare voiceprints

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/extractvp?path=julia_1.wav&model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/speakerid4/extractvp',
  uri_params: {
    path: '/julia.wav',
    model: 'L4',
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	The `time_range` parameter in the output is serialized only when query parameters `from_time` or `to_time` are specified. `voiceprint_set` may contains more than one voiceprint when input recording is multi-channel. Each voiceprint is extracted from one channel, and `voiceprint_set` is sorted by channel order. JSON XML { "result": { "version": 3, "name": "SpeakerIdentification4VoiceprintResult", "file": "\/kelly_julia.wav", "model": "L4", "time_range": { "from_time": 2.5, "to_time": 5.5 }, "voiceprint_set": [ { "voiceprint": <Base64 Data>, "speech_length": 12.7 }, { "voiceprint": <Base64 Data>, "speech_length": 24.8 }, ... ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>SpeakerIdentification4VoiceprintResult</name> <file>/kelly_julia.wav</file> <model>L4</model> <time_range> <from_time>2.5</from_time> <to_time>5.5</to_time> </time_range> <voiceprint_set> <item> <voiceprint>[Base64 Data]</voiceprint> <speech_length>12.7</speech_length> </item> <item> <voiceprint>[Base64 Data]</voiceprint> <speech_length>24.8</speech_length> </item> ... </voiceprint_set> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1035Invalid time range
415Unsupported Media Type	1007Unsupported audio format

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)

Resource locker

LOCK Analyzed file

POST /technologies/speakerid4/comparevp (asynchronous)Analyze two voiceprints

Compares two voiceprints. This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
model	query	string	yes	Name of the SID4 model.
audio_source_profile_1	query	string	no	Name of the Audio Source Profile for the first voiceprint. If the profile name starts with a '/' symbol it is taken as a path in the storage.
audio_source_profile_2	query	string	no	Name of the Audio Source Profile for the second voiceprint. If the profile name starts with a '/' symbol it is taken as a path in the storage.

Body

{
  "voiceprints": [
    <Base64 Data>,
    <Base64 Data>
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprints>
  <item>
    [Base64 Data]
  </item>
  <item>
    [Base64 Data]
  </item>
</voiceprints>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST -H "Content-Type:application/json" --data-binary @"voiceprints.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/comparevp?model=L4&audio_source_profile_1=test_profile_1&audio_source_profile_2=test_profile_2"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/speakerid4/comparevp',
  uri_params: {
    model: 'L4',
    audio_source_profile_1: 'test_profile_1',
    audio_source_profile_2: 'test_profile_2'
  },
  content: {
    "voiceprints": [
      "VlBUIAcAAAD9CAAA6AMAAAAAAAD3vHKT8LtfPk373b\/gMhG\/BAyNvXDZjD86XH0\/0FyCP1e6iD8zjba+OAAgv\/Jj3z0TL54+bm+0PiwUVb\/g6ErAE7jXPos6Mb8xYRy\/UEcAQGgoZT8eb+Q\/oGxIP88EBT5YrYY\/8WqWP\/0WrD\/xa44\/lomHP+yqjz+soYI\/RRgZPdoFtj9ZCmQ\/qKIEP7nuhL4Bl4O\/g9kJv1\/erb8gA1q+CsSRPzNga78qMo6\/kISNvwykbD9P+Jq\/zUWGPiVKAUDwvIq\/E6yPv8WYpr\/SpAa\/wbaJvXgpHL4QwJu95Wk5Pj5mXb7n8+49Xz2bPy3SSj+6Uvw+5ZgDP\/Fqsb\/KgiC+yadGP4lmFj53iwE\/ZpeRP9SwOD9tQWU+8yKRvW8RFz\/Jryy\/pgQnvxN4zb6GCCs\/rmQiP51l3z4hRp0\/JVOYv+oVE76B6gM+oLErv6imh7war3E\/zS\/OP4BF0r\/QAZA+IMgEPvM5hj\/dWYg+HRa5P+RkMr9I0rY+MEdWPrifzL+vmBi\/ihuNvjjj4b8yzEI\/17JnP78GvT9ZSgG\/rNqbvwD6Iz66ZRlAguRbPjwv9T7OE5o\/ok6Lvhdso79bJO+\/noI5vz\/xWb+Udvi8cfAdP3b6pD440NS+tTUdwMhpAjxSTH+\/DjDJPT4Lez2b7y0\/o3IYP8AHKT+rvRy\/YLigvBGtfb\/IUBe+KL3gv6mV2z+8g9G\/tFXdPppkKb0NeQA\/g\/oJQPTrbjweV7M+rbJqv\/IXv78oRE8+ET54v0uXs7\/8TIi\/RESXP48LjD8lN25AulqTv2LrtL\/6J6W+5QRrv971Zb9S1hnA+t1TPzOJED5GOTe\/di+6Pq7cQL\/tLCk+5IsBPt3n374WlqG\/t0Udvv9W9b8SyAo\/p343vylLSb8z4UO\/kttMv4ZwrD\/d7Hq\/WPo6Pz4bRz1kycM\/AGA3O5DIZb7Eqjc\/lYDnPejvH0D0d9G\/wvvCv1bu3j5uhKI\/CMK0PMX3RT9bUI2\/OJnSPcBppr5sGd0+IYtIv6o4ar+oxyG+tXTMPqkCmD+ty6a\/f+PyPmKR3r6ML+G\/rNxevgvMED8bS4A\/U\/oevp6Nar+UPR0\/1EYiwAovzj5O3ry\/teVFPu9Nk781WUO\/tQQ9QMQWGL+4LMe99A+hv\/67SD7kfD7ApnkWv\/TZnj4K2IE\/JyOev5qAz75dJ2e\/vp4Wv3OlXT8rO2a\/Hiz2P3olHb3nLgO\/uQpjP+02Rj8hGmg\/tsi6PdKfKD\/JHVQ\/zPsHv9YZjL1eVTs\/Y8Olv\/kNez61bb6\/7aICP9oqX7\/2BDu+sIGevy\/e+z4MwxQ+vThJvhqC4r84fdi\/SvSJvw==",
      "VlBUIAcAAABIDAAA6AMAAAAAAAD4FigbpNHSPk1S2b\/4upC\/Jhv\/vliBYz82X1M\/LYy5P9BDMz90Izm\/oGe1PdWMlb7J2OG9CFQsv6H9Q79rIAzAjLFdP8Ra2b70OhXA+jK+PiT3hD\/e\/q4\/s8SHP8CyGD\/jzDw\/X+\/OPxSJHz8GWWM84v7DPyKyAj3ls+M+YDTDvk3UUz+R4D8\/4mesPgGjtT3mJ4e\/X9t0vxa8bz0hlYg+UbMEQNykDb+3ZUq\/m0mAv9i+tr1FrlG\/pIl\/PXZPJ0BPb+092GUMwEEnyr+igHU\/f43fPSkK8L3eZBa\/jG0bvzKBWb+JbVK\/obVlP4Z4dD\/0y8o8xEIQvqVdgr87EhBAIhsRQGbwL7+ePvg+dqBdPqw7JD+uzwQ\/cP\/Cvn+zrj8sgPe\/2LocvtNrhr90q3E\/i36iP+gHC77bQTO+Ji2MPt0nt76OY7q+1VHYPU3LSz4ePSa\/WSBEP0A6+r8Op4c\/3jQaP56PIb\/BvZa\/kFSuPyw33D4d0oK\/L\/4KP\/vfKL\/5aaS\/VIKXPxHj5T6RaJm+HUuPviNq1z82Jcs+DFtJP5X+JL\/f97k\/CLkYOlUMBb8IxZS+Gb9Xv9QVqr\/IN82\/L7MFP9cslzyvyKA\/k57gPhycQD64Fx4+RTlgPchBLjza3J2\/Tbsvv9IE1D4T9W4+AH4xv65yqr7adq68b+ZKPrJzrb1U\/\/a+0Jo2vhuVbj\/JZ\/i\/YNAdP9bONb\/3rNQ+EMJfP2YT+j5PRUU\/AHKRvwxnG7\/\/fio\/Xbndv3dEf78QOZG\/G2gsQPDLiT+Au\/A\/UdIrP9pn3b5JeQa\/3PaLvzh3tz7rTCrAWucWvWJk2j\/Nky4\/ez+EP2CWyb9Dc4U\/6aQpP+hPiD6UwE++7AS6P4dQB8BMOmc\/Qbu4Pz77U77SVoc\/6BcFP2afCz9ZbSi\/+z6UPzLRh72G2cM\/t9mPvuWDcr9qRFE+S5UcQDvrxj+PrpA\/5uOdv3vcSz+R2Aw\/12WUvCScIb\/vxJO\/8++tP2I4gr5fUkM\/vGqCv\/hcB0BLT8y9aX6ov9kOLT5koZW\/6ehyvep6pjyVJ6O\/vfRoPmoOab8R6vk\/biEAP6EDA0BQ+1g+Yq2+vyEjNUAxb4W\/xo5SP3w4nL7caIu+l+LqP14XPL4Ocdm+miuiP43SnD9BJFLAsHSrvwelOL17B7C\/yRbTvirTZT\/a7x+\/JxTpPWf6aT0mlmO\/85AgP4rLmj9cw6K\/zZChP\/ym6T4W3jA\/ligQwPF7n7\/Ewj0\/yK+gPhrjL78IKYY+H2jpP3gncj05e5++GHcrP3vK\/L4usla+ZFMDvVho4r4w2Ls\/lEfVP9p\/nL6mvdu\/gyGDvg=="
    ]
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status

Output

200OK

/technologies/speakerid4/comparevpset – compare voiceprint set

{
 "result": {
   "version": 1,
    "name": "SpeakerIdentification4MultiResult",
    "model": "L4",
    "speaker_group": "",
    "results": [
      {
        "file": "",
        "speaker_model": "",
        "audio_source_profile_1": "profile_test_1",
        "audio_source_profile_2": "profile_test_2",
        "channel_scores": [
          {
            "channel": 0,
            "scores": [
              {
                "score": 13.249981
              }
            ]
          }
        ]
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>SpeakerIdentification4MultiResult</name>
  <model>L4</model>
  <speaker_group/>
  <results>
    <item>
      <file/>
      <speaker_model/>
      <audio_source_profile_1>test_profile_1</audio_source_profile_1>
      <audio_source_profile_2>test_profile_2</audio_source_profile_2>
      <channel_scores>
        <item>
          <channel>0</channel>
          <scores>
            <item>
              <score>13.249981</score>
            </item>
          </scores>
        </item>
      </channel_scores>
    </item>
  </results>
</result>

Result description

model	Name of SID4 model
speaker_group	Always empty for this request.
results[]	An array containing the results - always contains only one item for this request.

Results array item description

file	Always empty for this request.
speaker_model	Always empty for this request.
audio_source_profile_1	Name of Audio Source Profile for the first voiceprint.
audio_source_profile_2	Name of Audio Source Profile for the second voiceprint.
channel_scores[]	Array of scores for each audio channel. It contains only one item because Voiceprint should only contain data for one audio channel.

Channel score item description

channel	Channel index
scores[]	Array of scores. This response always contains only one score.
scores[]->score	LLR (Log-likelihood ratio) based on natural logarithm.

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1017User model not ready
1025An invalid value was specified for one of the header parameters in the request
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1015User model not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

LOCK Audio Source Profile (if parameters audio_source_profile_1 or audio_source_profile_2 are used)

POST /technologies/speakerid4/comparevpset (asynchronous)Analyze one voiceprint set

Compares the voiceprint set with itself. This request is asynchronous (see Asynchronous request).

The request body must contain only one voiceprint set.

To compare two different voiceprint sets use POST /technologies/speakerid4/comparevpsets

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
model	query	string	yes	Name of the SID4 model.
prune_matrix	query	string	no	`above` (results above and on diagonal will be 0) `below` (results below and on diagonal will be 0)
audio_source_profile	query	string	no	Name of the Audio Source Profile. If the profile name starts with a '/' symbol it is taken as a path in the storage.

Body

{
  "voiceprint_set": [
    {
      "voiceprint": <Base64 Data>
    },
    {
      "voiceprint": <Base64 Data>
    },
    ...
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint_set>
  <item>
    <voiceprint>[Base64 Data]</voiceprint>
  </item>
  <item>
    <voiceprint>[Base64 Data]</voiceprint>
  </item>
  ...
</voiceprint_set>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST -H "Content-Type:application/json" --data-binary @"voiceprint_set.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/comparevpset?model=L4&audio_source_profile=test_profile"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/speakerid4/comparevpset',
  uri_params: {
    model: 'L4',
    audio_source_profile: 'test_profile'
  },
  content: {
    "voiceprint_set": [
      {
        "voiceprint": "VlBUIAcAAAD9CAAA6AMAAAAAAAD3vHKT8LtfPk373b\/gMhG\/BAyNvXDZjD86XH0\/0FyCP1e6iD8zjba+OAAgv\/Jj3z0TL54+bm+0PiwUVb\/g6ErAE7jXPos6Mb8xYRy\/UEcAQGgoZT8eb+Q\/oGxIP88EBT5YrYY\/8WqWP\/0WrD\/xa44\/lomHP+yqjz+soYI\/RRgZPdoFtj9ZCmQ\/qKIEP7nuhL4Bl4O\/g9kJv1\/erb8gA1q+CsSRPzNga78qMo6\/kISNvwykbD9P+Jq\/zUWGPiVKAUDwvIq\/E6yPv8WYpr\/SpAa\/wbaJvXgpHL4QwJu95Wk5Pj5mXb7n8+49Xz2bPy3SSj+6Uvw+5ZgDP\/Fqsb\/KgiC+yadGP4lmFj53iwE\/ZpeRP9SwOD9tQWU+8yKRvW8RFz\/Jryy\/pgQnvxN4zb6GCCs\/rmQiP51l3z4hRp0\/JVOYv+oVE76B6gM+oLErv6imh7war3E\/zS\/OP4BF0r\/QAZA+IMgEPvM5hj\/dWYg+HRa5P+RkMr9I0rY+MEdWPrifzL+vmBi\/ihuNvjjj4b8yzEI\/17JnP78GvT9ZSgG\/rNqbvwD6Iz66ZRlAguRbPjwv9T7OE5o\/ok6Lvhdso79bJO+\/noI5vz\/xWb+Udvi8cfAdP3b6pD440NS+tTUdwMhpAjxSTH+\/DjDJPT4Lez2b7y0\/o3IYP8AHKT+rvRy\/YLigvBGtfb\/IUBe+KL3gv6mV2z+8g9G\/tFXdPppkKb0NeQA\/g\/oJQPTrbjweV7M+rbJqv\/IXv78oRE8+ET54v0uXs7\/8TIi\/RESXP48LjD8lN25AulqTv2LrtL\/6J6W+5QRrv971Zb9S1hnA+t1TPzOJED5GOTe\/di+6Pq7cQL\/tLCk+5IsBPt3n374WlqG\/t0Udvv9W9b8SyAo\/p343vylLSb8z4UO\/kttMv4ZwrD\/d7Hq\/WPo6Pz4bRz1kycM\/AGA3O5DIZb7Eqjc\/lYDnPejvH0D0d9G\/wvvCv1bu3j5uhKI\/CMK0PMX3RT9bUI2\/OJnSPcBppr5sGd0+IYtIv6o4ar+oxyG+tXTMPqkCmD+ty6a\/f+PyPmKR3r6ML+G\/rNxevgvMED8bS4A\/U\/oevp6Nar+UPR0\/1EYiwAovzj5O3ry\/teVFPu9Nk781WUO\/tQQ9QMQWGL+4LMe99A+hv\/67SD7kfD7ApnkWv\/TZnj4K2IE\/JyOev5qAz75dJ2e\/vp4Wv3OlXT8rO2a\/Hiz2P3olHb3nLgO\/uQpjP+02Rj8hGmg\/tsi6PdKfKD\/JHVQ\/zPsHv9YZjL1eVTs\/Y8Olv\/kNez61bb6\/7aICP9oqX7\/2BDu+sIGevy\/e+z4MwxQ+vThJvhqC4r84fdi\/SvSJvw=="
      },
      {
        "voiceprint": "VlBUIAcAAABIDAAA6AMAAAAAAAD4FigbpNHSPk1S2b\/4upC\/Jhv\/vliBYz82X1M\/LYy5P9BDMz90Izm\/oGe1PdWMlb7J2OG9CFQsv6H9Q79rIAzAjLFdP8Ra2b70OhXA+jK+PiT3hD\/e\/q4\/s8SHP8CyGD\/jzDw\/X+\/OPxSJHz8GWWM84v7DPyKyAj3ls+M+YDTDvk3UUz+R4D8\/4mesPgGjtT3mJ4e\/X9t0vxa8bz0hlYg+UbMEQNykDb+3ZUq\/m0mAv9i+tr1FrlG\/pIl\/PXZPJ0BPb+092GUMwEEnyr+igHU\/f43fPSkK8L3eZBa\/jG0bvzKBWb+JbVK\/obVlP4Z4dD\/0y8o8xEIQvqVdgr87EhBAIhsRQGbwL7+ePvg+dqBdPqw7JD+uzwQ\/cP\/Cvn+zrj8sgPe\/2LocvtNrhr90q3E\/i36iP+gHC77bQTO+Ji2MPt0nt76OY7q+1VHYPU3LSz4ePSa\/WSBEP0A6+r8Op4c\/3jQaP56PIb\/BvZa\/kFSuPyw33D4d0oK\/L\/4KP\/vfKL\/5aaS\/VIKXPxHj5T6RaJm+HUuPviNq1z82Jcs+DFtJP5X+JL\/f97k\/CLkYOlUMBb8IxZS+Gb9Xv9QVqr\/IN82\/L7MFP9cslzyvyKA\/k57gPhycQD64Fx4+RTlgPchBLjza3J2\/Tbsvv9IE1D4T9W4+AH4xv65yqr7adq68b+ZKPrJzrb1U\/\/a+0Jo2vhuVbj\/JZ\/i\/YNAdP9bONb\/3rNQ+EMJfP2YT+j5PRUU\/AHKRvwxnG7\/\/fio\/Xbndv3dEf78QOZG\/G2gsQPDLiT+Au\/A\/UdIrP9pn3b5JeQa\/3PaLvzh3tz7rTCrAWucWvWJk2j\/Nky4\/ez+EP2CWyb9Dc4U\/6aQpP+hPiD6UwE++7AS6P4dQB8BMOmc\/Qbu4Pz77U77SVoc\/6BcFP2afCz9ZbSi\/+z6UPzLRh72G2cM\/t9mPvuWDcr9qRFE+S5UcQDvrxj+PrpA\/5uOdv3vcSz+R2Aw\/12WUvCScIb\/vxJO\/8++tP2I4gr5fUkM\/vGqCv\/hcB0BLT8y9aX6ov9kOLT5koZW\/6ehyvep6pjyVJ6O\/vfRoPmoOab8R6vk\/biEAP6EDA0BQ+1g+Yq2+vyEjNUAxb4W\/xo5SP3w4nL7caIu+l+LqP14XPL4Ocdm+miuiP43SnD9BJFLAsHSrvwelOL17B7C\/yRbTvirTZT\/a7x+\/JxTpPWf6aT0mlmO\/85AgP4rLmj9cw6K\/zZChP\/ym6T4W3jA\/ligQwPF7n7\/Ewj0\/yK+gPhrjL78IKYY+H2jpP3gncj05e5++GHcrP3vK\/L4usla+ZFMDvVho4r4w2Ls\/lEfVP9p\/nL6mvdu\/gyGDvg=="
      }
    ]
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status Output

200OK

Example of a result matrix without using parameter prune_matrix

	VP₁	VP₂	VP_n
VP₁	13.458	4.455	-11.751
VP₂	4.455	14.398	2.785
VP_n	-11.751	2.785	16.492

Example of a result matrix with parameter prune_matrix=above

	VP₁	VP₂
VP₁	0	0
VP₂	4.455	0
VP_n	-11.751	2.785

Example of a result matrix with parameter prune_matrix=below

	VP₂	VP_n
VP₁	4.455	-11.751
VP₂	0	2.785
VP_n	0	0

/technologies/speakerid4/comparevpsets – compare voiceprint sets

{
   "result": {
     "version": ,
     "name": SpeakerIdentification4VoiceprintSetsCompareResult",
     "model": L4",
     "audio_source_profile_1": "profile_test",
     "audio_source_profile_2": "profile_test",
     "matrix": [
       [
         <vp1 x vp1>, <vp1 x vp2>, ..., <vp1 x vpN>
       ],
       [
         <vp2 x vp1>, <vp2 x vp2>, ..., <vp2 x vpN>
       ],
       ...,
       [
         <vpN x vp1>, <vpN x vp2>, ..., <vpN x vpN>
       ]
     ]
   }
 }

<?xml version='1.0' encoding='UTF-8'?>
 <result>
   <version>1</version>
   <name>SpeakerIdentification4VoiceprintSetsCompareResult</name>
   <model>L4</model>
   <audio_source_profile_1>profile_test</audio_source_profile_1>
   <audio_source_profile_2>profile_test</audio_source_profile_2>
   <matrix>
     <item>
       <item>[vp1 x vp1]</item>
       <item>[vp1 x vp2]</item>
       ...
       <item>[vp1 x vpN]</item>
     </item>
     <item>
       <item>[vp2 x vp1]</item>
       <item>[vp2 x vp2]</item>
       ...
       <item>[vp2 x vpN]</item>
     </item>
     ...
     <item>
       <item>[vpN x vp1]</item>
       <item>[vpN x vp2]</item>
       ...
       <item>[vpN x vpN]</item>
     </item>
     ...
   </matrix>
 </result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1025An invalid value was specified for one of the header parameters in the request
1019An invalid data was specified in the request content
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

404Not Found

1015User model not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

LOCK Audio Source Profile (if parameter audio_source_profile is used)

POST /technologies/speakerid4/comparevpsets (asynchronous)Analyze two voiceprint sets

Compares two voiceprint sets with each other. This request is asynchronous (see Asynchronous request).

The request body should contain two voiceprint sets.

To compare one voiceprint set to itself use POST /technologies/speakerid4/comparevpset

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
model	query	string	yes	Name of the SID4 model.
audio_source_profile_1	query	string	no	Name of the Audio Source Profile for the first voiceprint. If the profile name starts with a '/' symbol it is taken as a path in the storage.
audio_source_profile_2	query	string	no	Name of the Audio Source Profile for the second voiceprint set. If the profile name starts with a '/' symbol it is taken as a path in the storage.

Body

{
  "voiceprint_sets": [
    {
      "voiceprint_set": [
        {
          "voiceprint": <Base64 Data>
        },
        {
          "voiceprint": <Base64 Data>
        },
        ...
      ]
    },
    {
      "voiceprint_set": [
        {
          "voiceprint": <Base64 Data>
        },
        {
          "voiceprint": <Base64 Data>
        },
        ...
      ]
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint_sets>
  <item>
    <voiceprint_set>
      <item>
        <voiceprint>[Base64 Data]</voiceprint>
      </item>
      <item>
        <voiceprint>[Base64 Data]</voiceprint>
      </item>
      ...
    </voiceprint_set>
  </item>
  <item>
    <voiceprint_set>
      <item>
        <voiceprint>[Base64 Data]</voiceprint>
      </item>
      <item>
        <voiceprint>[Base64 Data]</voiceprint>
      </item>
      ...
    </voiceprint_set>
  </item>
</voiceprint_sets>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST -H "Content-Type:application/json" --data-binary @"voiceprint_sets.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/comparevpsets?model=L4&audio_source_profile_1=test_profile_1&audio_source_profile_2=test_profile_2"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/speakerid4/comparevpsets',
  uri_params: {
    model: 'L4',
    audio_source_profile_1: 'test_profile_1',
    audio_source_profile_2: 'test_profile_2'
  },
  content: {
    "voiceprint_sets": [
      {
        "voiceprint_set": [
          {
            "voiceprint": "VlBUIAcAAAD9CAAA6AMAAAAAAAD3vHKT8LtfPk373b\/gMhG\/BAyNvXDZjD86XH0\/0FyCP1e6iD8zjba+OAAgv\/Jj3z0TL54+bm+0PiwUVb\/g6ErAE7jXPos6Mb8xYRy\/UEcAQGgoZT8eb+Q\/oGxIP88EBT5YrYY\/8WqWP\/0WrD\/xa44\/lomHP+yqjz+soYI\/RRgZPdoFtj9ZCmQ\/qKIEP7nuhL4Bl4O\/g9kJv1\/erb8gA1q+CsSRPzNga78qMo6\/kISNvwykbD9P+Jq\/zUWGPiVKAUDwvIq\/E6yPv8WYpr\/SpAa\/wbaJvXgpHL4QwJu95Wk5Pj5mXb7n8+49Xz2bPy3SSj+6Uvw+5ZgDP\/Fqsb\/KgiC+yadGP4lmFj53iwE\/ZpeRP9SwOD9tQWU+8yKRvW8RFz\/Jryy\/pgQnvxN4zb6GCCs\/rmQiP51l3z4hRp0\/JVOYv+oVE76B6gM+oLErv6imh7war3E\/zS\/OP4BF0r\/QAZA+IMgEPvM5hj\/dWYg+HRa5P+RkMr9I0rY+MEdWPrifzL+vmBi\/ihuNvjjj4b8yzEI\/17JnP78GvT9ZSgG\/rNqbvwD6Iz66ZRlAguRbPjwv9T7OE5o\/ok6Lvhdso79bJO+\/noI5vz\/xWb+Udvi8cfAdP3b6pD440NS+tTUdwMhpAjxSTH+\/DjDJPT4Lez2b7y0\/o3IYP8AHKT+rvRy\/YLigvBGtfb\/IUBe+KL3gv6mV2z+8g9G\/tFXdPppkKb0NeQA\/g\/oJQPTrbjweV7M+rbJqv\/IXv78oRE8+ET54v0uXs7\/8TIi\/RESXP48LjD8lN25AulqTv2LrtL\/6J6W+5QRrv971Zb9S1hnA+t1TPzOJED5GOTe\/di+6Pq7cQL\/tLCk+5IsBPt3n374WlqG\/t0Udvv9W9b8SyAo\/p343vylLSb8z4UO\/kttMv4ZwrD\/d7Hq\/WPo6Pz4bRz1kycM\/AGA3O5DIZb7Eqjc\/lYDnPejvH0D0d9G\/wvvCv1bu3j5uhKI\/CMK0PMX3RT9bUI2\/OJnSPcBppr5sGd0+IYtIv6o4ar+oxyG+tXTMPqkCmD+ty6a\/f+PyPmKR3r6ML+G\/rNxevgvMED8bS4A\/U\/oevp6Nar+UPR0\/1EYiwAovzj5O3ry\/teVFPu9Nk781WUO\/tQQ9QMQWGL+4LMe99A+hv\/67SD7kfD7ApnkWv\/TZnj4K2IE\/JyOev5qAz75dJ2e\/vp4Wv3OlXT8rO2a\/Hiz2P3olHb3nLgO\/uQpjP+02Rj8hGmg\/tsi6PdKfKD\/JHVQ\/zPsHv9YZjL1eVTs\/Y8Olv\/kNez61bb6\/7aICP9oqX7\/2BDu+sIGevy\/e+z4MwxQ+vThJvhqC4r84fdi\/SvSJvw=="
          },
          {
            "voiceprint": "VlBUIAcAAABIDAAA6AMAAAAAAAD4FigbpNHSPk1S2b\/4upC\/Jhv\/vliBYz82X1M\/LYy5P9BDMz90Izm\/oGe1PdWMlb7J2OG9CFQsv6H9Q79rIAzAjLFdP8Ra2b70OhXA+jK+PiT3hD\/e\/q4\/s8SHP8CyGD\/jzDw\/X+\/OPxSJHz8GWWM84v7DPyKyAj3ls+M+YDTDvk3UUz+R4D8\/4mesPgGjtT3mJ4e\/X9t0vxa8bz0hlYg+UbMEQNykDb+3ZUq\/m0mAv9i+tr1FrlG\/pIl\/PXZPJ0BPb+092GUMwEEnyr+igHU\/f43fPSkK8L3eZBa\/jG0bvzKBWb+JbVK\/obVlP4Z4dD\/0y8o8xEIQvqVdgr87EhBAIhsRQGbwL7+ePvg+dqBdPqw7JD+uzwQ\/cP\/Cvn+zrj8sgPe\/2LocvtNrhr90q3E\/i36iP+gHC77bQTO+Ji2MPt0nt76OY7q+1VHYPU3LSz4ePSa\/WSBEP0A6+r8Op4c\/3jQaP56PIb\/BvZa\/kFSuPyw33D4d0oK\/L\/4KP\/vfKL\/5aaS\/VIKXPxHj5T6RaJm+HUuPviNq1z82Jcs+DFtJP5X+JL\/f97k\/CLkYOlUMBb8IxZS+Gb9Xv9QVqr\/IN82\/L7MFP9cslzyvyKA\/k57gPhycQD64Fx4+RTlgPchBLjza3J2\/Tbsvv9IE1D4T9W4+AH4xv65yqr7adq68b+ZKPrJzrb1U\/\/a+0Jo2vhuVbj\/JZ\/i\/YNAdP9bONb\/3rNQ+EMJfP2YT+j5PRUU\/AHKRvwxnG7\/\/fio\/Xbndv3dEf78QOZG\/G2gsQPDLiT+Au\/A\/UdIrP9pn3b5JeQa\/3PaLvzh3tz7rTCrAWucWvWJk2j\/Nky4\/ez+EP2CWyb9Dc4U\/6aQpP+hPiD6UwE++7AS6P4dQB8BMOmc\/Qbu4Pz77U77SVoc\/6BcFP2afCz9ZbSi\/+z6UPzLRh72G2cM\/t9mPvuWDcr9qRFE+S5UcQDvrxj+PrpA\/5uOdv3vcSz+R2Aw\/12WUvCScIb\/vxJO\/8++tP2I4gr5fUkM\/vGqCv\/hcB0BLT8y9aX6ov9kOLT5koZW\/6ehyvep6pjyVJ6O\/vfRoPmoOab8R6vk\/biEAP6EDA0BQ+1g+Yq2+vyEjNUAxb4W\/xo5SP3w4nL7caIu+l+LqP14XPL4Ocdm+miuiP43SnD9BJFLAsHSrvwelOL17B7C\/yRbTvirTZT\/a7x+\/JxTpPWf6aT0mlmO\/85AgP4rLmj9cw6K\/zZChP\/ym6T4W3jA\/ligQwPF7n7\/Ewj0\/yK+gPhrjL78IKYY+H2jpP3gncj05e5++GHcrP3vK\/L4usla+ZFMDvVho4r4w2Ls\/lEfVP9p\/nL6mvdu\/gyGDvg=="
          }
        ]
      }
    ]
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status

Output

200OK

Example result matrix:

		VP Set₂
		VP₁	VP₂	VP_m
VP Set₁	VP₁	-3.421	-1.531	-7.218
	VP₂	4.455	-0.972	-2.141
	VP₃	-1.305	-2.371	-5.714
	VP_n	-11.751	-2.785	-6.159

/technologies/speakerid4/clustervpset – analyze clusters in voiceprint set

{
   "result": {
     "version": 1,
     "name": "SpeakerIdentification4VoiceprintSetsCompareResult",
     "model": "L4",
     "audio_source_profile_1": "profile_test_1",
     "audio_source_profile_2": "profile_test_2",
     "matrix": [
       [
         <vpset1_vp1 x vpset2_vp1>,
         <vpset1_vp1 x vpset2_vp2>,
         ...,
         <vpset1_vp1 x vpset2_vpM>,
       ],
       [
         <vpset1_vp2 x vpset2_vp1>,
         <vpset1_vp2 x vpset2_vp2>
         ...,
         <vpset1_vp2 x vpset2_vpM>,
       ],
       ...,
       [
         <vpset1_vpN x vpset2_vp1>,
         <vpset1_vpN x vpset2_vp2>
         ...,
         <vpset1_vpN x vpset2_vpM>,
       ],
     ]
   }
 }

<?xml version='1.0' encoding='UTF-8'?>
 <result>
   <version>1</version>
   <name>SpeakerIdentification4VoiceprintSetsCompareResult</name>
   <model>L4</model>
   <audio_source_profile_1>profile_test_1</audio_source_profile_1>
   <audio_source_profile_2>profile_test_2</audio_source_profile_2>
   <matrix>
     <item>
       <item>[vpset1_vp1 x vpset2_vp1]</item>
       <item>[vpset1_vp1 x vpset2_vp2]</item>
       ...,
       <item>[vpset1_vp1 x vpset2_vpN]</item>
     </item>
     <item>
       <item>[vpset1_vp2 x vpset2_vp1]</item>
       <item>[vpset1_vp2 x vpset2_vp2]</item>
       ...,
       <item>[vpset1_vp2 x vpset2_vpN]</item>
     </item>
     ...,
     <item>
       <item>[vpset1_vpN x vpset2_vp1]</item>
       <item>[vpset1_vpN x vpset2_vp2]</item>
       ...,
       <item>[vpset1_vpN x vpset2_vpM]</item>
     </item>
   </matrix>
 </result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1025An invalid value was specified for one of the header parameters in the request
1019An invalid data was specified in the request content
1017User model not ready
1060The capacity for technology has been exceeded
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

403Forbidden

1011Execute access forbidden

404Not Found

1015User model not found

405Method Not Allowed

1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

LOCK Audio Source Profile (if parameters audio_source_profile_1 or audio_source_profile_2 is used)

POST /technologies/speakerid4/clustervpset (asynchronous)Analyze clusters in one voiceprint set

Compares the voiceprint set with itself and cluster the voiceprints. This request is asynchronous (see Asynchronous request).

The request body must contain only one voiceprint set.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
model	query	string	yes	Name of the SID4 model.
audio_source_profile	query	string	no	Name of the Audio Source Profile. If the profile name starts with a '/' symbol it is taken as a path in the storage.

Body

{
  "voiceprint_set": [
    {
      "voiceprint": <Base64 Data>
    },
    {
      "voiceprint": <Base64 Data>
    },
    ...
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint_set>
  <item>
    <voiceprint>[Base64 Data]</voiceprint>
  </item>
  <item>
    <voiceprint>[Base64 Data]</voiceprint>
  </item>
  ...
</voiceprint_set>

Example

/technologies/speakerid4/vpinfo – information about voiceprint

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST -H "Content-Type:application/json" --data-binary @"voiceprint_set.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/clustervpset?model=L4&audio_source_profile=test_profile"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/speakerid4/clustervpset',
  uri_params: {
    model: 'L4',
    audio_source_profile: 'test_profile'
  },
  content: {
    "voiceprint_set": [
      {
        "voiceprint": "VlBUIAcAAAD9CAAA6AMAAAAAAAD3vHKT8LtfPk373b\/gMhG\/BAyNvXDZjD86XH0\/0FyCP1e6iD8zjba+OAAgv\/Jj3z0TL54+bm+0PiwUVb\/g6ErAE7jXPos6Mb8xYRy\/UEcAQGgoZT8eb+Q\/oGxIP88EBT5YrYY\/8WqWP\/0WrD\/xa44\/lomHP+yqjz+soYI\/RRgZPdoFtj9ZCmQ\/qKIEP7nuhL4Bl4O\/g9kJv1\/erb8gA1q+CsSRPzNga78qMo6\/kISNvwykbD9P+Jq\/zUWGPiVKAUDwvIq\/E6yPv8WYpr\/SpAa\/wbaJvXgpHL4QwJu95Wk5Pj5mXb7n8+49Xz2bPy3SSj+6Uvw+5ZgDP\/Fqsb\/KgiC+yadGP4lmFj53iwE\/ZpeRP9SwOD9tQWU+8yKRvW8RFz\/Jryy\/pgQnvxN4zb6GCCs\/rmQiP51l3z4hRp0\/JVOYv+oVE76B6gM+oLErv6imh7war3E\/zS\/OP4BF0r\/QAZA+IMgEPvM5hj\/dWYg+HRa5P+RkMr9I0rY+MEdWPrifzL+vmBi\/ihuNvjjj4b8yzEI\/17JnP78GvT9ZSgG\/rNqbvwD6Iz66ZRlAguRbPjwv9T7OE5o\/ok6Lvhdso79bJO+\/noI5vz\/xWb+Udvi8cfAdP3b6pD440NS+tTUdwMhpAjxSTH+\/DjDJPT4Lez2b7y0\/o3IYP8AHKT+rvRy\/YLigvBGtfb\/IUBe+KL3gv6mV2z+8g9G\/tFXdPppkKb0NeQA\/g\/oJQPTrbjweV7M+rbJqv\/IXv78oRE8+ET54v0uXs7\/8TIi\/RESXP48LjD8lN25AulqTv2LrtL\/6J6W+5QRrv971Zb9S1hnA+t1TPzOJED5GOTe\/di+6Pq7cQL\/tLCk+5IsBPt3n374WlqG\/t0Udvv9W9b8SyAo\/p343vylLSb8z4UO\/kttMv4ZwrD\/d7Hq\/WPo6Pz4bRz1kycM\/AGA3O5DIZb7Eqjc\/lYDnPejvH0D0d9G\/wvvCv1bu3j5uhKI\/CMK0PMX3RT9bUI2\/OJnSPcBppr5sGd0+IYtIv6o4ar+oxyG+tXTMPqkCmD+ty6a\/f+PyPmKR3r6ML+G\/rNxevgvMED8bS4A\/U\/oevp6Nar+UPR0\/1EYiwAovzj5O3ry\/teVFPu9Nk781WUO\/tQQ9QMQWGL+4LMe99A+hv\/67SD7kfD7ApnkWv\/TZnj4K2IE\/JyOev5qAz75dJ2e\/vp4Wv3OlXT8rO2a\/Hiz2P3olHb3nLgO\/uQpjP+02Rj8hGmg\/tsi6PdKfKD\/JHVQ\/zPsHv9YZjL1eVTs\/Y8Olv\/kNez61bb6\/7aICP9oqX7\/2BDu+sIGevy\/e+z4MwxQ+vThJvhqC4r84fdi\/SvSJvw=="
      },
      {
        "voiceprint": "VlBUIAcAAABIDAAA6AMAAAAAAAD4FigbpNHSPk1S2b\/4upC\/Jhv\/vliBYz82X1M\/LYy5P9BDMz90Izm\/oGe1PdWMlb7J2OG9CFQsv6H9Q79rIAzAjLFdP8Ra2b70OhXA+jK+PiT3hD\/e\/q4\/s8SHP8CyGD\/jzDw\/X+\/OPxSJHz8GWWM84v7DPyKyAj3ls+M+YDTDvk3UUz+R4D8\/4mesPgGjtT3mJ4e\/X9t0vxa8bz0hlYg+UbMEQNykDb+3ZUq\/m0mAv9i+tr1FrlG\/pIl\/PXZPJ0BPb+092GUMwEEnyr+igHU\/f43fPSkK8L3eZBa\/jG0bvzKBWb+JbVK\/obVlP4Z4dD\/0y8o8xEIQvqVdgr87EhBAIhsRQGbwL7+ePvg+dqBdPqw7JD+uzwQ\/cP\/Cvn+zrj8sgPe\/2LocvtNrhr90q3E\/i36iP+gHC77bQTO+Ji2MPt0nt76OY7q+1VHYPU3LSz4ePSa\/WSBEP0A6+r8Op4c\/3jQaP56PIb\/BvZa\/kFSuPyw33D4d0oK\/L\/4KP\/vfKL\/5aaS\/VIKXPxHj5T6RaJm+HUuPviNq1z82Jcs+DFtJP5X+JL\/f97k\/CLkYOlUMBb8IxZS+Gb9Xv9QVqr\/IN82\/L7MFP9cslzyvyKA\/k57gPhycQD64Fx4+RTlgPchBLjza3J2\/Tbsvv9IE1D4T9W4+AH4xv65yqr7adq68b+ZKPrJzrb1U\/\/a+0Jo2vhuVbj\/JZ\/i\/YNAdP9bONb\/3rNQ+EMJfP2YT+j5PRUU\/AHKRvwxnG7\/\/fio\/Xbndv3dEf78QOZG\/G2gsQPDLiT+Au\/A\/UdIrP9pn3b5JeQa\/3PaLvzh3tz7rTCrAWucWvWJk2j\/Nky4\/ez+EP2CWyb9Dc4U\/6aQpP+hPiD6UwE++7AS6P4dQB8BMOmc\/Qbu4Pz77U77SVoc\/6BcFP2afCz9ZbSi\/+z6UPzLRh72G2cM\/t9mPvuWDcr9qRFE+S5UcQDvrxj+PrpA\/5uOdv3vcSz+R2Aw\/12WUvCScIb\/vxJO\/8++tP2I4gr5fUkM\/vGqCv\/hcB0BLT8y9aX6ov9kOLT5koZW\/6ehyvep6pjyVJ6O\/vfRoPmoOab8R6vk\/biEAP6EDA0BQ+1g+Yq2+vyEjNUAxb4W\/xo5SP3w4nL7caIu+l+LqP14XPL4Ocdm+miuiP43SnD9BJFLAsHSrvwelOL17B7C\/yRbTvirTZT\/a7x+\/JxTpPWf6aT0mlmO\/85AgP4rLmj9cw6K\/zZChP\/ym6T4W3jA\/ligQwPF7n7\/Ewj0\/yK+gPhrjL78IKYY+H2jpP3gncj05e5++GHcrP3vK\/L4usla+ZFMDvVho4r4w2Ls\/lEfVP9p\/nL6mvdu\/gyGDvg=="
      }
    ]
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "SpeakerIdentification4VoiceprintSetClustersResult", "model": "L4", "audio_source_profile": "profile_test", "clusters": [ { "members": [ 0, 4 ] }, { "members": [ 1, 2 ] }, { "members": [ 3 ] } ] } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>1</version> <name>SpeakerIdentification4VoiceprintSetClustersResult</name> <model>L4</model> <audio_source_profile>profile_test</audio_source_profile> <clusters> <item> <members> <item>0</item> <item>4</item> </members> </item> <item> <members> <item>1</item> <item>2</item> </members> </item> <item> <members> <item>3</item> </members> </item> </clusters> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1025An invalid value was specified for one of the header parameters in the request 1019An invalid data was specified in the request content 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

LOCK Audio Source Profile (if parameter audio_source_profile is used)

POST /technologies/speakerid4/vpinfo Information about voiceprint

Returns information about the voiceprint posted in the request body. The voiceprint can contain multiple sub-voiceprints. For each sub-voiceprint the server returns version, speech_length (in seconds) and user_data (base64 encoded).

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	yes	`application/json` for JSON content (Default value) `application/xml` for XML content `application/octet-stream` for raw voiceprint content

Body

{
  "voiceprint": "<Base64 Data>"
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint>[Base64 Data]</voiceprint>

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary @"voiceprint.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/vpinfo"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$voiceprint = array(
  'voiceprint' => 'VlBUIAcAAAD9CAAA6AMAAAAAAAD3vHKT8LtfPk373b/gMhG/BAyNvXDZjD86XH0/0FyCP1e6iD8zjba+OAAgv/Jj3z0TL54+bm+0PiwUVb/g6ErAE7jXPos6Mb8xYRy/UEcAQGgoZT8eb+Q/oGxIP88EBT5YrYY/8WqWP/0WrD/xa44/lomHP+yqjz+soYI/RRgZPdoFtj9ZCmQ/qKIEP7nuhL4Bl4O/g9kJv1/erb8gA1q+CsSRPzNga78qMo6/kISNvwykbD9P+Jq/zUWGPiVKAUDwvIq/E6yPv8WYpr/SpAa/wbaJvXgpHL4QwJu95Wk5Pj5mXb7n8+49Xz2bPy3SSj+6Uvw+5ZgDP/Fqsb/KgiC+yadGP4lmFj53iwE/ZpeRP9SwOD9tQWU+8yKRvW8RFz/Jryy/pgQnvxN4zb6GCCs/rmQiP51l3z4hRp0/JVOYv+oVE76B6gM+oLErv6imh7war3E/zS/OP4BF0r/QAZA+IMgEPvM5hj/dWYg+HRa5P+RkMr9I0rY+MEdWPrifzL+vmBi/ihuNvjjj4b8yzEI/17JnP78GvT9ZSgG/rNqbvwD6Iz66ZRlAguRbPjwv9T7OE5o/ok6Lvhdso79bJO+/noI5vz/xWb+Udvi8cfAdP3b6pD440NS+tTUdwMhpAjxSTH+/DjDJPT4Lez2b7y0/o3IYP8AHKT+rvRy/YLigvBGtfb/IUBe+KL3gv6mV2z+8g9G/tFXdPppkKb0NeQA/g/oJQPTrbjweV7M+rbJqv/IXv78oRE8+ET54v0uXs7/8TIi/RESXP48LjD8lN25AulqTv2LrtL/6J6W+5QRrv971Zb9S1hnA+t1TPzOJED5GOTe/di+6Pq7cQL/tLCk+5IsBPt3n374WlqG/t0Udvv9W9b8SyAo/p343vylLSb8z4UO/kttMv4ZwrD/d7Hq/WPo6Pz4bRz1kycM/AGA3O5DIZb7Eqjc/lYDnPejvH0D0d9G/wvvCv1bu3j5uhKI/CMK0PMX3RT9bUI2/OJnSPcBppr5sGd0+IYtIv6o4ar+oxyG+tXTMPqkCmD+ty6a/f+PyPmKR3r6ML+G/rNxevgvMED8bS4A/U/oevp6Nar+UPR0/1EYiwAovzj5O3ry/teVFPu9Nk781WUO/tQQ9QMQWGL+4LMe99A+hv/67SD7kfD7ApnkWv/TZnj4K2IE/JyOev5qAz75dJ2e/vp4Wv3OlXT8rO2a/Hiz2P3olHb3nLgO/uQpjP+02Rj8hGmg/tsi6PdKfKD/JHVQ/zPsHv9YZjL1eVTs/Y8Olv/kNez61bb6/7aICP9oqX7/2BDu+sIGevy/e+z4MwxQ+vThJvhqC4r84fdi/SvSJvw=='
);

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($voiceprint),
    'ignore_errors' => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/vpinfo",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

/technologies/speakerid4/vpmerge – merge set of voiceprints

{
  "result": {
    "version": 1,
    "name": "VoiceprintInfoResult",
    "voiceprint_info": [
      {
        "index": 1,
        "version": 37,
        "speech_length": 119.49997,
        "user_data": "<Base64 encoded user data>"
      }
      ...
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>VoiceprintInfoResult</name>
  <voiceprint_info>
    <item>
      <index>1</index>
      <version>37</version>
      <speech_length>119.49997</speech_length>
      <user_data>[Base64 encoded user data]</user_data>
    </item>
    ...
  </voiceprint_info>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1025An invalid value was specified for one of the header parameters in the request
1018The requested URI requires content
1019An invalid data was specified in the request content
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

POST /technologies/speakerid4/vpmerge Merge set of the voiceprints to new one.

Merges a set of voiceprints to a single new voiceprint. The new voiceprint is a combination of all voiceprints in the set. All voiceprints in the set have to be of the same SID4 model. It uses a weighted arithmetic mean. It is accomplished by weighting a particular voiceprint by its speech length. Keep in mind that the resulting voiceprint is not the same as the voiceprint extracted from a file created by concatenating all individual audio files into one, but it is very similar to it.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content

Body

{
  "voiceprint_set": [
    {
      "voiceprint": <Base64 Data>
    },
    {
      "voiceprint": <Base64 Data>
    },
    ...
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<voiceprint_set>
  <voiceprint>
    [Base64 Data]
  </voiceprint>
  <voiceprint>
    [Base64 Data]
  </voiceprint>
  ...
</voiceprint_set>

Example

/technologies/speakerid4/benchmark – speaker identification 4 benchmark

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST -H "Content-Type:application/json" --data-binary @"voiceprint_set.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/vpmerge"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'POST',
  uri_path: '/technologies/speakerid4/vpmerge',
  content: {
    "voiceprint_set": [
      {
        "voiceprint": "VlBUIAcAAAD9CAAA6AMAAAAAAAD3vHKT8LtfPk373b\/gMhG\/BAyNvXDZjD86XH0\/0FyCP1e6iD8zjba+OAAgv\/Jj3z0TL54+bm+0PiwUVb\/g6ErAE7jXPos6Mb8xYRy\/UEcAQGgoZT8eb+Q\/oGxIP88EBT5YrYY\/8WqWP\/0WrD\/xa44\/lomHP+yqjz+soYI\/RRgZPdoFtj9ZCmQ\/qKIEP7nuhL4Bl4O\/g9kJv1\/erb8gA1q+CsSRPzNga78qMo6\/kISNvwykbD9P+Jq\/zUWGPiVKAUDwvIq\/E6yPv8WYpr\/SpAa\/wbaJvXgpHL4QwJu95Wk5Pj5mXb7n8+49Xz2bPy3SSj+6Uvw+5ZgDP\/Fqsb\/KgiC+yadGP4lmFj53iwE\/ZpeRP9SwOD9tQWU+8yKRvW8RFz\/Jryy\/pgQnvxN4zb6GCCs\/rmQiP51l3z4hRp0\/JVOYv+oVE76B6gM+oLErv6imh7war3E\/zS\/OP4BF0r\/QAZA+IMgEPvM5hj\/dWYg+HRa5P+RkMr9I0rY+MEdWPrifzL+vmBi\/ihuNvjjj4b8yzEI\/17JnP78GvT9ZSgG\/rNqbvwD6Iz66ZRlAguRbPjwv9T7OE5o\/ok6Lvhdso79bJO+\/noI5vz\/xWb+Udvi8cfAdP3b6pD440NS+tTUdwMhpAjxSTH+\/DjDJPT4Lez2b7y0\/o3IYP8AHKT+rvRy\/YLigvBGtfb\/IUBe+KL3gv6mV2z+8g9G\/tFXdPppkKb0NeQA\/g\/oJQPTrbjweV7M+rbJqv\/IXv78oRE8+ET54v0uXs7\/8TIi\/RESXP48LjD8lN25AulqTv2LrtL\/6J6W+5QRrv971Zb9S1hnA+t1TPzOJED5GOTe\/di+6Pq7cQL\/tLCk+5IsBPt3n374WlqG\/t0Udvv9W9b8SyAo\/p343vylLSb8z4UO\/kttMv4ZwrD\/d7Hq\/WPo6Pz4bRz1kycM\/AGA3O5DIZb7Eqjc\/lYDnPejvH0D0d9G\/wvvCv1bu3j5uhKI\/CMK0PMX3RT9bUI2\/OJnSPcBppr5sGd0+IYtIv6o4ar+oxyG+tXTMPqkCmD+ty6a\/f+PyPmKR3r6ML+G\/rNxevgvMED8bS4A\/U\/oevp6Nar+UPR0\/1EYiwAovzj5O3ry\/teVFPu9Nk781WUO\/tQQ9QMQWGL+4LMe99A+hv\/67SD7kfD7ApnkWv\/TZnj4K2IE\/JyOev5qAz75dJ2e\/vp4Wv3OlXT8rO2a\/Hiz2P3olHb3nLgO\/uQpjP+02Rj8hGmg\/tsi6PdKfKD\/JHVQ\/zPsHv9YZjL1eVTs\/Y8Olv\/kNez61bb6\/7aICP9oqX7\/2BDu+sIGevy\/e+z4MwxQ+vThJvhqC4r84fdi\/SvSJvw=="
      },
      {
        "voiceprint": "VlBUIAcAAABIDAAA6AMAAAAAAAD4FigbpNHSPk1S2b\/4upC\/Jhv\/vliBYz82X1M\/LYy5P9BDMz90Izm\/oGe1PdWMlb7J2OG9CFQsv6H9Q79rIAzAjLFdP8Ra2b70OhXA+jK+PiT3hD\/e\/q4\/s8SHP8CyGD\/jzDw\/X+\/OPxSJHz8GWWM84v7DPyKyAj3ls+M+YDTDvk3UUz+R4D8\/4mesPgGjtT3mJ4e\/X9t0vxa8bz0hlYg+UbMEQNykDb+3ZUq\/m0mAv9i+tr1FrlG\/pIl\/PXZPJ0BPb+092GUMwEEnyr+igHU\/f43fPSkK8L3eZBa\/jG0bvzKBWb+JbVK\/obVlP4Z4dD\/0y8o8xEIQvqVdgr87EhBAIhsRQGbwL7+ePvg+dqBdPqw7JD+uzwQ\/cP\/Cvn+zrj8sgPe\/2LocvtNrhr90q3E\/i36iP+gHC77bQTO+Ji2MPt0nt76OY7q+1VHYPU3LSz4ePSa\/WSBEP0A6+r8Op4c\/3jQaP56PIb\/BvZa\/kFSuPyw33D4d0oK\/L\/4KP\/vfKL\/5aaS\/VIKXPxHj5T6RaJm+HUuPviNq1z82Jcs+DFtJP5X+JL\/f97k\/CLkYOlUMBb8IxZS+Gb9Xv9QVqr\/IN82\/L7MFP9cslzyvyKA\/k57gPhycQD64Fx4+RTlgPchBLjza3J2\/Tbsvv9IE1D4T9W4+AH4xv65yqr7adq68b+ZKPrJzrb1U\/\/a+0Jo2vhuVbj\/JZ\/i\/YNAdP9bONb\/3rNQ+EMJfP2YT+j5PRUU\/AHKRvwxnG7\/\/fio\/Xbndv3dEf78QOZG\/G2gsQPDLiT+Au\/A\/UdIrP9pn3b5JeQa\/3PaLvzh3tz7rTCrAWucWvWJk2j\/Nky4\/ez+EP2CWyb9Dc4U\/6aQpP+hPiD6UwE++7AS6P4dQB8BMOmc\/Qbu4Pz77U77SVoc\/6BcFP2afCz9ZbSi\/+z6UPzLRh72G2cM\/t9mPvuWDcr9qRFE+S5UcQDvrxj+PrpA\/5uOdv3vcSz+R2Aw\/12WUvCScIb\/vxJO\/8++tP2I4gr5fUkM\/vGqCv\/hcB0BLT8y9aX6ov9kOLT5koZW\/6ehyvep6pjyVJ6O\/vfRoPmoOab8R6vk\/biEAP6EDA0BQ+1g+Yq2+vyEjNUAxb4W\/xo5SP3w4nL7caIu+l+LqP14XPL4Ocdm+miuiP43SnD9BJFLAsHSrvwelOL17B7C\/yRbTvirTZT\/a7x+\/JxTpPWf6aT0mlmO\/85AgP4rLmj9cw6K\/zZChP\/ym6T4W3jA\/ligQwPF7n7\/Ewj0\/yK+gPhrjL78IKYY+H2jpP3gncj05e5++GHcrP3vK\/L4usla+ZFMDvVho4r4w2Ls\/lEfVP9p\/nL6mvdu\/gyGDvg=="
      }
    ]
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "VoiceprintMergeResult", "voiceprint": <Base64 Data>, "speech_length": 12.4 } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>VoiceprintMergeResult</name> <voiceprint>[Base64 Data]</voiceprint> <speech_length>12.4</speech_length> </result>
400Bad Request	1018The requested URI requires content 1025An invalid value was specified for one of the header parameters in the request 1019An invalid data was specified in the request content 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication

GET /technologies/speakerid4/benchmark (asynchronous)Speaker identification 4 Benchmark

Benchmark the Speaker Identification 4 technology with the default set of recordings or a user-specified recording (by parameter path). Only speed of extraction is measured.

Parameters

Name	Parameter Type	Data Type	Required	Description
model	query	string	yes	Name of Speaker Identification 4 technology model.
path	query	string	no	Server path to the audio file. If not specified, default recordings will be used.

Body

empty content

Example

/technologies/speakerid4/speakermodels – list of speaker models

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/benchmark?model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 *
 * JavaScript code:
 */
var options = {
  method: 'GET',
  uri_path: '/technologies/speakerid/benchmark',
  uri_params: {
    model: 'L4'
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "SpeakerIdentification4BenchmarkResult", "dataset_version": "1.0", "model_name": "S", "benchmark_result": { "processed_length": 21.31999969482422, "processing_time": 0.48091199999999995, "faster_than_realtime": 44.549944615190896 }, "cpu_info": { "vendor": "GenuineIntel", "brand": "Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz", "n_cores": 4, "n_logical_cores": 4, "l1_data_cache": 32768, "l1_instruction_cache": 32768, "l2_cache": 262144, "l3_cache": 6291456 }, "memory_info": { "total_ram": 16623747072, "free_ram": 5028855808, "total_swap": 0, "free_swap": 0 } } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>SpeakerIdentification4BenchmarkResult</name> <dataset_version>1.0</dataset_version> <model_name>S</model_name> <benchmark_result> <processed_length>21.31999969482422</processed_length> <processing_time>0.48091199999999995</processing_time> <faster_than_realtime>44.549944615190896</faster_than_realtime> </benchmark_result> <cpu_info> <vendor>GenuineIntel</vendor> <brand>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</brand> <n_cores>4</n_cores> <n_logical_cores>4</n_logical_cores> <l1_data_cache>32768</l1_data_cache> <l1_instruction_cache>32768</l1_instruction_cache> <l2_cache>262144</l2_cache> <l3_cache>6291456</l3_cache> </cpu_info> <memory_info> <total_ram>16623747072</total_ram> <free_ram>4938498048</free_ram> <total_swap>0</total_swap> <free_swap>0</free_swap> </memory_info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Voice Activity Detection (VAD)

Resource locker

LOCK Analyzed file (if parameter path is used)

GET /technologies/speakerid4/speakermodels List of speaker models

Returns the list of speaker models and groups available for speaker identification. Speaker models and groups are shared by both SID and SID4.

Body

empty content

Example

/technologies/speakerid4/speakermodels/{name} – information about the model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 1, "name": "SpeakerIdentificationModelsResult", "models": [ "model1", "model2" ], "groups": [ "all", "group1" ] } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>1</version> <name>SpeakerIdentificationModelsResult</name> <models> <item>model1</item> <item>model2</item> </models> <groups> <item>all</item> <item>group1</item> </groups> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

GET /technologies/speakerid4/speakermodels/{name} Information about speaker model

Returns the list of recordings and metafiles included in a speaker model. Speaker models are shared by both SID and SID4.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Determines the speaker model name.

Body

empty content

Example

POST /technologies/speakerid4/speakermodels/{name} Add new speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 5, "name": "SpeakerIdentificationModelInfo", "speaker_model": "model1", "is_ready": [ "S", "L" ], "is_calibrated": [ { "model": "S", "calibration_set": "calibset", "max_fa_rate": 0.1 } ], "member_of_groups": [ "all", "group1" ], "files": [ { "name": "david_1.wav", "last_modified": "2016-01-22T08:36:00Z", "created": "2016-01-22T08:36:00Z", "size": 492204, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 30.76, "n_channels": 1, "format": "lin16" } ], "metafiles": [ { "name": "david_1.txt", "last_modified": "2015-09-15T12:33:02Z", "created": "2015-09-15T12:33:02Z", "size": 100, "is_directory": false, "is_registered": true } ] } } <?xml version="1.0"?> <result> <version>5</version> <name>SpeakerIdentificationModelInfo</name> <speaker_model>model1</speaker_model> <is_ready> <item>S</item> <item>L</item> </is_ready> <is_calibrated> <item> <model>S</model> <calibration_set>calibset</calibration_set> <max_fa_rate>0.1</max_fa_rate> </item> </is_calibrated> <member_of_groups> <item>all</item> <item>group1</item> </member_of_groups> <files> <item> <name>david_1.wav</name> <last_modified>2016-01-22T08:36:00Z</last_modified> <created>2016-01-22T08:36:00Z</created> <size>492204</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>30.76</length> <n_channels>1</n_channels> <format>lin16</format> </item> </files> <metafiles> <item> <name>david_1.txt</name> <last_modified>2015-09-15T12:33:02Z</last_modified> <created>2015-09-15T12:33:02Z</created> <size>100</size> <is_directory>false</is_directory> <is_registered>true</is_registered> </item> </metafiles> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Creates a new empty speaker model. Speaker models are shared by both SID and SID4.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Determines the speaker model name

Body

empty content

Example

DELETE /technologies/speakerid4/speakermodels/{name} Remove speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1051Invalid path syntax 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Removes a speaker model. All contained recordings, metafiles and related results are deleted. Speaker models are shared by both SID and SID4.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Determines the speaker model name.

Body

empty content

Example

/technologies/speakerid4/speakermodels/{name}/prepare – prepares speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker model specified by name in request path

PUT /technologies/speakerid4/speakermodels/{name}/prepare (asynchronous)Prepare speaker model

Prepares the speaker model. It is necessary to prepare a speaker model before comparing it with voiceprints or using it in stream. A speaker model is prepared automatically when it is used in the GET /technologies/speakerid4 request. This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
model	query	string	yes	Name of the SID4 model.

Body

empty content

Example

/technologies/speakerid4/speakermodels/{name}/audiofile – speaker model audio file

curl -H "X-SessionID:YOUR_SESSION_ID" -X PUT "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKERMODEL_NAME/prepare?model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 */
var speakermodel_name = 'test';
var options = {
  method: 'PUT',
  uri_path: '/technologies/speakerid4/speakermodels/' + speakermodel_name + '/prepare',
  uri_params: {
    model: 'L4',
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1017User model not ready 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1033Unable to prepare speaker model

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)

Resource locker

LOCK Speaker model specified by name in request path

GET /technologies/speakerid4/speakermodels/{name}/audiofile Download recording from model

Downloads recording from a speaker model. Specific recording is determined by the path parameter. Note that query parameter path here does not refer to the location of the recording on server, but it is the name of your recording within the speaker model. Therefore, the name of the recording should not contain any slash characters ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
path	query	string	yes	Name of recording in speaker model.

Body

empty content

Example

POST /technologies/speakerid4/speakermodels/{name}/audiofile Add audio file to speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME/audiofile?path=AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the Phonexia Speech Engine
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/audiofile?path=$PATH",
  false,
  $context
);

file_put_contents('./audio.wav', $response); //= audio file saved on the PHP server
?>

Available responses

HTTP Status	Output
200OK	AUDIO DATA
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Uploads audio file to speaker model. The request body contains audio file data. Speaker model is automatically created if it does not exist. Note that query parameter path here does not refer to the location of the recording on server, but it is the name of your recording within the speaker model. Therefore, the name of the recording should not contain any slash characters ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
path	query	string	yes	Name of recording in speaker model.

Body

AUDIO DATA

Example

DELETE /technologies/speakerid4/speakermodels/{name}/audiofile Remove recording from speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST --data-binary "@FILE_PATH" "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME/audiofile?path=AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= destination path to the audiofile on the Phonexia Speech Engine
$SPEAKER_MODEL_NAME = "test";

$audio = file_get_contents("./audio.wav"); //= path to the source file on the PHP server

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: audio/wav',
    'content'       => $audio,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/audiofile?path=$PATH",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1039It was necessary to rename uploaded file but it could not be done, because file with same name already exists 1038Resource is locked 1051Invalid path syntax 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
403Forbidden	1063Access to file is forbidden
405Method Not Allowed	1009Technology is not supported by server
413Request Entity Too Large	1014Size of uploaded file exceeds size limit
415Unsupported Media Type	1007Unsupported audio format

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker model specified by name in request path

Removes recording from speaker model. Recording is determined by the path parameter. Note that query parameter path here does not refer to the location of the recording on server, but it is the name of your recording within the speaker model. Therefore, the name of the recording should not contain any slash characters ('/'), as it has no effect on the recording location in server's storage.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
path	query	string	yes	Name of recording in speaker model.

Body

empty content

Example

/technologies/speakerid4/speakermodels/{name}/metafile – speaker model metafile

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME/audiofile?path=AUDIO_FILE.wav"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/AUDIO_FILE.wav";  //= path to the audio file on the Phonexia Speech Engine
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/audiofile?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker model specified by name in request path

GET /technologies/speakerid4/speakermodels/{name}/metafile Download metafile from speaker model

Downloads a metafile from a speaker model. The metafile is determined by the path parameter. Note that the parameter path in the request does not refer to the location of the metafile on the server, but it is the name of the metafile within the speaker model. Therefore, the name of the metafile must not contain any slashes ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
path	query	string	yes	Name of metafile in speaker model.

Body

empty content

Example

POST /technologies/speakerid4/speakermodels/{name}/metafile Add metafile to speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME/metafile?path=METAFILE"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/METAFILE";  //= path to the meta file on the Phonexia Speech Engine
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/metafile?path=$PATH",
  false,
  $context
);

file_put_contents('./METAFILE', $response); //= audio file saved on the PHP server
?>

Available responses

HTTP Status	Output
200OK	METADATA
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Uploads a metafile to a speaker model. The request body contains the metafile data. Note that the parameter path in the request does not refer to the location of the metafile on the server, but it is the name of the metafile within the speaker model. Therefore, the name of the metafile must not contain any slashes ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
path	query	string	yes	Name of the metafile in speaker model.

Body

metafile

Example

DELETE /technologies/speakerid4/speakermodels/{name}/metafile Remove metafile from speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST --data-binary "@FILE_PATH" "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME/metafile?path=METAFILE"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/METAFILE";  //= destination path to the meta file on the Phonexia Speech Engine
$SPEAKER_MODEL_NAME = "test";

$audio = file_get_contents("./METAFILE"); //= path to the source file on the PHP server

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: audio/wav',
    'content'       => $audio,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/metafile?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server
413Request Entity Too Large	1014Size of uploaded file exceeds size limit

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Removes a metafile from a speaker model. The metafile is determined by the path parameter. Note that the parameter path in the request does not refer to the location of the metafile on the server, but it is the name of the metafile within the speaker model. Therefore, the name of the metafile must not contain any slashes ('/').

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
path	query	string	yes	Name of the metafile in speaker model.

Body

empty content

Example

/technologies/speakerid4/speakermodels/{name}/voiceprint – voiceprint in speaker model

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/SPEAKER_MODEL_NAME/metafile?path=METAFILE"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$PATH = "/METAFILE";  //= path to the meta file on the Phonexia Speech Engine
$SPEAKER_MODEL_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/metafile?path=$PATH",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "AudioFileInfoResult", "info": { "name": "julia_1.wav", "last_modified": "2015-08-03T08:16:15Z", "created": "2015-08-03T08:16:15Z", "size": 474444, "is_directory": false, "is_registered": true, "frequency": 8000, "length": 29.65, "n_channels": 1, "format": "lin16" } } } <?xml version="1.0"?> <result> <version>3</version> <name>AudioFileInfoResult</name> <info> <name>julia_1.wav</name> <last_modified>2015-08-03T08:16:15Z</last_modified> <created>2015-08-03T08:16:15Z</created> <size>474444</size> <is_directory>false</is_directory> <is_registered>true</is_registered> <frequency>8000</frequency> <length>29.65</length> <n_channels>1</n_channels> <format>lin16</format> </info> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1008File not found 1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

GET /technologies/speakerid4/speakermodels/{name}/voiceprint Get voiceprint from speaker model.

Gets a voiceprint from a prepared speaker model. The speaker model can be prepared by calling PUT /technologies/speakerid4/speakermodels/{name}/prepare

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.
model	query	string	yes	Name of the SID4 model.

Body

empty content

Example

/technologies/speakerid4/groups/{name} – speaker groups

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/speakermodels/kelly/voiceprint?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_MODEL_NAME = "kelly";
$TECHNOLOGY_MODEL = "L4";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_MODEL_NAME/voiceprint?model=$TECHNOLOGY_MODEL",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "SpeakerModelVoiceprintResult", "speaker_model": "kelly", "model": "L", "voiceprint": <Base64 Data>, "speech_length": 12.4 } } <?xml version="1.0" encoding="UTF-8"?> <result> <version>3</version> <name>SpeakerModelVoiceprintResult</name> <speaker_model>kelly</speaker_model> <model>L</model> <voiceprint>[Base64 Data]</voiceprint> <speech_length>12.4</speech_length> </result>
400Bad Request	1017User model not ready 1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

GET /technologies/speakerid4/groups/{name} Get speaker models in group

Returns information about a speaker model group.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.

Body

empty content

Example

POST /technologies/speakerid4/groups/{name} Create empty group

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/SPEAKER_GROUP_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_GROUP_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/groups/$SPEAKER_GROUP_NAME",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "SpeakerIdentificationGroupResult", "group": "group1", "is_ready": [ "S", "L" ], "is_calibrated": [ { "model": "S", "calibration_set": "calibset", "max_fa_rate": 0.1 } ], "speaker_models": [ "model1", "model2", ... ] } } <result> <version>3</version> <name>SpeakerIdentificationGroupResult</name> <group>group1</group> <is_ready> <item>S</item> <item>L</item> </is_ready> <is_calibrated> <item> <model>S</model> <calibration_set>calibset</calibration_set> <max_fa_rate>0.1</max_fa_rate> </item> ... </is_calibrated> <speaker_models> <item>model1</item> <item>model2</item> ... </speaker_models> </result>
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Creates a new empty speaker model group.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.

Body

empty content

Example

DELETE /technologies/speakerid4/groups/{name} Remove group

curl -H "X-SessionID:YOUR_SESSION_ID" -X POST "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/SPEAKER_GROUP_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_GROUP_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/groups/$SPEAKER_GROUP_NAME",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1016User model already exist 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker Group specified by name in request path

Removes an existing speaker model group.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of the speaker model.

Body

empty content

Example

/technologies/speakerid4/groups/{name}/speakermodel – speaker model in group

curl -H "X-SessionID:YOUR_SESSION_ID" -X DELETE "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/SPEAKER_GROUP_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_GROUP_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/speakermodels/$SPEAKER_GROUP_NAME",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker Group specified by name in request path

POST /technologies/speakerid4/groups/{name}/speakermodel Create group containing existing speaker model(s)

Specifies the existing speaker model(s) to be included in a speaker group. If the speaker group does not exist, it is automatically created. If the speaker group already exists, it gets overwritten. It is possible to set the Content-Type parameter in the request header, which is helpful in case the client wants to send input data in XML format.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
name	path	string	yes	Name of the speaker model.

Body

{
   "speaker_models": [
     "speaker_1",
     "speaker_2",
     ...
   ]
}

<?xml version="1.0" encoding="UTF-8"?>
<speaker_models>
  <item>speaker_1</item>
  <item>speaker_2</item>
  ...
</speaker_models>

Example

PUT /technologies/speakerid4/groups/{name}/speakermodel Add speaker model(s) to group

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X POST --data-binary "@speaker_models.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/SPEAKER_GROUP_NAME/speakermodel"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_GROUP_NAME = "test";

$speakers = array(
  'speaker_models' =>
  array (
    "speaker_1",
    "speaker_2"
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'POST',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($speakers),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/groups/$SPEAKER_GROUP_NAME/speakermodel",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker group specified by name in request path

Adds existing speaker model(s) into an existing speaker group. It is possible to set the Content-Type parameter in the request header which is helpful in case the client wants to send input data in XML format.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
name	path	string	yes	Name of the speaker model.

Body

{
   "speaker_models": [
     "speaker_1",
     "speaker_2",
     ...
   ]
}

<?xml version="1.0" encoding="UTF-8"?>
<speaker_models>
  <item>speaker_1</item>
  <item>speaker_2</item>
  ...
</speaker_models>

Example

DELETE /technologies/speakerid4/groups/{name}/speakermodel Remove speaker model(s) from group

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X PUT --data-binary "@speaker_models.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/SPEAKER_GROUP_NAME/speakermodel"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_GROUP_NAME = "test";

$speakers = array(
  'speaker_models' =>
  array (
    "speaker_1",
    "speaker_2"
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'PUT',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($speakers),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/groups/$SPEAKER_GROUP_NAME/speakermodel",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1018The requested URI requires content 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker group specified by name in request path

Removes speaker model(s) from a speaker group. The request body contains a list of speaker models to be removed from the speaker group. It is possible to set the Content-Type parameter in the request headerwhich is helpful in case the client wants to send input data in XML format.

Parameters

Name	Parameter Type	Data Type	Required	Description
Content-Type	header	string	no	`application/json` for JSON content (Default value) `application/xml` for XML content
name	path	string	yes	Name of the speaker model.

Body

{
   "speaker_models": [
     "speaker_1",
     "speaker_2",
     ...
   ]
}

<?xml version="1.0" encoding="UTF-8"?>
<speaker_models>
  <item>speaker_1</item>
  <item>speaker_2</item>
  ...
</speaker_models>

Example

/technologies/speakerid4/groups/{name}/prepare – prepares group of speaker models

curl -H "X-SessionID:YOUR_SESSION_ID" -H "Content-Type:application/json" -X DELETE --data-binary "@speaker_models.json" "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/SPEAKER_GROUP_NAME/speakermodel"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$SPEAKER_GROUP_NAME = "test";

$speakers = array(
  'speaker_models' =>
  array (
    "speaker_1",
    "speaker_2"
  )
);

$options = array(
  'http' =>
  array (
    'method'        => 'DELETE',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID . "\r\n" .
                       'Content-Type: application/json',
    'content'       => json_encode($speakers),
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/groups/$SPEAKER_GROUP_NAME/speakermodel",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1018The requested URI requires content 1038Resource is locked 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
405Method Not Allowed	1009Technology is not supported by server

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)
Speaker Identification 4 VoicePrint Comparator (SID4C)

Resource locker

CHECK Speaker group specified by name in request path

PUT /technologies/speakerid4/groups/{name}/prepare (asynchronous)Prepare group of speaker models

Prepares a group of speaker models. It is necessary to prepare a group before comparing voiceprints with it.

The group is prepared automatically when used in the GET /technologies/speakerid4 request.

This request is asynchronous (see Asynchronous request).

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of group.
model	query	string	yes	Name of the SID4 model.

Body

empty content

Example

/technologies/speakerid4/groups/{name}/voiceprints – voiceprints of all speaker models in group

curl -H "X-SessionID:YOUR_SESSION_ID" -X PUT "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/GROUP_NAME/prepare?model=L4"

/*
 * See above to chapter Asynchronous request - Example: PHP + JS Asynchronous request example
 *
 * There is specific options applicable for async_request() method from PHP + JS Example
 */
var group_name = 'test';
var options = {
  method: 'PUT',
  uri_path: '/technologies/speakerid4/groups/' + group_name + '/prepare',
  uri_params: {
    model: 'L4',
  },
  callback: function(result)
  {
    console.log(result); // work with result
  }
};

async_request(options);

Available responses

HTTP Status	Output
200OK
400Bad Request	1004An invalid value was specified for one of the query parameters in the request URI 1017User model not ready 1060The capacity for technology has been exceeded 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server
406Not Acceptable	1034Unable to prepare group of speaker models

Required technologies

Speaker Identification 4 VoicePrint Extractor (SID4E)

Resource locker

LOCK Speaker Group specified by name in request path

GET /technologies/speakerid4/groups/{name}/voiceprints Get voiceprints from speaker group.

Returns the list of voiceprints of all speaker models belonging to the speaker group. All speaker models must be prepared first. A speaker model can be prepared by calling PUT /technologies/speakerid4/speakermodels/{name}/prepare. All speaker models in a group can be prepared by calling PUT /technologies/speakerid4/groups/{name}/prepare.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Name of speaker group.
model	query	string	yes	Name of the SID4 model.

Body

empty content

Example

/technologies/speakerid4/audiosourceprofiles – list of Audio Source Profiles

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/groups/group1/voiceprints?model=L4"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$SPEAKER_GROUP_NAME = "group1";
$TECHNOLOGY_MODEL = "L4";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/groups/$SPEAKER_GROUP_NAME/voiceprints?model=$TECHNOLOGY_MODEL",
  false,
  $context
);

$matches = array();
preg_match('/HTTP\/\d+\.\d+ (\d+)/', $http_response_header[0], $matches);
$http_code = $matches[1];

if($http_code == 200)
{
  // OK
}
?>

Available responses

HTTP Status	Output
200OK	JSON XML { "result": { "version": 3, "name": "SpeakerGroupVoiceprintsResult", "speaker_group": "group1", "model": "L", "voiceprint_set": [ { "speaker_model": "kelly", "voiceprint": <Base64 Data>, "speech_length": 12.4 }, { "speaker_model": "julia", "voiceprint": <Base64 Data>, "speech_length": 24.8 }, ... ] } } <?xml version='1.0' encoding='UTF-8'?> <result> <version>3</version> <name>SpeakerGroupVoiceprintsResult</name> <speaker_group>group1</speaker_group> <model>L</model> <voiceprint_set> <item> <speaker_model>kelly</speaker_model> <voiceprint>[Base64 Data]</voiceprint> <speech_length>12.4</speech_length> </item> <item> <speaker_model>julia</speaker_model> <voiceprint>[Base64 Data]</voiceprint> <speech_length>24.8</speech_length> </item> ... </voiceprint_set> </result>
400Bad Request	1017User model not ready 1004An invalid value was specified for one of the query parameters in the request URI 1073An uknown parameter was submitted
401Unauthorized	1005The request requires user authentication
404Not Found	1015User model not found
405Method Not Allowed	1009Technology is not supported by server

GET /technologies/speakerid4/audiosourceprofiles List of Audio Source Profiles

Returns the list of Audio Source Profiles for Speaker Identification 4.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/audiosourceprofiles"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/audiosourceprofiles",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK

/technologies/speakerid4/audiosourceprofiles/{name} – Audio Source Profile manipulation

{
  "result": {
    "version": 1,
    "name": "AudioSourceProfilesResult",
    "audio_source_profiles": [
      {
        "name": "Profile1",
        "hash": "ffecae4fedd92147992a77e7f555d113a012c5bb9b26e1a0f4537ba77affab4d",
        "model": "L4"
      },
      {
        "name": "Profile2",
        "hash": "bae838c29f979f9f56214a8e0e318d342d26cbf13248c4db451c7314983dcf98",
        "model": "L4"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <version>1</version>
  <name>AudioSourceProfilesResult</name>
  <audio_source_profiles>
    <item>
       <name>Profile1</name>
       <hash>bae838c29f979f9f56214a8e0e318d342d26cbf13248c4db451c7314983dcf98</hash>
       <model>L4</model>
    </item>
    <item>
       <name>Profile2</name>
       <hash>bae838c29f979f9f56214a8e0e318d342d26cbf13248c4db451c7314983dcf98</hash>
       <model>L4</model>
    </item>
  </audio_source_profiles>
</result>

400Bad Request

1004An invalid value was specified for one of the query parameters in the request URI
1073An uknown parameter was submitted

401Unauthorized

1005The request requires user authentication

GET /technologies/speakerid4/audiosourceprofiles/{name} Information about Audio Source Profile

Returns details about an Audio Source Profile

See also Usage examples - Speaker Identification 4 - prepare Audio Source Profile for more information.

Parameters

Name	Parameter Type	Data Type	Required	Description
name	path	string	yes	Determines the Audio Source Profile.

Body

empty content

Example

curl -H "X-SessionID:YOUR_SESSION_ID" -X GET "SERVER_ADDRESS:PORT/technologies/speakerid4/audiosourceprofiles/AUDIO_SOURCE_PROFILE_NAME"

<?php
/**
 * Set variables according to your server.
 */
$SERVER_ADDRESS = 'http://127.0.0.1';
$PORT = 8600;
$YOUR_SESSION_ID = '39db96cc-f11e-4d34-afae-33635cf9c4c1';	//= get it from login request
$AUDIO_SOURCE_PROFILE_NAME = "test";

$options = array(
  'http' =>
  array (
    'method'        => 'GET',
    'header'        => 'X-SessionID: ' . $YOUR_SESSION_ID,
    'ignore_errors'  => true,
  )
);

$context = stream_context_create( $options );
$response = file_get_contents(
  "$SERVER_ADDRESS:$PORT/technologies/speakerid4/audiosourceprofiles/$AUDIO_SOURCE_PROFILE_NAME",
  false,
  $context
);

$response = json_decode( $response );
var_dump($response);
/** Work with $response **/
?>

Available responses

HTTP Status

Output

200OK