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.
- 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 and contain specific details with types of their own.
| validation error detail type | description |
|---|---|
| various error types | Various request validation error codes from Pydantic. See Pydantic validation errors for exhaustive list of all error detail types that might be reported. |
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. |
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. |
values-not-unique | Values in an array must be unique. |
Request validation error detail type is subject to change.
For error handling purposes, using error type is recommended.
Note that while validation errors are listed in the Pydantic documentation, not all of them can occur in the context of this API. In addition, error responses are standardized by FastAPI and this API to ensure consistent formatting across all endpoints. An example of such a response is provided in the documentation for each REST API endpoint.
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. |
Rejection error message is 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.