Version: 3.5.0-dev.2

Phonexia Speech Platform 4: REST API Reference

OpenAPI

Speech Platform 4 REST API follows OpenAPI specification.

Technologies

The main functionality of the REST API is provided by technology endpoints that can be used to post tasks and to get task results. Some technologies comprise endpoints for different logically related tasks:

• Speaker Identification
  • Voiceprint Extraction - This technology extracts voiceprints from media files. Voiceprints capture distinctive vocal characteristics, allowing for various speaker recognition tasks.
  • Voiceprint Comparison - This technology compares two sets of voiceprints that were individually prepared by Voiceprint Extraction.
• Speech to Text
  • Enhanced Speech to Text Built on Whisper - This technology transcribes speech in media files using a Whisper model enhanced by Phonexia.
  • Speech to Text by Phonexia - This technology transcribes speech in media files using original Phonexia models.

Tasks

In the REST API, technology endpoints adhere to a standardized workflow of creating tasks and retrieving task results. The following example illustrates the workflow for the Voiceprint Extraction technology:

Step 1: Start Task

Initiate the operation by making a POST request to the following endpoint:

POST {address}:{port}/api/technology/speaker-identification-voiceprint-extraction

• Request Parameters: Ensure that you provide the necessary parameters or data as specified in the API documentation.
• Response: The API will respond with a unique task_id and task state.

Step 2: Get Task Result

To monitor the progress and to obtain the result of the operation, make a GET request to the same endpoint while replacing {task_id} with the unique task_id received in Step 1:

GET {address}:{port}/api/technology/speaker-identification-voiceprint-extraction/{task_id}

The response includes a state field which can have one of the following values:

• running: This state means that the task is currently being executed. The task is actively performing its designated operations.
• rejected: This state suggests that the task hasn't been executed, probably because certain requirements for execution haven't been met. The user may try to start the task again with different input.
• failed: A task in this state has encountered an issue during its execution and was unable to complete its intended operations successfully. The API user may try starting an identical task again, and it may succeed if the issue of the system has been resolved (e.g., a service has been automatically restarted). Otherwise, it may be necessary to have the system administrator solve the issue.
• done: The task that has reached this state has been successfully completed, and its intended operations have been executed without errors.

This standardized workflow ensures efficient monitoring and management of voice-related technology operations, making it easier to integrate them into your applications.

Querying Task State

You can also query the state of a specific task by making a GET request to the following endpoint:

GET {address}:{port}/api/task/{task_id}

This endpoint provides state information about the specified task, which can be useful for tracking its progress and status.

Task Workflow Diagram

The following diagram illustrates the logic of a basic task workflow. API calls are shown in rounded boxes. See section "Get Task Result" for more information on individual task states:

Error responses

You can encounter an error in two places:

• a direct response to a request;
• a result of a task.

Request errors

An error as a direct response to a request is typically caused by the client's input.

It may be a common HTTP error like '405 Method not allowed', '404 Not Found', etc. It may also be invalid data in the body (e.g. input file), query parameters, or headers. The client might want to retry the request after fixing the input data.

Request errors and HTTP status codes

error type	error message	HTTP code	description
request.invalid	Invalid request.	400 Bad Request	Request payload data was invalid and could not be parsed.
request.forbidden	Request is forbdden.	403 Forbidden	Request is valid but not allowed by the system.
resource.not-found	Resource not found.	404 Not Found	Resource or endpoint does not exist.1
method.invalid	Invalid method.	405 Method Not Allowed	Unsupported HTTP method was requested.
request.size-limit-exceeded	Request size limit exceeded.	413 Request Entity Too Large	Size of request exceeded. The client may retry with different data.
request.validation-error	Request validation error.	422 Unprocessable Entity	Request payload data was not validated by the API.1
request.rate-limit-exceeded	Rate limit exceeded: <rate_limit_spec>.	429 Too Many Requests	Request rate limit for an endpoint has been exceeded. The client may retry later.2
storage.capacity-exceeded	Storage capacity exceeded.	507 Insufficient Storage	The server is unable to store the data needed to complete the request due to insufficient storage.
internal	Internal server error.	500 Internal Server Error	Unhandled application error occurred.

¹ Possible error detail types are described in section Error details below.
² The following response headers may be checked for details: retry-after, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.

Request error details

Some request errors may contain additional information in the response body. The following table describes possible error detail types and messages.

error detail type	error detail message	error type	description
endpoint.not-found	Endpoint does not exist.	resource.not-found	The requested endpoint URL is not provided by the API.
task.not-found	Task does not exist.	resource.not-found	The requested task does not exist. The provided task_id may be wrong or the task may have expired already.
licensing.capacity-exceeded	Licensed processing capacity exceeded.	request.forbidden	Processing capacity allowed for the operation was exceeded. You may try again later or extend the license.
various error types	various messages	request.validation-error	Various error codes from Pydantic, which is used internally for input validation.1

¹ See Pydantic validation errors.

Request error detail types are subject to change.

For error handling purposes, using error type is recommended.

Task errors

The result of an asynchronous task contains an error in case of rejection or failure.

Rejection

A task rejection typically happens when the request was originally accepted but further validation found an error. Some validation is impossible to do before the task is started as it's performed on the underlying service side. For example, the request may contain a file that is not supported by the underlying service. In this case, the task is rejected and the error is returned in the task result.

For example, the request may contain a file that is not supported by the underlying service. In this case, the task is rejected and the error is returned in the task result.

The client may retry the request after fixing the input data.

error type	error message	description
task.validation-error	Empty or corrupted media file.	The input file can't be processed, as it does not contain media data.
task.validation-error	No audio streams found in the file.	The input file is a media file, but it does not contain any audio streams.
task.validation-error	Audio length limit exceeded.	The input audio is too long to be processed by the technology.
task.validation-error	Unsupported language: <language_tag>	The language is not supported by the technology.

Rejection error message is subject to change.

For error handling purposes, using error type is recommended.

Failure

Task failures are reserved for system failures like unavailability of the underlying service or unexpected crashes. In this case, the client may retry the request after some time. If the failure persists, it may be necessary to have the system administrator solve the issue.

error type	error message	description
internal	various error messages	Task processing failed due to some internal/service error.

Failure error type and error message values are subject to change.

The cause of the failure is not properly distinguishable by the error type yet.

Some possible error messages are the following: License has expired, Service is busy, Unknown error, and several others. The error message may be used for pinpointing the cause of the failure during development, but it's not guaranteed it won't change in the future.