Contact UsGet started

Using Yandex API Gateway to set up speech synthesis in Yandex SpeechKit

Written by
Updated at May 7, 2025

Using serverless technology, you can create your own integration with Yandex Cloud services.

This guide will show you how to create a custom setup with an OpenAPI 3.0-based API gateway with HTTP integration.

The users’ speech synthesis requests run through the API gateway that calls SpeechKit API through HTTP integration and retrieves the synthesized speech from SpeechKit.

To set up SpeechKit speech synthesis using Yandex API Gateway:

  1. Prepare your cloud environment.
  2. Create a service account.
  3. Create an API gateway.
  4. Check the result.

If you no longer need the resources you created, delete them.

Getting started

Sign up in Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or register a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

The cost of support for the new infrastructure includes:

Create a service account

Create a service account with the speechkit-sa role for the folder where you create your infrastructure:

  1. In the management console, select the folder where you want to create a service account.
  2. In the services list, select Identity and Access Management.
  3. Click Create service account.
  4. Enter a name for the service account: speechkit-sa.
  5. Click Add role and select the ai.speechkit-tts.user role.
  6. Click Create.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. Create a service account named speechkit-sa:

    yc iam service-account create speechkit-sa

    Result:

    id: nfersamh4sjq********
folder_id: b1gc1t4cb638********
created_at: "2023-09-21T10:36:29.726397755Z"
name: speechkit-sa

    Save the ID of the speechkit-sa service account (id) and the ID of the folder where it was created (folder_id).

    For more information about the yc iam service-account create command, see the CLI reference.

  2. Assign the ai.speechkit-tts.user role for the folder to the service account by specifying the folder and service account IDs you previously saved:

    yc resource-manager folder add-access-binding <folder_ID> \
  --role ai.speechkit-tts.user \
  --subject serviceAccount:<service_account_ID>

    For more information about the yc resource-manager folder add-access-binding command, see the CLI reference.

To create a service account, use the create method for the ServiceAccount resource or the ServiceAccountService/Create gRPC API call.

To assign the ai.speechkit-tts.user role for the folder to the service account, use the setAccessBindings method for the ServiceAccount resource or the ServiceAccountService/SetAccessBindings gRPC API call.

Create an API gateway

  1. In the management console, select the folder where you want to create an API gateway.

  2. In the services list, select API Gateway.

  3. Click Create API gateway.

  4. In the Name field, enter speechkit-api-gw.

  5. In the Specification section, add the following specification and provide the speechkit-sa service account ID in the service_account_id parameter:

    openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /synthesis:
    post:
      requestBody:
        description: "/synthesis"
        content:
          application/json:
            schema:
              type: object
              x-yc-schema-mapping:
                type: static
                template:
                  text: "${.text}"
                  hints:
                    - voice: "lera"
                    - role: "friendly"
                    - audioTemplate:
                        audio:
                          audioSpec:
                            containerAudio:
                              containerAudioType: "MP3"
      responses:
        200:
          description: "/synthesis"
          content:
            application/json:
              schema:
                type: object
                x-yc-schema-mapping:
                  type: static
                  template:
                    data: "${.result.audioChunk.data}"
      x-yc-apigateway-integration:
        http_method: post
        type: http
        url: https://tts.api.cloud.yandex.net/tts/v3/utteranceSynthesis
        service_account_id: "<service_account_ID>"

  6. Click Create.

  7. Wait until the status of the API gateway you just created switches to running, and then click the row with the gateway name.

  8. In the window that opens, copy the Default domain field value. You will need it later to check how the API gateway works.

  1. Save the following specification to the speechkit-gw.yaml file and provide the speechkit-sa service account ID in the service_account_id parameter:

    openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /synthesis:
    post:
      requestBody:
        description: "/synthesis"
        content:
          application/json:
            schema:
              type: object
              x-yc-schema-mapping:
                type: static
                template:
                  text: "${.text}"
                  hints:
                    - voice: "lera"
                    - role: "friendly"
                    - audioTemplate:
                        audio:
                          audioSpec:
                            containerAudio:
                              containerAudioType: "MP3"
      responses:
        200:
          description: "/synthesis"
          content:
            application/json:
              schema:
                type: object
                x-yc-schema-mapping:
                  type: static
                  template:
                    data: "${.result.audioChunk.data}"
      x-yc-apigateway-integration:
        http_method: post
        type: http
        url: https://tts.api.cloud.yandex.net/tts/v3/utteranceSynthesis
        service_account_id: "<service_account_ID>"

  2. Run the following command:

    yc serverless api-gateway create \
  --name speechkit-api-gw \
  --spec=speechkit-gw.yaml

    Where:

    • --name: API gateway name.
    • --spec: Path to the specification file.

    Result:

    done (2s)
id: d5ddbmungf72********
folder_id: b1gt6g8ht345********
created_at: "2024-08-19T18:58:32.101Z"
name: speechkit-api-gw
status: ACTIVE
domain: d5dm1lba80md********.i9******.apigw.yandexcloud.net
connectivity: {}
log_options:
  folder_id: b1gt6g8ht345********
execution_timeout: 300s

Save the service domain (the domain filed value) of the API gateway you created. You will need it later to check how the API gateway works.

For more information about the yc serverless api-gateway create command, see the CLI reference.

To create an API gateway, use the create REST API method for the ApiGateway resource or the ApiGatewayService/Create gRPC API call.

Check the result

Note

To check whether your API gateway works properly, you will need cURL and jq.

Send a request to your API gateway by providing the service domain value you previously saved:

curl --verbose \
  https://<service_domain>/synthesis \
  --data '{"text": "Hi! S+erverless Api G+ateway now has a new feature: converting HTTP request or response body!"}' \
  | jq -r  '.data' | while read chunk; do base64 -d <<< "$chunk" >> audio.mp3; done

Once you run the above command, the synthesized speech will be saved to the audio.mp3 file in the current directory. You can listen to the output file in your browser, e.g., Yandex Browser or Mozilla Firefox.

To learn more about the format of the text provided in the -d parameter, see the Yandex SpeechKit documentation.

How to delete the resources you created

If you no longer need the resources you created:

Previous
Streaming Yandex Cloud Postbox events to Data Streams and analyzing them using DataLens
Next
Connecting to YDB from a Cloud Functions function in Python