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.
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 /api/technology/speaker-identification-voiceprint-extraction
- Request Parameters: Ensure that you provide the necessary parameters or data as
specified in the API documentation. They can be passed in two ways:
- Query Parameters: Passed in the URL.
- Configuration Parameters: Passed as part of
multipart/form-datacontent type with the field nameconfigand the value as a JSON string. The JSON string must use exact key names as documented for the endpoint (case-sensitive, no typos). Any unknown keys are silently ignored and the endpoint will proceed with its default behavior for those parameters.
- Response: The API will respond with a unique
task_idand taskstate.
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 URL appended with the unique task_id received in Step 1:
GET /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.
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
Errors may occur in two contexts:
- directly in the response to a request
- in the result of an asynchronous task
Request errors
An error returned directly in response to a request is typically caused by invalid
input from the client. It may be a standard HTTP error such as 404 Not Found,
405 Method Not Allowed, or similar. It may also result from invalid data in the
request body (for example, an input file), query parameters, or headers. The client can
retry the request after correcting the input data.
Request errors and HTTP status codes
| HTTP status code | error type | description |
|---|---|---|
| 400 Bad Request | request.invalid | Request payload data was invalid and could not be parsed. |
| 403 Forbidden | request.forbidden | Request is valid but not allowed by the system. |
| 404 Not Found | resource.not-found | Resource or endpoint does not exist. |
| 405 Method Not Allowed | method.invalid | Unsupported HTTP method was requested. |
| 413 Request Entity Too Large | request.size-limit-exceeded | Size of request exceeded. The client may retry with different data. |
| 422 Unprocessable Entity | request.validation-error | Request payload data was not validated by the API. |
| 500 Internal Server Error | internal | Unhandled application error occurred. |
| 507 Insufficient Storage | storage.capacity-exceeded | The server is unable to store the data needed to complete the request due to insufficient storage. |
Request error details
Some request errors may include additional information in the response body. The following table describes the possible error detail types and messages.
| error detail type | error type | description |
|---|---|---|
endpoint.not-found | resource.not-found | The requested endpoint URL is not provided by the API. |
file.not-found | resource.not-found | The requested file does not exist. The provided file_id may be wrong or the task may have expired already, causing the file to be deleted automatically. |
licensing.capacity-exceeded | request.forbidden | Processing capacity allowed for the operation was exceeded. You may try again later or extend the license. |
media.too-large | request.size-limit-exceeded | The media file intended for processing exceeds the size limit. |
task.not-found | resource.not-found | The requested task does not exist. The provided task_id may be wrong or the task may have expired already. |
Request validation error details
Request data pass through two layers of validation. The first is provided by the Pydantic library which checks if request data conform to the constraints specified in the REST API documentation, e.g., data is of the correct type (string, integer, etc.), or a value is in the list of supported options. The second layer of validation is concerned with enforcing constraints of Phonexia speech technologies and safeguarding internal logic of task processing (e.g., mutually exclusive arguments are not both set).
All validation errors have the general request.validation-error type. Validation
errors may include an array of error details with a type of their own. The details
describe all the possible problems in the input data.
Some error details additionally carry a context---a key-value map with additional information about the error detail. The structure of the context is unique for each error detail type, and it is described in individual endpoints' documentation.
The early-validation-failure detail type covers all problems discovered in the first
layer of validation provided by Pydantic. The actual problem discovered by Pydantic is
included as original_type in the detail's context. See
Pydantic validation errors
for an exhaustive list of all problems grouped in this error detail type. These early
checks frequently deal with data types. For example, the value "seven" will be rejected
when a numeric data type is expected.
Other error detail types originate in deeper layers of the application and express some violation of business logic.
| validation error detail type | description |
|---|---|
early-validation-failure | Value failed to pass early format validation. |
language-groups-intersecting | Language Identification: Language codes must be unique across all language groups. |
language-selection-conflict | Language Identification: All language codes used in groups must be selected for identification. |
language-switching-and-source-language-conflict | Enhanced Speech Translation Built on Whisper: Language switching cannot be enabled if source language is set. |
max-and-total-speakers-conflict | Speaker Diarization: Maximum speakers and total speakers cannot be set at the same time. |
model-conflict | Voiceprint Merging: All voiceprints must be generated by the same model. |
operation-and-raw-segmentation-conflict | Authenticity Verification: Raw segmentation is allowed only when Audio Manipulation Detection operation is requested. |
range-not-sequential | The start value of a range must not be greater than its end value. |
too-many-channels | Channels selected for processing must comply with technology requirements. |
unknown | An unknown validation error occurred. |
value-empty | Value must not be empty. Applies to values of type string or array. |
value-invalid | Value must conform to constraints specific for the field. |
value-negative | Value must be a non-negative number. |
value-not-positive | Value must be a positive number. |
value-too-short | Value must have the minimum required length. |
value-unsupported | Value is not among options provided by the given field. |
values-not-unique | Values in an array must be unique. |
Task errors
The result of an asynchronous task will contain an error if the task is rejected or fails.
Rejection
A task is typically rejected when the request was initially accepted, but a later validation step discovers an error. Some checks cannot be performed before the task starts, because they run only in the underlying service. For example, the request may include a file type that the service does not support. In such a case, the task is rejected and the error is reported in the task result.
The client can retry the request after correcting 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. |
task.validation-error | Invalid request: <N> error(s) occurred. | The underlying service identified problems in the request. They are enumerated in the detail array. |
Rejection error message, as well as items in the detail array, are subject to
change.
For error handling purposes, using error type is recommended.
Failure
Task failures are typically caused by system issues, such as unavailability of the underlying service or unexpected crashes.
The client can retry the request after a delay. If the failures persist, a system administrator may need to investigate and resolve 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.