### Get Access Token using Python Source: https://developers.sber.ru/docs/ru/salutespeech/api/authentication This Python script demonstrates how to obtain an access token for the SaluteSpeech API using the requests library. Replace '' with your key and ensure 'RqUID' is unique. ```python import requests url = "https://ngw.devices.sberbank.ru:9443/api/v2/oauth" payload={ 'scope': 'SALUTE_SPEECH_PERS' } headers = { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json', 'RqUID': '9995ee0a-981c-41e1-8a99-efd7cad58cdd', 'Authorization': 'Basic ' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` -------------------------------- ### GET /rest/v1 Source: https://developers.sber.ru/docs/ru/salutespeech/rest/get-data-download Получение результата асинхронной задачи синтеза или распознавания речи. ```APIDOC ## GET /rest/v1 ### Description Возвращает результат выполнения задачи на асинхронный синтез или распознавание речи. Возвращает бинарное содержимое файла для синтеза или JSON-файл для распознавания. ### Method GET ### Endpoint https://smartspeech.sber.ru/rest/v1 ### Parameters #### Query Parameters - **response_file_id** (string) - Required - Идентификатор загруженного файла ### Response #### Success Response (200) - **application/octet-stream** (binary) - Содержимое файла в двоичном формате (синтез). - **application/json** (object) - Текстовый файл (распознавание). #### Error Responses - **400** - Некорректный формат запроса. - **401** - Ошибка авторизации. - **413** - Превышен максимальный размер входных данных. - **500** - Внутренняя ошибка сервиса. ``` -------------------------------- ### GET /rest/v1 Source: https://developers.sber.ru/docs/ru/salutespeech/rest/get-async-task Получение статуса асинхронной задачи по её идентификатору. ```APIDOC ## GET /rest/v1 ### Description Возвращает статус задачи. Используется для синтеза и распознавания речи в асинхронном режиме. ### Method GET ### Endpoint https://smartspeech.sber.ru/rest/v1 ### Parameters #### Query Parameters - **id** (string) - Required - Идентификатор созданной задачи ### Response #### Success Response (200) - **status** (string) - Статус задачи. Статус DONE означает завершение обработки задачи. (Enum: NEW, RUNNING, CANCELED, DONE, ERROR) #### Response Example { "status": "NEW" } ``` -------------------------------- ### SSML Example for Speech Synthesis Source: https://developers.sber.ru/docs/ru/salutespeech/guides/synthesis/ssml Use this SSML structure in the request body when the Content-Type is application/ssml. Ensure all tags are closed, attributes are in double quotes, and special characters like '&' are escaped. ```xml Привет! Как прошел день? Все хорошо? ``` -------------------------------- ### Get Access Token using cURL Source: https://developers.sber.ru/docs/ru/salutespeech/api/authentication Use this cURL command to request an access token for the SaluteSpeech API. Ensure you replace '' with your actual key and that 'RqUID' is unique for each request. ```sh curl -L -X POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Accept: application/json' \ -H 'RqUID: 4fadbe99-84bf-4bae-8bc3-71bad17dfae5' \ -H 'Authorization: Basic ' \ --data-urlencode 'scope= SALUTE_SPEECH_PERS' ``` -------------------------------- ### POST /recognize/async Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-async-speech-recognition Submits an audio file for asynchronous speech recognition and returns a task ID. ```APIDOC ## POST /recognize/async ### Description Returns the ID of the created speech recognition task. The request must include the ID of the uploaded file and recognition parameters. ### Method POST ### Endpoint /recognize/async ### Parameters #### Header Parameters - **X-Request-ID** (string) - Optional - A unique request ID used for searching the request in logs. If not specified, the server will generate one automatically. #### Request Body - **request_file_id** (string) - Required - The ID of the uploaded file. - **options** (object) - Required - Recognition parameters. - **audio_encoding** (string) - Required - The audio codec. Enum: [PCM_S16LE, OPUS, MP3, FLAC, ALAW, MULAW]. - **model** (string) - Optional - The name of the speech recognition model. Enum: [general, callcenter]. Default: "general". - **sample_rate** (integer) - Optional - The sample rate. Example: 16000. - **language** (string) - Optional - The language for speech recognition. Enum: [ru-RU, en-US, kk-KZ, ky-KG, uz-UZ]. Default: "ru-RU". - **enable_profanity_filter** (boolean) - Optional - Profanity filter. Default: false. - **hypotheses_count** (integer) - Optional - The number of alternative hypotheses to report for the recognized speech. Minimum: 0, Maximum: 10. Default: 1. - **no_speech_timeout** (number) - Optional - User speech waiting interval. Minimum: 2, Maximum: 20. Default: 7. - **max_speech_timeout** (number) - Optional - Defines the maximum utterance length before forced EOU. Minimum: 0.5, Maximum: 20. Default: 20. - **hints** (object) - Optional - Hints for recognition. - **words** (array) - Optional - A list of words or phrases to enhance recognition for. Example: ["карту", "гуакамоле"]. - **enable_letters** (boolean) - Optional - A model for short phrases that improves recognition of individual letters and short words. Default: false. - **eou_timeout** (number) - Optional - End of Utterance (EOU) recognition setting. The system waits for the specified number of seconds after a pause to determine the end of an utterance. Minimum: 0.5, Maximum: 5. Default: 1. - **channels_count** (integer) - Optional - The number of channels in multichannel audio. Minimum: 1, Maximum: 10. Default: 1. - **speaker_separation_options** (object) - Optional - Speaker separation parameters. - **enable** (boolean) - Optional - Enables speaker separation. Default: false. - **enable_only_main_speaker** (boolean) - Optional - Returns only the main speaker. Default: false. - **count** (integer) - Required - Maximum number of speakers. Minimum: 1, Maximum: 10. - **insight_models** (array) - Optional - Customer satisfaction evaluation using Insights models. Possible values: ["csi", "call_features", "is_solved", "csi, call_features, is_solved"]. ### Request Example ```json { "request_file_id": "2b325f72-1fa2-498c-aa2f-f7f3e88882dc", "options": { "audio_encoding": "PCM_S16LE", "sample_rate": 16000, "language": "ru-RU", "enable_profanity_filter": true, "hypotheses_count": 1, "no_speech_timeout": 7, "max_speech_timeout": 20, "hints": { "words": ["карту", "гуакамоле"], "enable_letters": false, "eou_timeout": 1 }, "channels_count": 1, "speaker_separation_options": { "enable": false, "enable_only_main_speaker": false, "count": 1 }, "insight_models": ["csi", "call_features"] } } ``` ### Response #### Success Response (200) - **task_id** (string) - The ID of the created recognition task. #### Response Example ```json { "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` ``` -------------------------------- ### POST /async-recognition Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-async-speech-recognition Initiates an asynchronous speech recognition task and returns the task ID and initial status. ```APIDOC ## POST /async-recognition ### Description Возвращает идентификатор созданной задачи на распознавание. ### Method POST ### Endpoint /async-recognition ### Response #### Success Response (200) - **status** (integer) - HTTP-код ответа. - **result** (object) - Результат создания задачи - **id** (string) - Идентификатор задачи - **created_at** (string) - Дата создания задачи - **updated_at** (string) - Дата обновления статуса задачи - **status** (string) - Статус задачи (NEW, RUNNING, CANCELED, DONE, ERROR) #### Response Example { "status": 200, "result": { "id": "5f5c6e6eed15b23b357852d52d3c979f", "created_at": "2017-10-10T10:00:00.000+03:00", "updated_at": "2021-01-01T00:00:00.000+03:00", "status": "NEW" } } ``` -------------------------------- ### SaluteSpeech API Access Token Response Source: https://developers.sber.ru/docs/ru/salutespeech/api/authentication This is an example of a successful JSON response when requesting an access token from the SaluteSpeech API. It includes the 'access_token' and its expiration time 'expires_at'. ```json { "access_token": "eyJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.DCXAAnwXjmRleOrIJcXDWbQwsP5UGSptcY3x5XXRkYZm6x3QkDQBL63DKQZzwrwmtuFbKajq6ULHuQhsmGax-l_R6AhRkr7pWzJi1jpzCenq9PAN2UjF0BX_IiDRgmEExH6_2OtHaJ_7KbudukIOLEgxD9l8WcXFY992dgqLL6eK2nnnUvyfmr4ITc9PWuAFsMIO6jweNFw0e9vRYEDkAbnv9EGR-w9CGwfBsHNWZwZlo7fyu07fkSfmqmGdBvU4344344luNNrHwktSGOzNhpLhu0-0A3KI950vmp_37QY8isDi3epGU3HShdrBZkk70fdXxBKQA.MV2IksoyxTV_c-qm6hSXaQ.LUT4JqOzKqmFOR07-Asq7Fhqj_eYSTXcsJAK-JchmM1QUqhPLBXsUyXXh6ZcjsnN7Q0QXzuBlSjaBWekgWANDirI6HP_MsEM4FxfJAOh73aowC700cEQPPYAxzPYG0d4bOqsZh8Ss57lJB2VM7M6Y2FcG2hb5Q0i2zPskqSWxXejuCyr2uIlY7Fe4bu4NUqtCaKJVwqriVWLfbA0OzZyA0osDc42Ba0u1adFAdaZDCE.IlKOixP8hSUimEI2pdP118Tx0StZjcLdbSauE5R0YAA", "expires_at": 1617814516729 } ``` -------------------------------- ### Authentication Overview Source: https://developers.sber.ru/docs/ru/salutespeech/rest/salutespeech-rest-api Details on how to authenticate with the SaluteSpeech REST API using Basic and Bearer schemes. ```APIDOC ## Authentication ### Description The SaluteSpeech REST API uses two types of authentication: Basic Auth for obtaining access tokens and Bearer Auth (JWT) for authenticated API calls. ### Security Schemes - **HTTP Basic Auth**: Used for the token retrieval endpoint. Requires a base64 encoded string of `Client ID` and `Client Secret` passed in the `Authorization` header. - **HTTP Bearer Auth**: Used for all other API requests. Requires a JWT token passed in the `Authorization` header. ### Usage 1. Use Basic Auth to request an access token from the token endpoint. 2. Use the returned JWT token in the `Authorization: Bearer ` header for all subsequent requests. ``` -------------------------------- ### Get Task Status Source: https://developers.sber.ru/docs/ru/salutespeech/api/grpc/synthesis-async-grpc Retrieves the status of a previously created synthesis task. It returns task details, including completion status and result file ID or error information. ```APIDOC ## Get Task Status ### Description Retrieves the status of a speech synthesis task. ### Method `GetTask` (gRPC) ### Endpoint `smartspeech.sber.ru` ### Parameters #### Query Parameters - **task_id** (string) - Required - The unique identifier of the task. ### Response #### Success Response (200) - **Task** (object) - An object containing task details: - **status** (string) - The current status of the task (e.g., `NEW`, `DONE`, `ERROR`). - **response_file_id** (string) - The ID of the synthesized audio file if the status is `DONE`. - **error** (string) - Description of the error if the status is `ERROR`. ``` -------------------------------- ### POST /rest/v1 Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-speech-synthesis Synthesizes speech from provided text or SSML and returns the binary audio data. ```APIDOC ## POST https://smartspeech.sber.ru/rest/v1 ### Description Возвращает бинарное представление синтезированного звука в запрошенном формате. ### Method POST ### Endpoint https://smartspeech.sber.ru/rest/v1 ### Parameters #### Header Parameters - **X-Request-ID** (string) - Optional - Уникальный ID запроса, который используется для поиска запроса в логах. #### Query Parameters - **format** (string) - Optional - Формат синтезируемого аудио (wav16, pcm16, opus, alaw, g729). Default: wav16. - **voice** (string) - Optional - Код голоса. Default: May_24000. - **rebuild_cache** (boolean) - Optional - Пересоздать кэш. Default: false. - **bypass_cache** (boolean) - Optional - Запрет использования кэша. Default: false. #### Request Body - **content** (string) - Required - Текст для синтеза в формате UTF-8 или SSML-разметка (application/text или application/ssml). ### Request Example { "content": "Привет из 1984!" } ### Response #### Success Response (200) - **binary** (binary) - Содержимое файла в двоичном формате. #### Response Example [Binary Audio Data] ``` -------------------------------- ### POST /websites/developers_sber_ru_ru_salutespeech Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-speech-recognition Submits an audio file for speech recognition and returns the processed results. The API supports various audio formats and has limitations on file size and duration. ```APIDOC ## POST /websites/developers_sber_ru_ru_salutespeech ### Description Returns the speech recognition result after processing the entire audio recording. The maximum audio size is 2 MB, and the maximum duration is one minute. For multichannel audio, only the first channel is recognized. ### Method POST ### Endpoint /websites/developers_sber_ru_ru_salutespeech ### Parameters #### Query Parameters - **language** (string) - Optional - Language for speech recognition. Languages `kk-KZ`, `ky-KG`, `uz-UZ` are available by special request. Available languages: `ru-RU` (Russian), `en-US` (English), `kk-KZ` (Kazakh), `ky-KG` (Kyrgyz), `uz-UZ` (Uzbek). Default: `ru-RU` - **enable_profanity_filter** (boolean) - Optional - Enable/disable profanity filter. Default: `true` - **model** (string) - Optional - Name of the model for speech recognition. Format: ascii string. Available models: `general`, `callcenter`, `media`, `ivr`. Default: `general` - **sample_rate** (integer) - Optional - Sampling rate. Maximum possible value is up to 96,000 Hz. - **channels_count** (integer) - Optional - Number of channels in multichannel audio. #### Header Parameters - **X-Request-ID** (string) - Optional - Unique request ID used for searching the request in logs. If not specified, the server will generate it automatically. ### Request Body - **BinaryFileDesc** (binary) - Required - The content of the file in binary format. Supported content types: `audio/mpeg`, `audio/flac`, `audio/ogg;codecs=opus`, `audio/x-pcm;bit=16;rate=8000`, `audio/x-pcm;bit=16;rate=16000`, `audio/pcma;rate=8000`, `audio/pcma;rate=16000`, `audio/pcmu;rate=8000`, `audio/pcmu;rate=16000` ### Response #### Success Response (200) - **result** (string) - The recognized text. - **audio_duration** (number) - The duration of the audio in seconds. - **processing_time** (number) - The time taken for processing in seconds. #### Response Example ```json { "result": "This is a test transcription.", "audio_duration": 5.23, "processing_time": 1.15 } ``` ``` -------------------------------- ### POST /rest/v1/async_speech_recognition Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-async-speech-recognition Initiates an asynchronous speech recognition task. ```APIDOC ## POST /rest/v1/async_speech_recognition ### Description Initiates an asynchronous speech recognition task. This endpoint allows you to submit audio data for processing and receive a task ID to track the recognition status. ### Method POST ### Endpoint https://smartspeech.sber.ru/rest/v1/async_speech_recognition ### Parameters #### Query Parameters - **token** (string) - Required - API token for authentication. - **uuid** (string) - Required - Unique identifier for the request. #### Request Body - **audio** (file) - Required - The audio file to be recognized. - **config** (string) - Optional - JSON string containing recognition configuration parameters. - **model** (string) - Optional - Specifies the recognition model to use (e.g., "general", "medical"). - **language** (string) - Optional - The language of the audio (e.g., "ru-RU", "en-US"). - **sample_rate** (integer) - Optional - The sample rate of the audio in Hz. - **encoding** (string) - Optional - The encoding of the audio (e.g., "LINEAR16", "FLAC"). - **channels** (integer) - Optional - The number of audio channels. ### Request Example ```json { "audio": "@/path/to/your/audio.wav", "config": "{\"model\": \"general\", \"language\": \"ru-RU\"}" } ``` ### Response #### Success Response (200) - **task_id** (string) - The unique identifier for the submitted recognition task. #### Response Example ```json { "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` #### Error Handling - **400 Bad Request**: Invalid request parameters or missing required fields. - **401 Unauthorized**: Invalid or missing API token. - **500 Internal Server Error**: An error occurred on the server. ``` -------------------------------- ### SaluteSpeech API - Asynchronous Synthesis Workflow Source: https://developers.sber.ru/docs/ru/salutespeech/api/grpc/synthesis-async-grpc This section details the asynchronous speech synthesis process using the SaluteSpeech API. It outlines the sequence of operations required to synthesize speech from text. ```APIDOC ## SaluteSpeech API - Asynchronous Synthesis Workflow This API allows for asynchronous speech synthesis. The process involves several steps: 1. **Client Application Creation**: Set up a client application using gRPC libraries. 2. **File Upload**: Upload the text file for synthesis using the `Upload` method. 3. **Task Creation**: Create an asynchronous synthesis task with `AsyncSynthesize`, providing the uploaded file ID and synthesis parameters. 4. **Status Check**: Monitor the task status using the `GetTask` method. 5. **Result Download**: Download the synthesized audio once the task is complete using the `Download` method. **API Endpoint**: `smartspeech.sber.ru` **Request/Response Headers**: Common headers apply to all steps. Refer to `` and `` for details. ``` -------------------------------- ### POST /api/v2 - Obtain Access Token Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-token Obtains an access token for authorizing requests to the SaluteSpeech API. The token is valid for 30 minutes. ```APIDOC ## POST /api/v2 - Obtain Access Token ### Description Returns an access token for authorizing requests to the API. The access token is valid for 30 minutes. To obtain a token, pass the access key in Bearer Token format in the `Authorization` header. The token value is obtained by base64 encoding the Client ID and Client Secret of the API. Use the obtained token to authorize requests for speech synthesis and recognition (synchronous or asynchronous). ### Method POST ### Endpoint https://ngw.devices.sberbank.ru:9443/api/v2 ### Parameters #### Header Parameters - **RqUID** (string) - Required - Unique request identifier. Corresponds to the [`uuid4`](https://www.uuidgenerator.net/version4) format. Parameter for logging incoming calls and incident analysis. Standard libraries and classes for generating UUID and GUID can be used to create a unique identifier. Example: `6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e`. - **Authorization** (string) - Required - Access key. #### Request Body - **scope** (string) - Required - API version. Possible values: * `SALUTE_SPEECH_PERS` — access for individuals. * `SALUTE_SPEECH_CORP` — access for legal entities. * `SBER_SPEECH` — deprecated value for legal entities. ### Request Example ```json { "scope": "SALUTE_SPEECH_PERS" } ``` ### Response #### Success Response (200) - **access_token** (string) - Token for authorizing requests. - **expires_at** (integer) - Token expiration date and time in Unix time format. #### Response Example ```json { "access_token": "eyJhbGci3iJkaXIiLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIn0..Dx7iF7cCxL8SSTKx.Uu9bPK3tPe_crdhOJqU3fmgJo_Ffvt4UsbTG6Nn0CHghuZgA4mD9qiUiSVC--okoGFkjO77W.vjYrk3T7vGM6SoxytPkDJw", "expires_at": 1679471442 } ``` #### Error Response (401) - **description**: Authorization error. ``` -------------------------------- ### POST /rest/v1 - Create Speech Synthesis Task Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-async-speech-synthesis Creates a speech synthesis task and returns its identifier. Requires the ID of a previously uploaded file and synthesis parameters. ```APIDOC ## POST /rest/v1 ### Description Creates a speech synthesis task and returns its identifier. Requires the ID of a previously uploaded file and synthesis parameters. ### Method POST ### Endpoint https://smartspeech.sber.ru/rest/v1 ### Parameters #### Header Parameters - **X-Request-ID** (string) - Optional - Unique request ID for log searching. If not provided, the server will generate one. #### Request Body - **request_file_id** (string) - Required - Identifier of the uploaded file. - **audio_encoding** (string) - Required - Audio codec. Only `opus` is supported. - **voice** (string) - Required - Voice code for synthesis. See 'Voice Examples' for possible values. ### Request Example ```json { "request_file_id": "uuid", "audio_encoding": "opus", "voice": "Ost_24000" } ``` ### Response #### Success Response (200) - **status** (integer) - HTTP response code. - **result** (object) - Result of task creation. - **id** (string) - Task identifier. - **created_at** (string) - Date of task creation. - **updated_at** (string) - Date of task status update. - **status** (string) - Task status (NEW, RUNNING, CANCELED, DONE, ERROR). #### Response Example ```json { "status": 200, "result": { "id": "5f5c6e6eed15b23b357852d52d3c979f", "created_at": "2017-10-10T10:00:00.000+03:00", "updated_at": "2021-01-01T00:00:00.000+03:00", "status": "NEW" } } ``` #### Error Responses - **400** - Bad request format. - **401** - Authorization error. - **413** - Input data size exceeded. - **500** - Internal server error. ``` -------------------------------- ### POST /rest/v1 Source: https://developers.sber.ru/docs/ru/salutespeech/rest/post-speech-recognition Endpoint for performing speech recognition on provided audio files. ```APIDOC ## POST /rest/v1 ### Description This endpoint is used to recognize speech from an audio file. ### Method POST ### Endpoint https://smartspeech.sber.ru/rest/v1 ``` -------------------------------- ### Использование шаблона в SSML Source: https://developers.sber.ru/docs/ru/salutespeech/guides/synthesis/ssml/audio-templates SSML-запрос для использования созданного шаблона с указанием ID и значений переменных. Шаблон может быть использован как самостоятельный элемент или в сочетании с другим текстом. ```xml