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 Content Too Large | request.size-limit-exceeded | Size of request exceeded. The client may retry with different data. |
| 422 Unprocessable Content | 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.
| 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. |
model.not-deployed | resource.not-found | The requested model is not deployed. |
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. |
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. See the detail's message for more info. |
value-empty | Value must not be empty. Applies to values of type string or array. |
value-incomplete | Value must be complete. Applies to values of type string. |
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. |
values-not-unique | Values in an array must be unique. |
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.
Context of error detail
Apart from the type, error detail may also carry a context. It is a key-value mapping that contains other useful information about the error. It may be used for more in-depth understanding of the error or e.g. for graphical rendering of user-friendly error views.
| error type | error detail type | context keys and their data types |
|---|---|---|
request.forbidden | licensing.capacity-exceeded | - |
request.size-limit-exceeded | media.too-large | file_size: integermax_file_size: integersize_unit: string |
request.validation-error | language-groups-intersecting | group: stringconflicting_codes: array[string] |
request.validation-error | language-selection-conflict | incorrect_language: stringgroup: stringuser_defined_languages: array[string] |
request.validation-error | language-switching-and-source-language-conflict | source_language: stringlanguage_switching: boolean |
request.validation-error | max-and-total-speakers-conflict | max_speakers: integertotal_speakers: integer |
request.validation-error | model-conflict | models: array[string] |
request.validation-error | operation-and-raw-segmentation-conflict | - |
request.validation-error | range-not-sequential | start: number<float>end: number<float> |
request.validation-error | too-many-channels | channels: array[integer]max: integer |
request.validation-error | unknown | - |
request.validation-error | value-empty | - |
request.validation-error | value-incomplete | value: string |
request.validation-error | value-invalid | value: oneOf(string,number,boolean) |
request.validation-error | value-negative | value: number |
request.validation-error | value-not-positive | value: number |
request.validation-error | value-too-short | length: integermin_length: integer |
request.validation-error | values-not-unique | repeated_values: array[string] |
resource.not-found | endpoint.not-found | - |
resource.not-found | file.not-found | file_id: string<uuid> |
resource.not-found | model.not-deployed | requested_model: stringavailable_models: array[string] |
resource.not-found | task.not-found | task_id: string<uuid> |
Task errors
The response to 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 response.
The client can retry the request after correcting the input data. Examples of error messages follow.
| 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. |
Task validation error details
As illustrated by the last example, the task.validation-error error type may include
an array of error details. Similarly to error details found in request errors, some of
these details include context with known structure.
| error detail type | context keys and their data types |
|---|---|
grapheme.invalid | grapheme: string |
model.unavailable | model: string |
multichannel.not-supported | number_of_channels: integer |
phoneme.invalid | phoneme: string |
phonemes.insufficient-count | minimum: integer |
technology.unavailable | technology: string |
unknown | - |
value.empty | - |
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.
Robust handling of error responses
When building custom automation based on the API's error responses, it is important to do it in a future-proof way. Please, adhere to the following principles in order not to be disrupted by future backwards-compatible updates of the API.
Do not rely on messages
Error message (as well as error detail message) is a free-form human-readable text that
describes the problem. As we improve Speech Platform 4, these messages may also change
in order to provide better insight into the problem. Because of that, no automatic
response handling should be based on them. Instead, use error's or error detail's
type, which is a fixed value and doesn't change in time.
Apply Postel's Law
The Postel's Law is a well-established engineering practice that guides machine-to-machine communication and states: "Be conservative in what you send, be liberal in what you accept." When applied to consuming the Speech Platform 4 API, this means your client code should tolerate responses that contain more information than you currently expect.
In practice, we may introduce new fields in response bodies, new values in enumerations, or new error detail types as part of backwards-compatible API evolution. A robust client should:
- Ignore unknown JSON fields rather than failing when deserializing a response. If your HTTP or JSON library supports a "strict" mode that rejects unrecognized properties, make sure it is turned off for Speech Platform 4 responses.
- Handle new error detail types gracefully. When processing error details, your code
may encounter a
typevalue it does not yet know about. This is especially relevant for both request and task validation errors. Theirdetailarray may include many different detail types and new ones are expected to be added in the future.
By following these guidelines you ensure that your integration remains stable across API updates without requiring immediate changes on your side every time the API is extended.