openapi: 3.1.0 info: title: Soniox Public API version: 1.0.0 description: '' paths: /v1/files: get: operationId: get_files summary: Get files parameters: - in: query name: limit schema: default: 1000 description: Maximum number of files to return. maximum: 1000 minimum: 1 title: Limit type: integer required: false description: Maximum number of files to return. - in: query name: cursor schema: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor required: false description: Pagination cursor for the next page of results. responses: '200': description: List of files. content: application/json: schema: $ref: '#/components/schemas/GetFilesResponse' example: files: - id: 84c32fc6-4fb5-4e7a-b656-b5ec70493753 filename: example.mp3 size: 123456 created_at: '2024-11-26T00:00:00Z' next_page_cursor: cursor_or_null '400': description: | Invalid request. Error types: - `invalid_cursor`: The `cursor` parameter is invalid. Omit `cursor` to start pagination from the beginning. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_cursor message: The `cursor` parameter is invalid. Omit `cursor` to start pagination from the beginning. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-cursor '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate, total file count, or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for file management has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves list of uploaded files. tags: - Files security: - PublicApiAuth: [] post: operationId: upload_file summary: Upload file parameters: [] responses: '201': description: Uploaded file. content: application/json: schema: $ref: '#/components/schemas/File' example: id: 84c32fc6-4fb5-4e7a-b656-b5ec70493753 filename: example.mp3 size: 123456 created_at: '2024-11-26T00:00:00Z' '400': description: | Invalid request. Error types: - `invalid_request`: One or more parts of the multipart body are missing or invalid (missing `file`, filename or `client_reference_id` too long, malformed multipart body), or the uploaded file exceeds the per-file upload limit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: missing location: file.file message: Field required request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate, the total file count or total file size cap (organization or project), or this upload would exceed those caps. The `message` describes which limit was hit. Delete unused files via `DELETE /v1/files/{id}` or request a higher limit in the Soniox Console. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Total file count limit has been exceeded for your organization. Please delete some. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Uploads a new file. tags: - Files requestBody: content: multipart/form-data: schema: title: MultiPartBodyParams type: object properties: client_reference_id: anyOf: - maxLength: 256 type: string - type: 'null' description: Optional tracking identifier string. Does not need to be unique. title: Client Reference Id file: description: The file to upload. Original file name will be used unless a custom filename is provided. format: binary title: File type: string required: - file required: true security: - PublicApiAuth: [] /v1/files/count: get: description: Returns the total number of files, split by source. operationId: get_files_count parameters: [ ] responses: '200': content: application/json: example: playground: 8 public_api: 42 total: 50 schema: $ref: '#/components/schemas/GetFilesCountResponse' description: Total number of files, split by source. '401': content: application/json: example: error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda status_code: 401 validation_errors: [ ] more_info: https://soniox.com/docs/api-reference/errors#unauthenticated schema: $ref: '#/components/schemas/ApiError' description: Authentication error. '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for file management has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': content: application/json: example: error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda status_code: 500 validation_errors: [ ] more_info: https://soniox.com/docs/api-reference/errors#internal-error schema: $ref: '#/components/schemas/ApiError' description: Internal server error. security: - PublicApiAuth: [ ] summary: Get files count tags: - Files /v1/files/{file_id}: get: operationId: get_file summary: Get file parameters: - in: path name: file_id schema: format: uuid title: File Id type: string required: true responses: '200': description: File metadata. content: application/json: schema: $ref: '#/components/schemas/File' example: id: 84c32fc6-4fb5-4e7a-b656-b5ec70493753 filename: example.mp3 size: 123456 created_at: '2024-11-26T00:00:00Z' client_reference_id: some_internal_id '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | File not found. Error types: - `file_not_found`: No file with this ID exists in the project the API key is scoped to (it may have been deleted, the ID may be wrong, or it may belong to a different project). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 404 error_type: file_not_found message: No file with this ID exists in your project. The file may have been deleted, the ID may be incorrect, or the file may belong to a different project. Verify the ID by listing files with GET /files. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#file-not-found '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for file management has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieve metadata for an uploaded file. tags: - Files security: - PublicApiAuth: [] delete: operationId: delete_file summary: Delete file parameters: - in: path name: file_id schema: format: uuid title: File Id type: string required: true responses: '204': description: File deleted. '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | File not found. Error types: - `file_not_found`: No file with this ID exists in the project the API key is scoped to (it may have been deleted, the ID may be wrong, or it may belong to a different project). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 404 error_type: file_not_found message: No file with this ID exists in your project. The file may have been deleted, the ID may be incorrect, or the file may belong to a different project. Verify the ID by listing files with GET /files. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#file-not-found '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for file management has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Permanently deletes specified file. If a transcription that has not started processing yet still references the file, that transcription fails with `file_not_found`, so delete the file only after the transcription reaches `completed` or `error`. tags: - Files security: - PublicApiAuth: [] /v1/transcriptions: get: operationId: get_transcriptions summary: Get transcriptions parameters: - in: query name: limit schema: default: 1000 description: Maximum number of transcriptions to return. maximum: 1000 minimum: 1 title: Limit type: integer required: false description: Maximum number of transcriptions to return. - in: query name: cursor schema: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor required: false description: Pagination cursor for the next page of results. responses: '200': description: A list of transcriptions. content: application/json: schema: $ref: '#/components/schemas/GetTranscriptionsResponse' example: transcriptions: - id: 73d4357d-cad2-4338-a60d-ec6f2044f721 status: completed created_at: '2024-11-26T00:00:00Z' model: stt-async-preview audio_url: https://soniox.com/media/examples/coffee_shop.mp3 file_id: null filename: coffee_shop.mp3 language_hints: - en - fr context: extra context for the transcription audio_duration_ms: 16079 error_message: null webhook_url: https://example.com/webhook webhook_auth_header_name: Authorization webhook_auth_header_value: '******************' webhook_status_code: null client_reference_id: some_internal_id next_page_cursor: cursor_or_null '400': description: | Invalid request. Error types: - `invalid_cursor`: The `cursor` parameter is invalid. Omit `cursor` to start pagination from the beginning. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_cursor message: The `cursor` parameter is invalid. Omit `cursor` to start pagination from the beginning. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-cursor '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for async transcription has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves list of transcriptions. tags: - Transcriptions security: - PublicApiAuth: [] post: operationId: create_transcription summary: Create transcription parameters: [] responses: '201': description: Created transcription. content: application/json: schema: $ref: '#/components/schemas/Transcription' example: id: 73d4357d-cad2-4338-a60d-ec6f2044f721 status: queued created_at: '2024-11-26T00:00:00Z' model: stt-async-preview audio_url: https://soniox.com/media/examples/coffee_shop.mp3 file_id: null filename: coffee_shop.mp3 language_hints: - en - fr context: extra context for the transcription audio_duration_ms: 0 error_message: null webhook_url: https://example.com/webhook webhook_auth_header_name: Authorization webhook_auth_header_value: '******************' webhook_status_code: null client_reference_id: some_internal_id '400': description: | Invalid request. Error types: - `invalid_request`: One or more request body fields are missing or invalid (model, audio source, language hints, translation config, webhook config, etc.). Inspect `validation_errors`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: value_error location: body.payload.model message: Invalid model request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '402': description: | Balance or budget exhausted. Error types: - `organization_balance_exhausted`: The organization's prepaid balance has dropped to zero. Top up at https://console.soniox.com/org/billing/overview or enable autopay. - `organization_monthly_budget_exhausted`: The organization has hit its configured monthly budget cap. Raise the cap at https://console.soniox.com/org/limits, or wait for the month to roll over. - `project_monthly_budget_exhausted`: The project has hit its configured monthly budget cap. Raise the cap at https://console.soniox.com/org/projects/limits, or wait for the month to roll over. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 402 error_type: organization_balance_exhausted message: Organization balance exhausted. Please either add funds manually or enable autopay. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#organization-balance-exhausted '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate, total transcription count, or pending transcription count limit (organization or project). The `message` describes which limit was hit. Delete completed transcriptions via `DELETE /v1/transcriptions/{id}` or request a higher limit in the Soniox Console. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Total transcription count limit for your organization has been exceeded. Please delete some. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Creates a new transcription. tags: - Transcriptions requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTranscriptionPayload' required: true security: - PublicApiAuth: [] /v1/transcriptions/count: get: description: Returns the total number of transcriptions, split by request scope. operationId: get_transcriptions_count parameters: [] responses: '200': content: application/json: example: playground: 8 public_api: 42 total: 50 schema: $ref: '#/components/schemas/GetTranscriptionsCountResponse' description: Total number of transcriptions, split by request scope. '401': content: application/json: example: error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda status_code: 401 validation_errors: [] more_info: https://soniox.com/docs/api-reference/errors#unauthenticated schema: $ref: '#/components/schemas/ApiError' description: Authentication error. '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for async transcription has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': content: application/json: example: error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda status_code: 500 validation_errors: [] more_info: https://soniox.com/docs/api-reference/errors#internal-error schema: $ref: '#/components/schemas/ApiError' description: Internal server error. security: - PublicApiAuth: [] summary: Get transcriptions count tags: - Transcriptions /v1/transcriptions/{transcription_id}: get: operationId: get_transcription summary: Get transcription parameters: - in: path name: transcription_id schema: format: uuid title: Transcription Id type: string required: true responses: '200': description: Transcription details. content: application/json: schema: $ref: '#/components/schemas/Transcription' example: id: 73d4357d-cad2-4338-a60d-ec6f2044f721 status: completed created_at: '2024-11-26T00:00:00Z' model: stt-async-preview audio_url: https://soniox.com/media/examples/coffee_shop.mp3 file_id: null filename: coffee_shop.mp3 language_hints: - en - fr context: extra context for the transcription audio_duration_ms: 16079 error_message: null webhook_url: https://example.com/webhook webhook_auth_header_name: Authorization webhook_auth_header_value: '******************' webhook_status_code: null client_reference_id: some_internal_id '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | Transcription not found. Error types: - `transcription_not_found`: No transcription with this ID exists in the project the API key is scoped to (it may have been deleted, the ID may be wrong, or it may belong to a different project). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 404 error_type: transcription_not_found message: No transcription with this ID exists in your project. It may have been deleted, the ID may be incorrect, or the transcription may belong to a different project. Verify the ID by listing transcriptions with GET /transcriptions. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#transcription-not-found '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for async transcription has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves detailed information about a specific transcription. tags: - Transcriptions security: - PublicApiAuth: [] delete: operationId: delete_transcription summary: Delete transcription parameters: - in: path name: transcription_id schema: format: uuid title: Transcription Id type: string required: true responses: '204': description: Transcription deleted. '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | Transcription not found. Error types: - `transcription_not_found`: No transcription with this ID exists in the project the API key is scoped to (it may have been deleted, the ID may be wrong, or it may belong to a different project). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 404 error_type: transcription_not_found message: No transcription with this ID exists in your project. It may have been deleted, the ID may be incorrect, or the transcription may belong to a different project. Verify the ID by listing transcriptions with GET /transcriptions. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#transcription-not-found '409': description: | Invalid transcription state. Error types: - `transcription_invalid_state`: The transcription cannot be deleted in its current state — it is still processing. Wait until `status` reaches `completed` or `error` and retry. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 409 error_type: transcription_invalid_state message: This transcription is currently being processed and cannot be deleted yet. Wait until `status` reaches `completed` or `error` (check via GET /transcriptions/{id}), then retry the delete. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#transcription-invalid-state '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for async transcription has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Permanently deletes a transcription. Files uploaded through the Files API are not deleted; use the delete file endpoint to remove them. Cannot delete transcriptions that are currently processing. tags: - Transcriptions security: - PublicApiAuth: [] /v1/transcriptions/{transcription_id}/transcript: get: operationId: get_transcription_transcript summary: Get transcription transcript parameters: - in: path name: transcription_id schema: format: uuid title: Transcription Id type: string required: true responses: '200': description: Transcription transcript. content: application/json: schema: $ref: '#/components/schemas/TranscriptionTranscript' example: id: 19b6d61d-02db-4c25-bc71-b4094dc310c8 text: Hello tokens: - text: Hel start_ms: 10 end_ms: 90 confidence: 0.95 - text: lo start_ms: 110 end_ms: 160 confidence: 0.98 '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | Transcription not found. Error types: - `transcription_not_found`: No transcription with this ID exists in the project the API key is scoped to (it may have been deleted, the ID may be wrong, or it may belong to a different project). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 404 error_type: transcription_not_found message: No transcription with this ID exists in your project. It may have been deleted, the ID may be incorrect, or the transcription may belong to a different project. Verify the ID by listing transcriptions with GET /transcriptions. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#transcription-not-found '409': description: | Invalid transcription state. The transcription exists but the transcript cannot be returned in its current state. Error types: - `transcription_invalid_state`. The `message` indicates which sub-case applies: - **Not completed yet** — transcription is still queued, downloading, or transcribing. Poll `GET /transcriptions/{id}` until `status` is `completed`, or configure a webhook on the transcription. - **Failed** — transcription ended in `failed` state. Inspect `error_type` / `error_message` on `GET /transcriptions/{id}` for the failure reason. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 409 error_type: transcription_invalid_state message: The transcript is not ready yet — transcription is still in progress. Poll GET /transcriptions/{id} until `status` is `completed`, or configure a webhook when creating the transcription to be notified when it finishes. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#transcription-invalid-state '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for async transcription has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves the full transcript text and detailed tokens for a completed transcription. Only available for successfully completed transcriptions. tags: - Transcriptions security: - PublicApiAuth: [] /v1/voices: get: operationId: get_voices summary: Get voices parameters: - in: query name: limit schema: default: 1000 description: Maximum number of voices to return. maximum: 1000 minimum: 1 title: Limit type: integer required: false description: Maximum number of voices to return. - in: query name: cursor schema: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor required: false description: Pagination cursor for the next page of results. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetVoicesResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Retrieves the list of voices in your project. tags: - Voices security: - PublicApiAuth: [] post: operationId: create_voice summary: Create voice parameters: [] responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Voice' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Uploads a reference audio clip and creates a new voice. tags: - Voices requestBody: content: multipart/form-data: schema: title: MultiPartBodyParams type: object properties: name: description: A name for the voice, unique within your project. maxLength: 128 minLength: 1 title: Name type: string file: description: The reference audio clip for the voice. format: binary title: File type: string required: - name - file required: true security: - PublicApiAuth: [] /v1/voices/count: get: operationId: get_voices_count summary: Get voices count parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetVoicesCountResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Returns the total number of voices in your project. tags: - Voices security: - PublicApiAuth: [] /v1/voices/{voice_id}: get: operationId: get_voice summary: Get voice parameters: - in: path name: voice_id schema: format: uuid title: Voice Id type: string required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Voice' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Retrieve metadata for a voice. tags: - Voices security: - PublicApiAuth: [] delete: operationId: delete_voice summary: Delete voice parameters: - in: path name: voice_id schema: format: uuid title: Voice Id type: string required: true responses: '204': description: No Content '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Permanently deletes the specified voice and its embeddings. tags: - Voices security: - PublicApiAuth: [] /v1/voices/{voice_id}/recompute: post: operationId: recompute_voice summary: Recompute voice parameters: - in: path name: voice_id schema: format: uuid title: Voice Id type: string required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Voice' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Prepares the voice for use with available models it is not ready for yet. Use this after a new model is released to make an existing voice usable with it. Models the voice is already prepared for are left unchanged. tags: - Voices requestBody: content: application/json: schema: $ref: '#/components/schemas/RecomputeVoicePayload' required: true security: - PublicApiAuth: [] /v1/models: get: operationId: get_models summary: Get models parameters: [] responses: '200': description: List of available models and their attributes. content: application/json: schema: $ref: '#/components/schemas/GetModelsResponse' '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves list of available models and their attributes. tags: - Models security: - PublicApiAuth: [] /v1/tts-models: get: operationId: get_tts_models summary: Get TTS models parameters: [] responses: '200': description: List of available TTS models and their attributes. content: application/json: schema: $ref: '#/components/schemas/GetTTSModelsResponse' '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate limit for model listing. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for model listing has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves list of available TTS models and their attributes. tags: - TTS Models security: - PublicApiAuth: [] /v1/shared-voices: get: operationId: get_shared_voices summary: Get shared voices parameters: - in: query name: model schema: description: Id of the TTS model whose voices to return. maxLength: 64 title: Model type: string required: true description: Id of the TTS model whose voices to return. - in: query name: gender schema: anyOf: - $ref: '#/components/schemas/TTSVoiceGender' - type: 'null' description: Only return voices of this gender. required: false description: Only return voices of this gender. - in: query name: age schema: anyOf: - $ref: '#/components/schemas/TTSVoiceAge' - type: 'null' description: Only return voices of this age. required: false description: Only return voices of this age. - in: query name: accent schema: anyOf: - maxLength: 40 type: string - type: 'null' description: Only return voices with this accent. title: Accent required: false description: Only return voices with this accent. - in: query name: use_case schema: anyOf: - items: maxLength: 40 type: string maxItems: 10 type: array - type: 'null' description: Only return voices tagged with every listed use case. Repeat the parameter to pass several values, or separate them with commas. title: Use Case required: false description: Only return voices tagged with every listed use case. Repeat the parameter to pass several values, or separate them with commas. - in: query name: style schema: anyOf: - items: maxLength: 40 type: string maxItems: 10 type: array - type: 'null' description: Only return voices tagged with every listed style. Repeat the parameter to pass several values, or separate them with commas. title: Style required: false description: Only return voices tagged with every listed style. Repeat the parameter to pass several values, or separate them with commas. - in: query name: limit schema: default: 100 description: Maximum number of voices to return. maximum: 200 minimum: 1 title: Limit type: integer required: false description: Maximum number of voices to return. - in: query name: cursor schema: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. Pass the same filters alongside it; the cursor points into the filtered list, not the whole catalogue. title: Cursor required: false description: Pagination cursor for the next page of results. Pass the same filters alongside it; the cursor points into the filtered list, not the whole catalogue. responses: '200': description: List of shared voices matching the filters. content: application/json: schema: $ref: '#/components/schemas/GetSharedVoicesResponse' example: voices: - id: Maya description: A steady, clear voice with a natural presence and measured delivery that feels confident, warm, and easy to listen to. gender: female age: middle_aged accent: british use_case: - conversational style: - smooth - confident - neutral - id: Victoria description: A poised female voice with a refined British accent, smooth pacing, and a lightly textured tone that feels elegant, confident, and composed. gender: female age: middle_aged accent: british use_case: - educational - narration - conversational style: - formal - bright - confident - neutral - calm next_page_cursor: cursor_or_null '400': description: | Invalid request. Error types: - `invalid_request`: The `model` parameter is missing, or a filter or pagination value is invalid (unknown `gender` or `age`, a value longer than 40 characters, more than 10 `use_case` / `style` values, or `limit` outside 1-200). Inspect `validation_errors`. - `invalid_cursor`: The `cursor` parameter is invalid. Omit `cursor` to start pagination from the beginning. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: enum location: query.gender message: Input should be 'male', 'female' or 'neutral' request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | TTS model not found. Error types: - `invalid_request`: No TTS model with this id exists. List the available models with `GET /v1/tts-models` and retry with one of their ids. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 404 error_type: invalid_request message: TTS model 'tts-rt-v0' not found. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate limit for model listing. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for model listing has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Retrieves the shared voices built into a TTS model, optionally filtered by gender, age, accent, use case and style. All given filters must match. For the voices you have cloned yourself, see `GET /v1/voices` instead. tags: - TTS Models security: - PublicApiAuth: [] /tts: post: operationId: generate_tts summary: Generate speech parameters: - in: header name: X-Request-Id schema: type: string required: false description: Optional request ID for tracing. responses: '200': description: | Generated audio stream. Response body contains raw audio bytes. content: audio/pcm: schema: format: binary type: string audio/mpeg: schema: format: binary type: string audio/opus: schema: format: binary type: string audio/flac: schema: format: binary type: string application/octet-stream: schema: format: binary type: string '400': description: | Bad request. The request is malformed or contains invalid parameters. `error_type` is one of [`invalid_request`](https://soniox.com/docs/api-reference/errors#invalid-request) or [`model_not_available`](https://soniox.com/docs/api-reference/errors#model-not-available). Possible messages: - `Invalid JSON body` - `Missing required field: model` - `Model name is too long (max length 50).` - `Missing required field: language` - `Language is too long (max length 50).` - `Missing required field: voice` - `Voice is too long (max length 50).` - `Missing required field: audio_format` - `Audio format is too long (max length 50).` - `Missing required field: text` - `Text is too long (max length 5000).` - `API key is too long (max length 250).` - `Client reference ID is too long (max length 256).` - `Invalid voice '' for model ''.` - `Invalid language '' for model ''.` - `The requested model is not available. See https://soniox.com/docs/tts/models for the list of supported TTS models.` (`error_type: model_not_available`) content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 400 error_type: invalid_request error_message: 'Missing required field: model' more_info: https://soniox.com/docs/api-reference/errors#invalid-request request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '401': description: | Authentication is missing or incorrect. Ensure a valid API key is provided before retrying. `error_type`: [`unauthenticated`](https://soniox.com/docs/api-reference/errors#unauthenticated). Possible messages: - `Missing API key. Provide it as an Authorization header (e.g. 'Authorization: Bearer '). You can get an API key at https://console.soniox.com.` - `Authorization header must use the Bearer scheme (e.g. 'Authorization: Bearer '). You can get an API key at https://console.soniox.com.` - `Incorrect API key provided. You can get an API key at https://console.soniox.com` - `Invalid or expired temporary API key. Create a new temporary API key and retry. See https://soniox.com/docs/guides/temporary-api-keys for details.` - The temporary API key cannot be used for this action. Each temporary API key is scoped to a specific `usage_type`; create a new key with the correct usage type. content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 401 error_type: unauthenticated error_message: Incorrect API key provided. You can get an API key at https://console.soniox.com more_info: https://soniox.com/docs/api-reference/errors#unauthenticated request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '402': description: | The organization's balance or monthly budget has been reached. Additional credits or a higher cap are required before making further requests. `error_type` is one of [`organization_balance_exhausted`](https://soniox.com/docs/api-reference/errors#organization-balance-exhausted), [`organization_monthly_budget_exhausted`](https://soniox.com/docs/api-reference/errors#organization-monthly-budget-exhausted), or [`project_monthly_budget_exhausted`](https://soniox.com/docs/api-reference/errors#project-monthly-budget-exhausted). Possible messages: - `Organization balance exhausted. Please either add funds manually or enable autopay.` - `Organization monthly budget exhausted. Please increase it.` - `Project monthly budget exhausted. Please increase it.` content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 402 error_type: organization_balance_exhausted error_message: Organization balance exhausted. Please either add funds manually or enable autopay. more_info: https://soniox.com/docs/api-reference/errors#organization-balance-exhausted request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '403': description: | The temporary API key in use was created with a `max_session_duration_seconds` cap, and that duration has elapsed for the current session. Create a new temporary API key to start a new session. `error_type`: [`temp_api_key_session_expired`](https://soniox.com/docs/api-reference/errors#temp-api-key-session-expired). Possible messages: - `Temporary API key session duration limit exceeded. Create a new temporary API key to start a new session.` content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 403 error_type: temp_api_key_session_expired error_message: Temporary API key session duration limit exceeded. Create a new temporary API key to start a new session. more_info: https://soniox.com/docs/api-reference/errors#temp-api-key-session-expired request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '408': description: | A backend call exceeded its deadline before completing. Retry the request. `error_type`: [`request_timeout`](https://soniox.com/docs/api-reference/errors#request-timeout). content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 408 error_type: request_timeout error_message: Request timeout. more_info: https://soniox.com/docs/api-reference/errors#request-timeout request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '429': description: | A usage or rate limit has been exceeded. You may retry after a delay or request an increase in limits via the Soniox Console. `error_type`: [`limit_exceeded`](https://soniox.com/docs/api-reference/errors#limit-exceeded). Possible messages: - `Requests per minute limit for text-to-speech has been exceeded for your organization.` - `Requests per minute limit for text-to-speech has been exceeded for your project.` - `Concurrent requests limit for text-to-speech has been exceeded for your organization.` - `Concurrent requests limit for text-to-speech has been exceeded for your project.` content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 429 error_type: limit_exceeded error_message: Requests per minute limit for text-to-speech has been exceeded for your organization. more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '500': description: | An unexpected server-side error occurred. The request may be retried. `error_type`: [`internal_error`](https://soniox.com/docs/api-reference/errors#internal-error). Possible messages: - `The server had an error processing your request. Sorry about that! You can retry your request, or contact us through our support email support@soniox.com if you keep seeing this error.` content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 500 error_type: internal_error error_message: The server had an error processing your request. Sorry about that! You can retry your request, or contact us through our support email support@soniox.com if you keep seeing this error. more_info: https://soniox.com/docs/api-reference/errors#internal-error request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '503': description: | The service cannot accept the request right now (upstream overload, cache exhausted, shutdown). Retry with backoff. The numeric `(code N)` in the message identifies the sub-cause for support triage. `error_type`: [`service_unavailable`](https://soniox.com/docs/api-reference/errors#service-unavailable). Possible messages: - `Cannot continue request (code N). Please restart the request. Refer to: https://soniox.com/url/cannot-continue-request` content: application/json: schema: $ref: '#/components/schemas/TTSApiError' example: error_code: 503 error_type: service_unavailable error_message: 'Cannot continue request (code 11). Please restart the request. Refer to: https://soniox.com/url/cannot-continue-request' more_info: https://soniox.com/docs/api-reference/errors#service-unavailable request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda description: Generates audio from text using the TTS REST endpoint. tags: - TTS servers: - url: https://tts-rt.soniox.com description: Soniox TTS API requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTTSPayload' example: model: tts-rt-v1 language: en voice: Adrian audio_format: wav text: Hello from Soniox Text-to-Speech. sample_rate: 24000 bitrate: 128000 client_reference_id: some_internal_id required: true security: - PublicApiAuth: [] /v1/auth/temporary-api-key: post: operationId: create_temporary_api_key summary: Create temporary API key parameters: [] responses: '201': description: Created temporary API key. content: application/json: schema: $ref: '#/components/schemas/CreateTemporaryApiKeyResponse' example: api_key: snx_temp_AcsDGHvigal7tHRzzzqJI7EdJ5CFwk9C0PtXN_s_cUKJ.Oo1TyosFa7b3rgAcXA2bayqBFO7667gXROEu0mH0U4vgvlNzCqVGgTzitabbXlK7FKH-sSy0F1NKI1OOJzQaAw.YPj4oA expires_at: '2025-02-22T22:47:37.150Z' '400': description: | Invalid request. Error types: - `invalid_request`: One or more body fields are missing or invalid (`usage_type`, `expires_in_seconds` out of range, `client_reference_id` too long, `max_session_duration_seconds` out of range, etc.). Inspect `validation_errors`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: less_than_equal location: body.payload.expires_in_seconds message: Input should be less than or equal to 3600 request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for temporary API key creation has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: | Creates a short-lived API key for specific temporary use cases. The key will automatically expire after the specified duration. Use `single_use` and `max_session_duration_seconds` to limit how the key can be used by a client. See the [Temporary API keys guide](https://soniox.com/docs/guides/temporary-api-keys) for details. tags: - Auth requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTemporaryApiKeyPayload' required: true security: - PublicApiAuth: [] /v1/usage-logs: get: operationId: get_usage_logs summary: Get usage logs parameters: - in: query name: start_time schema: description: Start of the time window (inclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). title: Start Time type: string required: true description: Start of the time window (inclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). - in: query name: end_time schema: description: End of the time window (exclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). title: End Time type: string required: true description: End of the time window (exclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). - in: query name: limit schema: default: 1000 description: Maximum number of usage log entries to return. maximum: 1000 minimum: 1 title: Limit type: integer required: false description: Maximum number of usage log entries to return. - in: query name: sort schema: allOf: - enum: - end_time_asc - end_time_desc title: UsageLogsSort type: string default: end_time_asc description: Sort order by end_time.Use `end_time_desc` to get the most recent entries first. When paginating, pass the same `sort` value alongside the cursor. required: false description: Sort order by end_time.Use `end_time_desc` to get the most recent entries first. When paginating, pass the same `sort` value alongside the cursor. - in: query name: cursor schema: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor required: false description: Pagination cursor for the next page of results. responses: '200': description: Per-request usage log entries. content: application/json: schema: $ref: '#/components/schemas/GetUsageLogsResponse' example: usage_logs: - uuid: 0d1e2f3a-4b5c-6d7e-8f90-1234567890ab request_scope: api client_reference_id: some_internal_id model: stt-async-v3 start_time: '2026-04-28T09:00:00Z' end_time: '2026-04-28T09:00:12Z' input_text_tokens: 42 input_audio_tokens: 12345 input_audio_duration_ms: 12000 output_text_tokens: 678 output_audio_tokens: 256 output_audio_duration_ms: 4500 cost_usd: '0.0081000000' input_cost_usd: '0.0011000000' input_text_cost_usd: '0.0001000000' input_audio_cost_usd: '0.0010000000' output_cost_usd: '0.0070000000' output_text_cost_usd: '0.0050000000' output_audio_cost_usd: '0.0020000000' next_page_cursor: cursor_or_null '400': description: | Invalid request. Error types: - `invalid_request`: A query parameter is missing or invalid. Common causes: `start_time` / `end_time` not parseable as ISO 8601, `end_time` not strictly after `start_time`, the window between them exceeds 31 days, or `cursor` does not match the supplied `start_time` / `end_time` / `sort`. - `invalid_cursor`: The `cursor` parameter is invalid. Omit `cursor` to start pagination from the beginning. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: value_error location: query.payload message: The period between start_time and end_time must not exceed 31 days. request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit for usage logs has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: Returns per-request usage log entries for the project. The project is implied by the API key used for authentication. Filters by request end time. The window between start_time and end_time must not exceed 31 days. start_time must not be earlier than 91 days ago. tags: - Usage logs security: - PublicApiAuth: [] /v1/usage/summary: get: operationId: get_usage_summary summary: Get usage summary parameters: - in: query name: start_time schema: description: Start of the window (inclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-01T00:00:00Z`). Its UTC day is included. title: Start Time type: string required: true description: Start of the window (inclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-01T00:00:00Z`). Its UTC day is included. - in: query name: end_time schema: description: End of the window (exclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-03T00:00:00Z`) and strictly after `start_time`. Its UTC day is included unless it falls exactly on midnight. title: End Time type: string required: true description: End of the window (exclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-03T00:00:00Z`) and strictly after `start_time`. Its UTC day is included unless it falls exactly on midnight. responses: '200': description: Daily cost and activity aggregates. content: application/json: schema: $ref: '#/components/schemas/GetUsageSummaryResponse' example: total: model: null days: - '2026-04-01' - '2026-04-02' total_cost_usd: '0.2567250000' total_input_cost_usd: '0.0415500000' total_output_cost_usd: '0.2151750000' total_duration_cost_usd: '0.0000000000' cost_usd: - '0.1711500000' - '0.0855750000' input_cost_usd: - '0.0277000000' - '0.0138500000' output_cost_usd: - '0.1434500000' - '0.0717250000' duration_cost_usd: - '0.0000000000' - '0.0000000000' total_num_requests: 285 total_input_text_tokens: 4800 total_input_audio_tokens: 15000 total_input_audio_duration_ms: 1800000 total_output_text_tokens: 10800 total_output_audio_tokens: 8250 total_output_audio_duration_ms: 990000 total_duration_ms: 0 num_requests: - 190 - 95 input_text_tokens: - 3200 - 1600 input_audio_tokens: - 10000 - 5000 input_audio_duration_ms: - 1200000 - 600000 output_text_tokens: - 7200 - 3600 output_audio_tokens: - 5500 - 2750 output_audio_duration_ms: - 660000 - 330000 duration_ms: - 0 - 0 models: - model: stt-async-v5 days: - '2026-04-01' - '2026-04-02' total_cost_usd: '0.0613500000' total_input_cost_usd: '0.0235500000' total_output_cost_usd: '0.0378000000' total_duration_cost_usd: '0.0000000000' cost_usd: - '0.0409000000' - '0.0204500000' input_cost_usd: - '0.0157000000' - '0.0078500000' output_cost_usd: - '0.0252000000' - '0.0126000000' duration_cost_usd: - '0.0000000000' - '0.0000000000' total_num_requests: 60 total_input_text_tokens: 300 total_input_audio_tokens: 15000 total_input_audio_duration_ms: 1800000 total_output_text_tokens: 10800 total_output_audio_tokens: 0 total_output_audio_duration_ms: 0 total_duration_ms: 0 num_requests: - 40 - 20 input_text_tokens: - 200 - 100 input_audio_tokens: - 10000 - 5000 input_audio_duration_ms: - 1200000 - 600000 output_text_tokens: - 7200 - 3600 output_audio_tokens: - 0 - 0 output_audio_duration_ms: - 0 - 0 duration_ms: - 0 - 0 - model: tts-rt-v1 days: - '2026-04-01' - '2026-04-02' total_cost_usd: '0.1953750000' total_input_cost_usd: '0.0180000000' total_output_cost_usd: '0.1773750000' total_duration_cost_usd: '0.0000000000' cost_usd: - '0.1302500000' - '0.0651250000' input_cost_usd: - '0.0120000000' - '0.0060000000' output_cost_usd: - '0.1182500000' - '0.0591250000' duration_cost_usd: - '0.0000000000' - '0.0000000000' total_num_requests: 225 total_input_text_tokens: 4500 total_input_audio_tokens: 0 total_input_audio_duration_ms: 0 total_output_text_tokens: 0 total_output_audio_tokens: 8250 total_output_audio_duration_ms: 990000 total_duration_ms: 0 num_requests: - 150 - 75 input_text_tokens: - 3000 - 1500 input_audio_tokens: - 0 - 0 input_audio_duration_ms: - 0 - 0 output_text_tokens: - 0 - 0 output_audio_tokens: - 5500 - 2750 output_audio_duration_ms: - 660000 - 330000 duration_ms: - 0 - 0 '400': description: | Invalid request. Error types: - `invalid_request`: A query parameter is missing or invalid. Common causes: `start_time` / `end_time` not parseable as ISO 8601, `end_time` not strictly after `start_time`, or the window covers more than 366 UTC days. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: value_error location: query.payload message: The window covers 517 UTC days, which exceeds the maximum of 366. request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '404': description: | Not found. Error types: - `not_found`: The project could not be resolved while collecting its usage. Retry, and contact support if it persists. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: | Returns daily cost and activity for the project, broken down per model and summed across all models. The project is implied by the API key used for authentication. Usage is aggregated by whole UTC day. The window is half-open, `[start_time, end_time)`, and a day is included when the window covers any part of it, so an `end_time` exactly at midnight excludes that day. The window must not cover more than 366 UTC days. tags: - Usage summary security: - PublicApiAuth: [] /v1/concurrency-limits: get: operationId: get_concurrency_limits summary: Get concurrency limits parameters: [] responses: '200': description: Current counts and configured limits. content: application/json: schema: $ref: '#/components/schemas/GetConcurrencyLimitsResponse' example: project: current: transcribe_concurrent: 2 tts_concurrent: 0 limits: transcribe_concurrent: 4 tts_concurrent: 1 organization: current: transcribe_concurrent: 5 tts_concurrent: 1 limits: transcribe_concurrent: 10 tts_concurrent: 2 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '429': description: | Rate or usage limit exceeded. Error types: - `limit_exceeded`: - `Requests per minute limit has been exceeded for your organization.` - `Requests per minute limit has been exceeded for your project.` content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda description: Current concurrent counts plus configured concurrency limits for the project and its organization. Region-scoped. tags: - Concurrency Limits security: - PublicApiAuth: [] /v1/concurrent-streams-history: get: operationId: get_concurrent_streams_history summary: Get concurrent streams history parameters: - in: query name: start_time schema: description: Start of the time window (inclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). Filters by `period_start`. title: Start Time type: string required: true description: Start of the time window (inclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). Filters by `period_start`. - in: query name: end_time schema: description: End of the time window (exclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`) and strictly after `start_time`. Filters by `period_start`. title: End Time type: string required: true description: End of the time window (exclusive). Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`) and strictly after `start_time`. Filters by `period_start`. - in: query name: period_sec schema: description: Aggregation period in seconds. One of `60` (per-minute), `3600` (hourly), `86400` (daily). The period also caps how long the requested window may be. enum: - 60 - 3600 - 86400 title: Period Sec type: integer required: true description: Aggregation period in seconds. One of `60` (per-minute), `3600` (hourly), `86400` (daily). The period also caps how long the requested window may be. - in: query name: kind schema: allOf: - enum: - stt - tts title: ConcurrentStreamKind type: string description: Stream kind to return. `stt` covers Speech-to-Text WebSocket sessions, `tts` covers Text-to-Speech WebSocket streams and REST requests. required: true description: Stream kind to return. `stt` covers Speech-to-Text WebSocket sessions, `tts` covers Text-to-Speech WebSocket streams and REST requests. responses: '200': description: Per-period concurrent stream aggregates. content: application/json: schema: $ref: '#/components/schemas/GetConcurrentStreamsHistoryResponse' example: kind: tts entries: - period_start: '2026-04-28T09:00:00Z' period_sec: 60 sample_min: 0 sample_max: 4 sample_sum: 21 sample_count: 9 total_count: 1 - period_start: '2026-04-28T09:01:00Z' period_sec: 60 sample_min: 0 sample_max: 0 sample_sum: 0 sample_count: 0 total_count: 0 '400': description: | Invalid request. Error types: - `invalid_request`: A query parameter is missing or invalid. Common causes: `period_sec` is not one of `60`, `3600`, `86400`, `start_time` / `end_time` not parseable as ISO 8601, `end_time` not strictly after `start_time`, the window between them exceeds the maximum for the requested `period_sec`, or the window would return more than 20000 entries. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 400 error_type: invalid_request message: Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values. validation_errors: - error_type: value_error location: query.payload message: For period_sec=60, the window between `start_time` and `end_time` must not exceed 7 days. request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#invalid-request '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 401 error_type: unauthenticated message: Incorrect API key provided. You can get an API key at https://console.soniox.com validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#unauthenticated '429': description: | Rate / capacity limit exceeded. Error types: - `limit_exceeded`: The caller hit a per-minute request rate or other capacity limit. The `message` describes which limit was hit. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 429 error_type: limit_exceeded message: Requests per minute limit has been exceeded for your organization. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#limit-exceeded '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status_code: 500 error_type: internal_error message: The server encountered an error. Please try again. If the issue persists contact support@soniox.com. validation_errors: [] request_id: 3d37a3bd-5078-47ee-a369-b204e3bbedda more_info: https://soniox.com/docs/api-reference/errors#internal-error description: | Returns historical concurrent stream counts for the project, aggregated per period. The project is implied by the API key used for authentication. Region-scoped. Every aggregation period in the requested window is returned, with no gaps. Periods with no recorded activity have every field set to `0`. tags: - Concurrent streams history security: - PublicApiAuth: [] components: schemas: Voice: properties: id: description: Unique identifier of the voice. format: uuid title: Id type: string name: description: Name of the voice. title: Name type: string filename: description: Original file name of the uploaded audio clip. title: Filename type: string created_at: description: UTC timestamp indicating when the voice was created. format: date-time title: Created At type: string models: description: Voice status for each available model. A model with status 'not_computed' is not prepared yet (e.g. it was released after the voice was created); call recompute to prepare the voice for it. items: $ref: '#/components/schemas/VoiceModel' title: Models type: array required: - id - name - filename - created_at - models title: Voice type: object VoiceModel: properties: model: description: Name of the model. title: Model type: string status: $ref: '#/components/schemas/VoiceModelStatus' description: Has to be 'ready' for the voice to be usable with this model. error_type: anyOf: - type: string - type: 'null' description: Machine-readable error category when status is 'failed'. Stable across releases — safe to use in control flow. `null` otherwise. title: Error Type error_message: anyOf: - type: string - type: 'null' description: Human-readable error message when status is 'failed' (e.g. the reference audio is too long). `null` otherwise. title: Error Message required: - model - status title: VoiceModel type: object VoiceModelStatus: enum: - not_computed - processing - ready - failed title: VoiceModelStatus type: string GetVoicesResponse: properties: voices: description: List of voices. items: $ref: '#/components/schemas/Voice' title: Voices type: array next_page_cursor: anyOf: - type: string - type: 'null' description: A pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available. title: Next Page Cursor required: - voices title: GetVoicesResponse type: object GetVoicesCountResponse: properties: total: description: Total number of voices in your project. title: Total type: integer required: - total title: GetVoicesCountResponse type: object RecomputeVoicePayload: properties: model: anyOf: - type: string - type: 'null' description: The model to prepare this voice for. If omitted, the voice is prepared for every available model it is not ready for yet. title: Model title: RecomputeVoicePayload type: object GetFilesPayload: properties: limit: default: 1000 description: Maximum number of files to return. maximum: 1000 minimum: 1 title: Limit type: integer cursor: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor title: GetFilesPayload type: object File: description: File metadata. example: client_reference_id: some_internal_id created_at: '2024-11-26T00:00:00Z' filename: example.mp3 id: 84c32fc6-4fb5-4e7a-b656-b5ec70493753 size: 123456 properties: id: description: Unique identifier of the file. format: uuid title: Id type: string filename: description: Name of the file. title: Filename type: string size: description: Size of the file in bytes. title: Size type: integer created_at: description: UTC timestamp indicating when the file was uploaded. format: date-time title: Created At type: string client_reference_id: anyOf: - type: string - type: 'null' description: Tracking identifier string. title: Client Reference Id required: - id - filename - size - created_at title: File type: object GetFilesCountResponse: properties: playground: description: Number of files uploaded via the Playground. title: Playground type: integer public_api: description: Number of files uploaded via Public API. title: Public Api type: integer total: description: Total number of files across all sources. title: Total type: integer required: - total - public_api - playground title: GetFilesCountResponse type: object GetFilesResponse: description: A list of files. example: files: - created_at: '2024-11-26T00:00:00Z' filename: example.mp3 id: 84c32fc6-4fb5-4e7a-b656-b5ec70493753 size: 123456 next_page_cursor: cursor_or_null properties: files: description: List of uploaded files. items: $ref: '#/components/schemas/File' title: Files type: array next_page_cursor: anyOf: - type: string - type: 'null' description: A pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available. title: Next Page Cursor required: - files title: GetFilesResponse type: object ApiError: properties: status_code: description: HTTP status code of the response. title: Status Code type: integer error_type: description: | Machine-readable error category. Examples: `invalid_request`, `unauthenticated`, `limit_exceeded`, `model_not_available`, `internal_error`. title: Error Type type: string message: description: Human-readable error message. title: Message type: string validation_errors: description: List of per-field validation errors. Populated only when `error_type` is `invalid_request` and the failure came from request-body validation. items: $ref: '#/components/schemas/ApiErrorValidationError' title: Validation Errors type: array request_id: description: Unique identifier for this request. Include it when contacting support at support@soniox.com so we can look up server-side logs. title: Request Id type: string more_info: anyOf: - type: string - type: 'null' description: | Optional URL with additional information about this error. Points to the Soniox documentation for errors a developer can resolve via code or configuration. title: More Info required: - status_code - error_type - message - validation_errors - request_id title: ApiError type: object ApiErrorValidationError: properties: error_type: title: Error Type type: string location: title: Location type: string message: title: Message type: string required: - error_type - location - message title: ApiErrorValidationError type: object UploadFilePayload: properties: client_reference_id: anyOf: - maxLength: 256 type: string - type: 'null' description: Optional tracking identifier string. Does not need to be unique. title: Client Reference Id title: UploadFilePayload type: object GetTranscriptionsPayload: properties: limit: default: 1000 description: Maximum number of transcriptions to return. maximum: 1000 minimum: 1 title: Limit type: integer cursor: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor title: GetTranscriptionsPayload type: object GetTranscriptionsCountResponse: properties: playground: description: Number of transcriptions created via the Playground. title: Playground type: integer public_api: description: Number of transcriptions created via Public API. title: Public Api type: integer total: description: Total number of transcriptions across all scopes. title: Total type: integer required: - total - public_api - playground title: GetTranscriptionsCountResponse type: object GetTranscriptionsResponse: properties: transcriptions: description: List of transcriptions. items: $ref: '#/components/schemas/Transcription' title: Transcriptions type: array next_page_cursor: anyOf: - type: string - type: 'null' description: A pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available. title: Next Page Cursor required: - transcriptions title: GetTranscriptionsResponse type: object Transcription: description: A transcription. example: audio_duration_ms: 0 audio_url: https://soniox.com/media/examples/coffee_shop.mp3 client_reference_id: some_internal_id created_at: '2024-11-26T00:00:00Z' error_message: null error_type: null file_id: null filename: coffee_shop.mp3 id: 73d4357d-cad2-4338-a60d-ec6f2044f721 language_hints: - en - fr model: stt-async-preview status: queued webhook_auth_header_name: Authorization webhook_auth_header_value: '******************' webhook_status_code: null webhook_url: https://example.com/webhook properties: id: description: Unique identifier for the transcription request. format: uuid title: Id type: string status: $ref: '#/components/schemas/TranscriptionStatus' description: Transcription status. created_at: description: UTC timestamp indicating when the transcription was created. format: date-time title: Created At type: string model: description: Speech-to-text model used for the transcription. title: Model type: string audio_url: anyOf: - type: string - type: 'null' description: URL of the file being transcribed. title: Audio Url file_id: anyOf: - format: uuid type: string - type: 'null' description: ID of the file being transcribed. title: File Id filename: description: Name of the file being transcribed. title: Filename type: string language_hints: anyOf: - items: type: string type: array - type: 'null' description: Expected languages in the audio. If not specified, languages are automatically detected. title: Language Hints enable_speaker_diarization: description: When `true`, speakers are identified and separated in the transcription output. title: Enable Speaker Diarization type: boolean enable_language_identification: description: When `true`, language is detected for each part of the transcription. title: Enable Language Identification type: boolean audio_duration_ms: anyOf: - type: integer - type: 'null' description: Duration of the audio in milliseconds. Only available after processing begins. title: Audio Duration Ms error_type: anyOf: - type: string - type: 'null' description: Error type if transcription failed. `null` for successful or in-progress transcriptions. title: Error Type error_message: anyOf: - type: string - type: 'null' description: Error message if transcription failed. `null` for successful or in-progress transcriptions. title: Error Message webhook_url: anyOf: - type: string - type: 'null' description: URL to receive webhook notifications when transcription is completed or fails. title: Webhook Url webhook_auth_header_name: anyOf: - type: string - type: 'null' description: Name of the authentication header sent with webhook notifications. title: Webhook Auth Header Name webhook_auth_header_value: anyOf: - type: string - type: 'null' description: Authentication header value. Always returned masked as `******************`. title: Webhook Auth Header Value webhook_status_code: anyOf: - type: integer - type: 'null' description: HTTP status code received from your server when webhook was delivered. `null` if not yet sent. title: Webhook Status Code client_reference_id: anyOf: - type: string - type: 'null' description: Tracking identifier string. title: Client Reference Id required: - id - status - created_at - model - filename - enable_speaker_diarization - enable_language_identification title: Transcription type: object TranscriptionStatus: enum: - queued - processing - completed - error title: TranscriptionStatus type: string CreateTranscriptionPayload: properties: model: description: Speech-to-text model to use for the transcription. maxLength: 32 title: Model type: string audio_url: anyOf: - maxLength: 4096 pattern: ^https?://[^\s]+$ type: string - type: 'null' description: URL of the audio file to transcribe. Cannot be specified if `file_id` is specified. title: Audio Url file_id: anyOf: - format: uuid type: string - type: 'null' description: ID of the uploaded file to transcribe. Cannot be specified if `audio_url` is specified. Keep the file until the transcription reaches `completed` or `error`; deleting it earlier fails the transcription with `file_not_found`. title: File Id language_hints: anyOf: - items: maxLength: 10 type: string maxItems: 100 type: array - type: 'null' description: Expected languages in the audio. If not specified, languages are automatically detected. title: Language Hints language_hints_strict: anyOf: - type: boolean - type: 'null' description: When `true`, the model will rely more on language hints. title: Language Hints Strict enable_speaker_diarization: anyOf: - type: boolean - type: 'null' description: When `true`, speakers are identified and separated in the transcription output. title: Enable Speaker Diarization enable_language_identification: anyOf: - type: boolean - type: 'null' description: When `true`, language is detected for each part of the transcription. title: Enable Language Identification translation: anyOf: - $ref: '#/components/schemas/TranslationConfig' - type: 'null' description: Translation configuration. context: anyOf: - $ref: '#/components/schemas/StructuredContext' - type: string - type: 'null' description: Additional context to improve transcription accuracy and formatting of specialized terms. title: Context webhook_url: anyOf: - maxLength: 256 pattern: ^https?://[^\s]+$ type: string - type: 'null' description: URL to receive webhook notifications when transcription is completed or fails. title: Webhook Url webhook_auth_header_name: anyOf: - maxLength: 256 type: string - type: 'null' description: Name of the authentication header sent with webhook notifications. title: Webhook Auth Header Name webhook_auth_header_value: anyOf: - maxLength: 256 type: string - type: 'null' description: Authentication header value sent with webhook notifications. title: Webhook Auth Header Value client_reference_id: anyOf: - maxLength: 256 type: string - type: 'null' description: Optional tracking identifier string. Does not need to be unique. title: Client Reference Id required: - model title: CreateTranscriptionPayload type: object StructuredContext: properties: general: anyOf: - items: $ref: '#/components/schemas/StructuredContextGeneralItem' type: array - type: 'null' description: General context items. title: General text: anyOf: - type: string - type: 'null' description: Text context. title: Text terms: anyOf: - items: type: string type: array - type: 'null' description: Terms that might occur in speech. title: Terms translation_terms: anyOf: - items: $ref: '#/components/schemas/StructuredContextTranslationTerm' type: array - type: 'null' description: Hints how to translate specific terms. Ignored if translation is not enabled. title: Translation Terms title: StructuredContext type: object StructuredContextGeneralItem: properties: key: description: Item key (e.g. "Domain"). title: Key type: string value: description: Item value (e.g. "medicine"). title: Value type: string required: - key - value title: StructuredContextGeneralItem type: object StructuredContextTranslationTerm: properties: source: description: Source term. title: Source type: string target: description: Target term to translate to. title: Target type: string required: - source - target title: StructuredContextTranslationTerm type: object TranslationConfig: properties: type: enum: - one_way - two_way title: Type type: string target_language: anyOf: - type: string - type: 'null' title: Target Language language_a: anyOf: - type: string - type: 'null' title: Language A language_b: anyOf: - type: string - type: 'null' title: Language B required: - type title: TranslationConfig type: object TranscriptionTranscript: description: The transcription text. example: id: 19b6d61d-02db-4c25-bc71-b4094dc310c8 text: Hello tokens: - confidence: 0.95 end_ms: 90 start_ms: 10 text: Hel - confidence: 0.98 end_ms: 160 start_ms: 110 text: lo properties: id: description: Unique identifier of the transcription this transcript belongs to. format: uuid title: Id type: string text: description: Complete transcribed text content. title: Text type: string tokens: description: List of detailed token information with timestamps and metadata. items: $ref: '#/components/schemas/TranscriptionTranscriptToken' title: Tokens type: array required: - id - text - tokens title: TranscriptionTranscript type: object TranscriptionTranscriptToken: description: The transcript token. example: confidence: 0.95 end_ms: 90 start_ms: 10 text: Hel properties: text: description: Token text content. title: Text type: string start_ms: description: Start time of the token in milliseconds. title: Start Ms type: integer end_ms: description: End time of the token in milliseconds. title: End Ms type: integer confidence: description: Confidence score of the token, between 0.0 and 1.0. title: Confidence type: number speaker: anyOf: - type: string - type: 'null' description: Speaker identifier. Only present when speaker diarization is enabled. title: Speaker language: anyOf: - type: string - type: 'null' description: Detected language code for this token. Only present when language identification is enabled. title: Language is_audio_event: anyOf: - type: boolean - type: 'null' description: Boolean indicating if this token represents an audio event. Only present when audio event detection is enabled. title: Is Audio Event translation_status: anyOf: - type: string - type: 'null' description: Translation status ("none", "original" or "translation"). Only when if translation is enabled. title: Translation Status required: - text - start_ms - end_ms - confidence title: TranscriptionTranscriptToken type: object GetModelsResponse: example: models: - aliased_model_id: null context_version: 2 id: stt-rt-v4 languages: - code: af name: Afrikaans - code: sq name: Albanian - code: ar name: Arabic - code: az name: Azerbaijani - code: eu name: Basque - code: be name: Belarusian - code: bn name: Bengali - code: bs name: Bosnian - code: bg name: Bulgarian - code: ca name: Catalan - code: zh name: Chinese - code: hr name: Croatian - code: cs name: Czech - code: da name: Danish - code: nl name: Dutch - code: en name: English - code: et name: Estonian - code: fi name: Finnish - code: fr name: French - code: gl name: Galician - code: de name: German - code: el name: Greek - code: gu name: Gujarati - code: he name: Hebrew - code: hi name: Hindi - code: hu name: Hungarian - code: id name: Indonesian - code: it name: Italian - code: ja name: Japanese - code: kn name: Kannada - code: kk name: Kazakh - code: ko name: Korean - code: lv name: Latvian - code: lt name: Lithuanian - code: mk name: Macedonian - code: ms name: Malay - code: ml name: Malayalam - code: mr name: Marathi - code: 'no' name: Norwegian - code: fa name: Persian - code: pl name: Polish - code: pt name: Portuguese - code: pa name: Punjabi - code: ro name: Romanian - code: ru name: Russian - code: sr name: Serbian - code: sk name: Slovak - code: sl name: Slovenian - code: es name: Spanish - code: sw name: Swahili - code: sv name: Swedish - code: tl name: Tagalog - code: ta name: Tamil - code: te name: Telugu - code: th name: Thai - code: tr name: Turkish - code: uk name: Ukrainian - code: ur name: Urdu - code: vi name: Vietnamese - code: cy name: Welsh name: Speech-to-Text Real-time v4 one_way_translation: all_languages endpoint_latency_adjustment_max_level: 0 supports_endpoint_latency_adjustment: false supports_endpoint_sensitivity: false supports_language_hints_strict: true supports_max_endpoint_delay: true transcription_mode: real_time translation_targets: [] two_way_translation: all_languages two_way_translation_pairs: [] - aliased_model_id: null context_version: 2 id: stt-rt-v3 languages: - code: af name: Afrikaans - code: sq name: Albanian - code: ar name: Arabic - code: az name: Azerbaijani - code: eu name: Basque - code: be name: Belarusian - code: bn name: Bengali - code: bs name: Bosnian - code: bg name: Bulgarian - code: ca name: Catalan - code: zh name: Chinese - code: hr name: Croatian - code: cs name: Czech - code: da name: Danish - code: nl name: Dutch - code: en name: English - code: et name: Estonian - code: fi name: Finnish - code: fr name: French - code: gl name: Galician - code: de name: German - code: el name: Greek - code: gu name: Gujarati - code: he name: Hebrew - code: hi name: Hindi - code: hu name: Hungarian - code: id name: Indonesian - code: it name: Italian - code: ja name: Japanese - code: kn name: Kannada - code: kk name: Kazakh - code: ko name: Korean - code: lv name: Latvian - code: lt name: Lithuanian - code: mk name: Macedonian - code: ms name: Malay - code: ml name: Malayalam - code: mr name: Marathi - code: 'no' name: Norwegian - code: fa name: Persian - code: pl name: Polish - code: pt name: Portuguese - code: pa name: Punjabi - code: ro name: Romanian - code: ru name: Russian - code: sr name: Serbian - code: sk name: Slovak - code: sl name: Slovenian - code: es name: Spanish - code: sw name: Swahili - code: sv name: Swedish - code: tl name: Tagalog - code: ta name: Tamil - code: te name: Telugu - code: th name: Thai - code: tr name: Turkish - code: uk name: Ukrainian - code: ur name: Urdu - code: vi name: Vietnamese - code: cy name: Welsh name: Speech-to-Text Real-time v3 one_way_translation: all_languages endpoint_latency_adjustment_max_level: 0 supports_endpoint_latency_adjustment: false supports_endpoint_sensitivity: false supports_language_hints_strict: true supports_max_endpoint_delay: false transcription_mode: real_time translation_targets: [] two_way_translation: all_languages two_way_translation_pairs: [] - aliased_model_id: null context_version: 2 id: stt-async-v4 languages: - code: af name: Afrikaans - code: sq name: Albanian - code: ar name: Arabic - code: az name: Azerbaijani - code: eu name: Basque - code: be name: Belarusian - code: bn name: Bengali - code: bs name: Bosnian - code: bg name: Bulgarian - code: ca name: Catalan - code: zh name: Chinese - code: hr name: Croatian - code: cs name: Czech - code: da name: Danish - code: nl name: Dutch - code: en name: English - code: et name: Estonian - code: fi name: Finnish - code: fr name: French - code: gl name: Galician - code: de name: German - code: el name: Greek - code: gu name: Gujarati - code: he name: Hebrew - code: hi name: Hindi - code: hu name: Hungarian - code: id name: Indonesian - code: it name: Italian - code: ja name: Japanese - code: kn name: Kannada - code: kk name: Kazakh - code: ko name: Korean - code: lv name: Latvian - code: lt name: Lithuanian - code: mk name: Macedonian - code: ms name: Malay - code: ml name: Malayalam - code: mr name: Marathi - code: 'no' name: Norwegian - code: fa name: Persian - code: pl name: Polish - code: pt name: Portuguese - code: pa name: Punjabi - code: ro name: Romanian - code: ru name: Russian - code: sr name: Serbian - code: sk name: Slovak - code: sl name: Slovenian - code: es name: Spanish - code: sw name: Swahili - code: sv name: Swedish - code: tl name: Tagalog - code: ta name: Tamil - code: te name: Telugu - code: th name: Thai - code: tr name: Turkish - code: uk name: Ukrainian - code: ur name: Urdu - code: vi name: Vietnamese - code: cy name: Welsh name: Speech-to-Text Async v4 one_way_translation: all_languages endpoint_latency_adjustment_max_level: 0 supports_endpoint_latency_adjustment: false supports_endpoint_sensitivity: false supports_language_hints_strict: true supports_max_endpoint_delay: false transcription_mode: async translation_targets: [] two_way_translation: all_languages two_way_translation_pairs: [] - aliased_model_id: null context_version: 2 id: stt-async-v3 languages: - code: af name: Afrikaans - code: sq name: Albanian - code: ar name: Arabic - code: az name: Azerbaijani - code: eu name: Basque - code: be name: Belarusian - code: bn name: Bengali - code: bs name: Bosnian - code: bg name: Bulgarian - code: ca name: Catalan - code: zh name: Chinese - code: hr name: Croatian - code: cs name: Czech - code: da name: Danish - code: nl name: Dutch - code: en name: English - code: et name: Estonian - code: fi name: Finnish - code: fr name: French - code: gl name: Galician - code: de name: German - code: el name: Greek - code: gu name: Gujarati - code: he name: Hebrew - code: hi name: Hindi - code: hu name: Hungarian - code: id name: Indonesian - code: it name: Italian - code: ja name: Japanese - code: kn name: Kannada - code: kk name: Kazakh - code: ko name: Korean - code: lv name: Latvian - code: lt name: Lithuanian - code: mk name: Macedonian - code: ms name: Malay - code: ml name: Malayalam - code: mr name: Marathi - code: 'no' name: Norwegian - code: fa name: Persian - code: pl name: Polish - code: pt name: Portuguese - code: pa name: Punjabi - code: ro name: Romanian - code: ru name: Russian - code: sr name: Serbian - code: sk name: Slovak - code: sl name: Slovenian - code: es name: Spanish - code: sw name: Swahili - code: sv name: Swedish - code: tl name: Tagalog - code: ta name: Tamil - code: te name: Telugu - code: th name: Thai - code: tr name: Turkish - code: uk name: Ukrainian - code: ur name: Urdu - code: vi name: Vietnamese - code: cy name: Welsh name: Speech-to-Text Async v3 one_way_translation: all_languages endpoint_latency_adjustment_max_level: 0 supports_endpoint_latency_adjustment: false supports_endpoint_sensitivity: false supports_language_hints_strict: false supports_max_endpoint_delay: false transcription_mode: async translation_targets: [] two_way_translation: all_languages two_way_translation_pairs: [] properties: models: description: List of available models and their attributes. items: $ref: '#/components/schemas/Model' title: Models type: array required: - models title: GetModelsResponse type: object Language: properties: code: description: 2-letter language code. title: Code type: string name: description: Language name. title: Name type: string required: - code - name title: Language type: object Model: properties: id: description: Unique identifier of the model. title: Id type: string aliased_model_id: anyOf: - type: string - type: 'null' description: If this is an alias, the id of the aliased model. title: Aliased Model Id name: description: Name of the model. title: Name type: string context_version: anyOf: - type: integer - type: 'null' description: Version of context supported. title: Context Version transcription_mode: $ref: '#/components/schemas/TranscriptionMode' description: Transcription mode of the model. languages: description: List of languages supported by the model. items: $ref: '#/components/schemas/Language' title: Languages type: array supports_language_hints_strict: title: Supports Language Hints Strict type: boolean supports_max_endpoint_delay: title: Supports Max Endpoint Delay type: boolean supports_endpoint_sensitivity: title: Supports Endpoint Sensitivity type: boolean supports_endpoint_latency_adjustment: title: Supports Endpoint Latency Adjustment type: boolean endpoint_latency_adjustment_max_level: description: Maximum endpoint_latency_adjustment_level the model accepts. Valid levels are 0 (no adjustment) through this value; 0 means the feature is unsupported. title: Endpoint Latency Adjustment Max Level type: integer translation_targets: description: List of supported one-way translation targets. If list is empty, check for one_way_translation field items: $ref: '#/components/schemas/TranslationTarget' title: Translation Targets type: array two_way_translation_pairs: description: List of supported two-way translation pairs. If list is empty, check for two_way_translation field items: type: string title: Two Way Translation Pairs type: array one_way_translation: anyOf: - type: string - type: 'null' description: When contains string 'all_languages', any laguage from languages can be used title: One Way Translation two_way_translation: anyOf: - type: string - type: 'null' description: When contains string 'all_languages',' any laguage pair from languages can be used title: Two Way Translation required: - id - aliased_model_id - name - context_version - transcription_mode - languages - supports_language_hints_strict - supports_max_endpoint_delay - supports_endpoint_sensitivity - supports_endpoint_latency_adjustment - endpoint_latency_adjustment_max_level - translation_targets - two_way_translation_pairs - one_way_translation - two_way_translation title: Model type: object TranscriptionMode: enum: - real_time - async title: TranscriptionMode type: string TranslationTarget: properties: target_language: title: Target Language type: string source_languages: items: type: string title: Source Languages type: array exclude_source_languages: items: type: string title: Exclude Source Languages type: array required: - target_language - source_languages - exclude_source_languages title: TranslationTarget type: object GetTTSModelsResponse: example: models: - aliased_model_id: null id: tts-rt-v1 name: TTS v1 languages: - code: af name: Afrikaans - code: ar name: Arabic - code: az name: Azerbaijani - code: be name: Belarusian - code: bg name: Bulgarian - code: bn name: Bengali - code: bs name: Bosnian - code: ca name: Catalan - code: cs name: Czech - code: cy name: Welsh - code: da name: Danish - code: de name: German - code: el name: Greek - code: en name: English - code: es name: Spanish - code: et name: Estonian - code: eu name: Basque - code: fa name: Persian - code: fi name: Finnish - code: fr name: French - code: gl name: Galician - code: gu name: Gujarati - code: he name: Hebrew - code: hi name: Hindi - code: hr name: Croatian - code: hu name: Hungarian - code: id name: Indonesian - code: is name: Icelandic - code: it name: Italian - code: ja name: Japanese - code: kk name: Kazakh - code: kn name: Kannada - code: ko name: Korean - code: lt name: Lithuanian - code: lv name: Latvian - code: mk name: Macedonian - code: ml name: Malayalam - code: mr name: Marathi - code: ms name: Malay - code: nl name: Dutch - code: 'no' name: Norwegian - code: pa name: Punjabi - code: pl name: Polish - code: pt name: Portuguese - code: ro name: Romanian - code: ru name: Russian - code: sk name: Slovak - code: sl name: Slovenian - code: sq name: Albanian - code: sr name: Serbian - code: su name: Sundanese - code: sv name: Swedish - code: sw name: Swahili - code: ta name: Tamil - code: te name: Telugu - code: th name: Thai - code: tl name: Tagalog - code: tr name: Turkish - code: uk name: Ukrainian - code: ur name: Urdu - code: vi name: Vietnamese - code: zh name: Chinese voices: - id: Maya description: A steady, clear voice with a natural presence and measured delivery that feels confident, warm, and easy to listen to. gender: female - id: Daniel description: A rich, steady male voice with a polished tone, controlled pacing, and a reassuring presence that feels confident and mature. gender: male - id: Noah description: A lively, youthful male voice with crisp clarity, quick natural pacing, and an upbeat tone that feels friendly, expressive, and modern. gender: male - id: Nina description: A bright, expressive female voice with youthful energy, natural rhythm, and a friendly tone that feels warm, engaging, and full of personality. gender: female - id: Emma description: A smooth, natural female voice with a relaxed pace, subtle warmth, and a contemporary tone that feels confident, personable, and easygoing. gender: female - id: Jack description: A friendly, confident male voice with clear articulation, steady energy, and a natural tone that feels approachable, upbeat, and sincere. gender: male - id: Adrian description: A deep, focused male voice with crisp articulation, measured pacing, and a composed tone that feels authoritative, clear, and professional. gender: male - id: Claire description: A polished, articulate female voice with a bright tone, smooth pacing, and a confident presence that feels refined, clear, and approachable. gender: female - id: Grace description: A gentle, soothing female voice with soft clarity, unhurried pacing, and a reassuring tone that feels kind, calm, and comforting. gender: female - id: Owen description: A grounded male voice with even pacing and a dry, composed tone that feels steady, natural, and quietly confident. gender: male - id: Mina description: A soft, thoughtful female voice with gentle clarity, steady pacing, and a warm tone that feels composed, sincere, and easy to listen to. gender: female - id: Kenji description: A calm, precise male voice with smooth clarity, balanced pacing, and a composed tone that feels respectful, modern, and trustworthy. gender: male - id: Rafael description: A clear, composed male voice with a warm Spanish accent, balanced pacing, and a confident tone that feels approachable and precise. gender: male - id: Mateo description: A warm, youthful male voice with a soft Spanish accent, clear pacing, and an open tone that feels sincere, friendly, and optimistic. gender: male - id: Lucia description: A clear, mature female voice with a natural Spanish accent, steady pacing, and a composed tone that feels warm, focused, and approachable. gender: female - id: Sofia description: A bright, friendly female voice with a natural Spanish accent, clear articulation, and an inviting tone that feels warm, confident, and easy to follow. gender: female - id: Oliver description: A refined male voice with a smooth British accent, gentle pacing, and a calm tone that feels trustworthy, articulate, and reassuring. gender: male - id: Arthur description: A deep, mature male voice with a rich British accent, measured pacing, and a textured tone that feels composed, assured, and quietly powerful. gender: male - id: Isla description: A lively female voice with a bright British accent, clear delivery, and expressive energy that feels fresh, friendly, and naturally engaging. gender: female - id: Victoria description: A poised female voice with a refined British accent, smooth pacing, and a lightly textured tone that feels elegant, confident, and composed. gender: female - id: Cooper description: A bold male voice with a strong Australian accent, relaxed pacing, and a casual tone that feels confident, rugged, and easygoing. gender: male - id: Mason description: A relaxed male voice with a natural Australian accent, smooth pacing, and a casual tone that feels friendly, grounded, and effortlessly confident. gender: male - id: Ruby description: A confident female voice with a natural Australian accent, lively pacing, and a warm tone that feels personable, sharp, and engaging. gender: female - id: Elise description: A warm female voice with a natural Australian accent, clear pronunciation, and a confident tone that feels supportive, polished, and easy to follow. gender: female - id: Arjun description: A deep male voice with a natural Indian accent, warm resonance, and an easygoing tone that feels friendly, grounded, and confident. gender: male - id: Rohan description: A lively male voice with a natural Indian accent, expressive rhythm, and confident energy that feels charismatic, upbeat, and full of personality. gender: male - id: Priya description: A clear female voice with a natural Indian accent, warm pacing, and a composed tone that feels helpful, attentive, and easy to trust. gender: female - id: Meera description: A polished female voice with a natural Indian accent, crisp articulation, and a steady tone that feels professional, reassuring, and dependable. gender: female properties: models: description: List of available TTS models and their attributes. items: $ref: '#/components/schemas/TTSModel' title: Models type: array required: - models title: GetTTSModelsResponse type: object TTSModel: properties: id: description: Unique identifier of the model. title: Id type: string aliased_model_id: anyOf: - type: string - type: 'null' description: If this is an alias, the id of the aliased model. title: Aliased Model Id name: description: Name of the model. title: Name type: string languages: description: List of languages supported by the model. items: $ref: '#/components/schemas/Language' title: Languages type: array voices: description: List of available voices for this model. items: $ref: '#/components/schemas/TTSVoice' title: Voices type: array supports_timestamps: title: Does this model support returning timestamps for generated audio? type: boolean supports_voice_cloning: description: Whether the model supports voice cloning, that is voices created with `POST /v1/voices`. title: Supports Voice Cloning type: boolean voice_cloning_max_audio_duration_ms: anyOf: - type: integer - type: 'null' description: Maximum duration (in milliseconds) of the reference audio accepted for voice cloning. Null when the model does not support voice cloning. title: Voice Cloning Max Audio Duration Ms supports_speed_adjustment: description: Whether the model supports adjusting the speaking rate via the `speed` parameter. title: Supports Speed Adjustment type: boolean speed_min: anyOf: - type: number - type: 'null' description: Minimum supported speaking rate. Null when the model does not support speed adjustment. title: Speed Min speed_max: anyOf: - type: number - type: 'null' description: Maximum supported speaking rate. Null when the model does not support speed adjustment. title: Speed Max supports_silence_reduction: description: Whether the model supports shortening the pauses between words via the `reduce_silence` parameter. title: Supports Silence Reduction type: boolean required: - id - aliased_model_id - name - languages - voices - supports_timestamps - supports_voice_cloning - voice_cloning_max_audio_duration_ms - supports_speed_adjustment - speed_min - speed_max - supports_silence_reduction title: TTSModel type: object TTSVoice: properties: id: description: Unique identifier of the voice. title: Id type: string description: description: Description of the TTS voice. title: Description type: string gender: $ref: '#/components/schemas/TTSVoiceGender' description: Gender of the TTS voice. required: - id - description - gender title: TTSVoice type: object TTSVoiceGender: enum: - male - female - neutral title: TTSVoiceGender type: string TTSVoiceAge: enum: - young - middle_aged - old title: TTSVoiceAge type: string TTSVoiceDetails: properties: id: description: Unique identifier of the voice. title: Id type: string description: description: Description of the TTS voice. title: Description type: string gender: $ref: '#/components/schemas/TTSVoiceGender' description: Gender of the TTS voice. age: $ref: '#/components/schemas/TTSVoiceAge' description: Perceived age of the speaker. accent: description: Accent of the voice, e.g. `american`, `british`. title: Accent type: string use_case: description: Tags describing what the voice is suited for, e.g. `narration`, `conversational`. items: type: string title: Use Case type: array style: description: Tags describing how the voice sounds, e.g. `warm`, `energetic`. items: type: string title: Style type: array required: - id - description - gender - age - accent - use_case - style title: TTSVoiceDetails type: object GetSharedVoicesResponse: properties: voices: description: List of voices matching the filters. items: $ref: '#/components/schemas/TTSVoiceDetails' title: Voices type: array next_page_cursor: anyOf: - type: string - type: 'null' description: A pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available. title: Next Page Cursor required: - voices title: GetSharedVoicesResponse type: object CreateTTSPayload: example: model: tts-rt-v1 language: en voice: Adrian audio_format: wav text: Hello from Soniox Text-to-Speech. sample_rate: 24000 bitrate: 128000 client_reference_id: some_internal_id speed: 1.2 reduce_silence: true properties: model: default: tts-rt-v1 description: TTS model to use. title: Model type: string language: description: Language code of the input text. title: Language type: string voice: description: 'Voice to use: a built-in voice name (for example `Adrian`) or the ID of a [cloned voice](https://soniox.com/docs/tts/concepts/voice-cloning).' title: Voice type: string audio_format: description: Output audio format (for example `mp3`, `wav`, `pcm_s16le`, `pcm_s16be`). title: Audio Format type: string text: description: Input text to generate audio from. title: Text type: string sample_rate: anyOf: - type: integer - type: 'null' description: Optional output sample rate in Hz. title: Sample Rate bitrate: anyOf: - type: integer - type: 'null' description: Optional output bitrate in bits per second. title: Bitrate client_reference_id: anyOf: - maxLength: 256 type: string - type: 'null' description: Optional tracking identifier string. Does not need to be unique. Ignored if the request authenticates with a temporary API key. title: Client Reference Id speed: anyOf: - type: number - type: 'null' description: Optional speaking rate of the generated speech, from `0.7` to `1.3`. `1.0` is the normal speed; lower values slow speech down and higher values speed it up. Defaults to `1.0`. title: Speed reduce_silence: anyOf: - type: boolean - type: 'null' description: Optional. When `true`, shortens the pauses between words so the generated speech flows more naturally. Defaults to `false`. Only supported on models with `supports_silence_reduction` set to `true`; enabling it on any other model returns an `invalid_request` error. title: Reduce Silence required: - model - language - voice - audio_format - text title: CreateTTSPayload type: object TTSApiError: properties: error_code: description: HTTP status code for the error. title: Error Code type: integer error_type: description: | Machine-readable error category. Branch your client on this value, not on `error_message`. See the [Errors reference](https://soniox.com/docs/api-reference/errors) for the full catalog. Examples: `invalid_request`, `unauthenticated`, `limit_exceeded`, `service_unavailable`, `internal_error`. title: Error Type type: string error_message: description: Human-readable error message. title: Error Message type: string more_info: anyOf: - type: string - type: 'null' description: | Optional URL pointing to the section on the Soniox docs error reference page that describes this `error_type`. title: More Info request_id: description: | Unique identifier for this request. Include it when contacting support at support@soniox.com so we can look up server-side logs. title: Request Id type: string required: - error_code - error_type - error_message - request_id title: TTSApiError type: object CreateTemporaryApiKeyResponse: example: api_key: snx_temp_AcsDGHvigal7tHRzzzqJI7EdJ5CFwk9C0PtXN_s_cUKJ.Oo1TyosFa7b3rgAcXA2bayqBFO7667gXROEu0mH0U4vgvlNzCqVGgTzitabbXlK7FKH-sSy0F1NKI1OOJzQaAw.YPj4oA expires_at: '2025-02-22T22:47:37.150Z' properties: api_key: description: Created temporary API key. title: Api Key type: string expires_at: description: UTC timestamp indicating when generated temporary API key will expire. format: date-time title: Expires At type: string required: - api_key - expires_at title: CreateTemporaryApiKeyResponse type: object CreateTemporaryApiKeyPayload: example: client_reference_id: reference_id expires_in_seconds: 1800 max_session_duration_seconds: 120 single_use: true usage_type: transcribe_websocket properties: usage_type: $ref: '#/components/schemas/TemporaryApiKeyUsageType' description: Intended usage of the temporary API key. expires_in_seconds: description: Duration in seconds until the temporary API key expires. maximum: 3600 minimum: 1 title: Expires In Seconds type: integer client_reference_id: anyOf: - maxLength: 256 type: string - type: 'null' description: Optional tracking identifier string. Does not need to be unique. title: Client Reference Id single_use: anyOf: - type: boolean - type: 'null' description: If true, the temporary API key can be used only once. title: Single Use max_session_duration_seconds: anyOf: - maximum: 18000 minimum: 1 type: integer - type: 'null' description: Maximum connection duration in seconds for WebSocket and TTS HTTP streaming endpoints. If exceeded, the connection will be dropped. If not set, no limit is applied. title: Max Session Duration Seconds required: - usage_type - expires_in_seconds title: CreateTemporaryApiKeyPayload type: object TemporaryApiKeyUsageType: enum: - transcribe_websocket - tts_rt title: TemporaryApiKeyUsageType type: string UsageLogsSort: enum: - end_time_asc - end_time_desc title: UsageLogsSort type: string GetUsageLogsPayload: properties: start_time: description: Start of the time window (inclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). title: Start Time type: string end_time: description: End of the time window (exclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. `2026-04-28T09:00:00Z`). title: End Time type: string limit: default: 1000 description: Maximum number of usage log entries to return. maximum: 1000 minimum: 1 title: Limit type: integer sort: allOf: - enum: - end_time_asc - end_time_desc title: UsageLogsSort type: string default: end_time_asc description: Sort order by end_time.Use `end_time_desc` to get the most recent entries first. When paginating, pass the same `sort` value alongside the cursor. cursor: anyOf: - type: string - type: 'null' description: Pagination cursor for the next page of results. title: Cursor required: - start_time - end_time title: GetUsageLogsPayload type: object GetUsageLogsResponse: properties: usage_logs: description: Per-request usage log entries ordered by end_time, uuid (per `sort`). items: $ref: '#/components/schemas/UsageLogEntry' title: Usage Logs type: array next_page_cursor: anyOf: - type: string - type: 'null' description: A pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available. title: Next Page Cursor required: - usage_logs title: GetUsageLogsResponse type: object UsageLogEntry: properties: uuid: description: Unique identifier of the request. format: uuid title: Uuid type: string request_scope: description: Scope of the request (api / playground). title: Request Scope type: string client_reference_id: description: Client reference ID supplied on the original request. Empty string if none. title: Client Reference Id type: string model: description: Model identifier. title: Model type: string start_time: description: When the request started. format: date-time title: Start Time type: string end_time: description: When the request ended. format: date-time title: End Time type: string input_text_tokens: title: Input Text Tokens type: integer input_audio_tokens: title: Input Audio Tokens type: integer input_audio_duration_ms: title: Input Audio Duration Ms type: integer output_text_tokens: title: Output Text Tokens type: integer output_audio_tokens: title: Output Audio Tokens type: integer output_audio_duration_ms: title: Output Audio Duration Ms type: integer cost_usd: title: Cost Usd type: string input_cost_usd: title: Input Cost Usd type: string input_text_cost_usd: title: Input Text Cost Usd type: string input_audio_cost_usd: title: Input Audio Cost Usd type: string output_cost_usd: title: Output Cost Usd type: string output_text_cost_usd: title: Output Text Cost Usd type: string output_audio_cost_usd: title: Output Audio Cost Usd type: string required: - uuid - request_scope - client_reference_id - model - start_time - end_time - input_text_tokens - input_audio_tokens - input_audio_duration_ms - output_text_tokens - output_audio_tokens - output_audio_duration_ms - cost_usd - input_cost_usd - input_text_cost_usd - input_audio_cost_usd - output_cost_usd - output_text_cost_usd - output_audio_cost_usd title: UsageLogEntry type: object GetUsageSummaryResponse: properties: total: allOf: - $ref: '#/components/schemas/UsageSummaryEntry' description: Cost and activity across all models. Its `model` is `null`. models: description: One entry per model that recorded usage in the window. Empty when the project had no usage. items: $ref: '#/components/schemas/UsageSummaryEntry' title: Models type: array required: - total - models title: GetUsageSummaryResponse type: object UsageSummaryEntry: properties: model: anyOf: - type: string - type: 'null' description: Model identifier. `null` on the `total` entry. title: Model days: description: One UTC day (`YYYY-MM-DD`) per element, in ascending order. Every day in the requested window is present, including days with no usage. All the per-day arrays below align to this axis. items: format: date type: string title: Days type: array total_cost_usd: description: Total cost over the window, in USD. Equals `total_input_cost_usd` + `total_output_cost_usd` + `total_duration_cost_usd`. title: Total Cost Usd type: string total_input_cost_usd: description: Total cost of input tokens over the window, in USD. title: Total Input Cost Usd type: string total_output_cost_usd: description: Total cost of output tokens over the window, in USD. title: Total Output Cost Usd type: string total_duration_cost_usd: description: Total cost over the window for models billed by session duration rather than by tokens, in USD. `0` for Speech-to-Text and Text-to-Speech models. title: Total Duration Cost Usd type: string cost_usd: description: Cost per day, in USD, aligned to `days`. items: type: string title: Cost Usd type: array input_cost_usd: description: Cost of input tokens per day, in USD, aligned to `days`. items: type: string title: Input Cost Usd type: array output_cost_usd: description: Cost of output tokens per day, in USD, aligned to `days`. items: type: string title: Output Cost Usd type: array duration_cost_usd: description: Duration-billed cost per day, in USD, aligned to `days`. items: type: string title: Duration Cost Usd type: array total_num_requests: description: Number of requests over the window. title: Total Num Requests type: integer total_input_text_tokens: title: Total Input Text Tokens type: integer total_input_audio_tokens: title: Total Input Audio Tokens type: integer total_input_audio_duration_ms: title: Total Input Audio Duration Ms type: integer total_output_text_tokens: title: Total Output Text Tokens type: integer total_output_audio_tokens: title: Total Output Audio Tokens type: integer total_output_audio_duration_ms: title: Total Output Audio Duration Ms type: integer total_duration_ms: description: Billed session duration over the window, in milliseconds, for models billed by duration. `0` for Speech-to-Text and Text-to-Speech models. title: Total Duration Ms type: integer num_requests: description: Number of requests per day, aligned to `days`. items: type: integer title: Num Requests type: array input_text_tokens: items: type: integer title: Input Text Tokens type: array input_audio_tokens: items: type: integer title: Input Audio Tokens type: array input_audio_duration_ms: items: type: integer title: Input Audio Duration Ms type: array output_text_tokens: items: type: integer title: Output Text Tokens type: array output_audio_tokens: items: type: integer title: Output Audio Tokens type: array output_audio_duration_ms: items: type: integer title: Output Audio Duration Ms type: array duration_ms: description: Billed session duration per day, in milliseconds, aligned to `days`. items: type: integer title: Duration Ms type: array required: - days - total_cost_usd - total_input_cost_usd - total_output_cost_usd - total_duration_cost_usd - cost_usd - input_cost_usd - output_cost_usd - duration_cost_usd - total_num_requests - total_input_text_tokens - total_input_audio_tokens - total_input_audio_duration_ms - total_output_text_tokens - total_output_audio_tokens - total_output_audio_duration_ms - total_duration_ms - num_requests - input_text_tokens - input_audio_tokens - input_audio_duration_ms - output_text_tokens - output_audio_tokens - output_audio_duration_ms - duration_ms title: UsageSummaryEntry type: object GetConcurrencyLimitsResponse: properties: project: $ref: '#/components/schemas/ScopeValues' organization: $ref: '#/components/schemas/ScopeValues' required: - project - organization title: GetConcurrencyLimitsResponse type: object ScopeValues: properties: current: $ref: '#/components/schemas/CurrentValues' limits: $ref: '#/components/schemas/LimitValues' required: - current - limits title: ScopeValues type: object CurrentValues: description: Live counts. properties: transcribe_concurrent: title: Transcribe Concurrent type: integer tts_concurrent: title: Tts Concurrent type: integer required: - transcribe_concurrent - tts_concurrent title: CurrentValues type: object LimitValues: description: Configured limits properties: transcribe_concurrent: anyOf: - type: integer - type: 'null' title: Transcribe Concurrent tts_concurrent: anyOf: - type: integer - type: 'null' title: Tts Concurrent required: - transcribe_concurrent - tts_concurrent title: LimitValues type: object GetConcurrentStreamsHistoryResponse: properties: kind: allOf: - $ref: '#/components/schemas/ConcurrentStreamKind' description: Stream kind these entries describe (`stt` or `tts`). entries: description: Per-period concurrent stream aggregates for the authenticated project, ordered by `period_start` ascending. Every aggregation period in the requested window is returned, with no gaps. Periods with no recorded activity have every field set to `0`. items: $ref: '#/components/schemas/ConcurrentStreamsHistoryEntry' title: Entries type: array required: - kind - entries title: GetConcurrentStreamsHistoryResponse type: object ConcurrentStreamsHistoryEntry: properties: period_start: description: Start of the aggregation period, UTC. Aligned to a multiple of `period_sec`. format: date-time title: Period Start type: string period_sec: description: Aggregation period in seconds. title: Period Sec type: integer sample_min: description: Lowest recorded concurrent stream count in the period. Always `0`, because that is what the per-minute tier records. Use `sample_max` for the peak. title: Sample Min type: integer sample_max: description: Peak concurrent stream count in the period. Stays exact when periods are rolled up into hours and days. `0` when the period had no activity. title: Sample Max type: integer sample_sum: description: Sum of the recorded concurrency values in the period. Divide by `sample_count` for the average concurrency while streams were active, or by `total_count` for the average across the whole period with idle slots counted as zero. title: Sample Sum type: integer sample_count: description: Number of values actually recorded in the period. For `period_sec=60` this is how many samples were taken during that minute, so it is usually larger than `total_count`. For hourly and daily periods it is the number of source periods that had data, at most `total_count`. `0` when the period had no activity. title: Sample Count type: integer total_count: description: Number of slots the period covers. `1` for `period_sec=60`, `60` for `3600` (minutes per hour), `24` for `86400` (hours per day). `0` when the period had no activity. title: Total Count type: integer required: - period_start - period_sec - sample_min - sample_max - sample_sum - sample_count - total_count title: ConcurrentStreamsHistoryEntry type: object ConcurrentStreamKind: enum: - stt - tts title: ConcurrentStreamKind type: string securitySchemes: PublicApiAuth: type: http scheme: bearer servers: - url: https://api.soniox.com description: Soniox API