[Yandex Cloud documentation](../../index.md) > [Tutorials](../index.md) > [Serverless technologies](index.md) > Integration with Yandex and Yandex Cloud services > Using API Gateway to set up speech synthesis in SpeechKit

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


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

In this tutorial, you will create a custom setup with an [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification)-based [API gateway](../../api-gateway/concepts/index.md) with [HTTP integration](../../api-gateway/concepts/extensions/http.md). 

Users’ speech synthesis requests run through the API gateway that uses HTTP integration to call the [SpeechKit API](https://aistudio.yandex.ru/docs/en/speechkit/concepts/api) and retrieve the synthesized speech from SpeechKit.

To set up SpeechKit speech synthesis using Yandex API Gateway:

1. [Get your cloud ready](#before-you-begin).
1. [Create a service account](#create-service-account).
1. [Create an API gateway](#create-gateway).
1. [Check the result](#check-out).

If you no longer need the resources you created, [delete them](#clear-out).


## Getting started {#before-you-begin}

Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md).


### Required paid resources {#paid-resources}

The new infrastructure support cost includes:

* Fee for the number of requests to the API gateway and outgoing traffic (see [Yandex API Gateway pricing](../../api-gateway/pricing.md)).
* Fee for using SpeechKit (see [SpeechKit pricing](https://aistudio.yandex.ru/docs/en/speechkit/pricing)).


## Create a service account {#create-service-account}

[Create](../../iam/operations/sa/create.md) a service account named `speechkit-sa` with the `ai.speechkit-tts.user` [role](https://aistudio.yandex.ru/docs/en/speechkit/security/index#ai-speechkit-tts-user) for the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) where you are creating your infrastructure:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a service account.
  1. Navigate to **Identity and Access Management**.
  1. Click **Create service account**.
  1. Name the service account: `speechkit-sa`.
  1. Click ![image](../../_assets/console-icons/plus.svg) **Add role** and select `ai.speechkit-tts.user`.
  1. Click **Create**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Create a service account named `speechkit-sa`:

      ```bash
      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 you created it (`folder_id`).

      For more information about the `yc iam service-account create` command, see the [CLI reference](../../cli/cli-ref/iam/cli-ref/service-account/create.md).

  1. 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:

      ```bash
      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](../../cli/cli-ref/resource-manager/cli-ref/folder/add-access-binding.md).

- API {#api}

  To create a service account, use the [create](../../iam/api-ref/ServiceAccount/create.md) method for the [ServiceAccount](../../iam/api-ref/ServiceAccount/index.md) resource or the [ServiceAccountService/Create](../../iam/api-ref/grpc/ServiceAccount/create.md) gRPC API call.

  To assign the `ai.speechkit-tts.user` role for a folder to a service account, use the [setAccessBindings](../../iam/api-ref/ServiceAccount/setAccessBindings.md) method for the [ServiceAccount](../../iam/api-ref/ServiceAccount/index.md) resource or the [ServiceAccountService/SetAccessBindings](../../iam/api-ref/grpc/ServiceAccount/setAccessBindings.md) gRPC API call.

{% endlist %}


## Create an API gateway {#create-gateway}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) where you want to create an API gateway.
  1. Navigate to **API Gateway**.
  1. Click **Create API gateway**.
  1. In the **Name** field, enter `speechkit-api-gw`.
  1. Under **Specification**, add the following specification and provide the `speechkit-sa` service account [ID](../../iam/operations/sa/get-id.md) in the `service_account_id` parameter:

      ```yaml
      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>"
      ```

  1. Click **Create**.
  1. Wait until the status of the API gateway you just created switches to `running`, and then click the row with the gateway name.
  1. In the window that opens, copy the **Default domain** field value. You will need it later to test the API gateway.

- CLI {#cli}

  1. Save the following specification to `speechkit-gw.yaml` and provide the `speechkit-sa` service account [ID](../../iam/operations/sa/get-id.md) in the `service_account_id` parameter:

      ```yaml
      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>"
      ```

  1. Run this command:

     ```bash
     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:

     ```text
     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` field value) of the API gateway you created. You will need it later to test the API gateway.

  For more information about the `yc serverless api-gateway create` command, see the [CLI reference](../../cli/cli-ref/serverless/cli-ref/api-gateway/create.md).

- API {#api}

  To create an API gateway, use the [create](../../api-gateway/apigateway/api-ref/ApiGateway/create.md) REST API method for the [ApiGateway](../../api-gateway/apigateway/api-ref/ApiGateway/index.md) resource or the [ApiGatewayService/Create](../../api-gateway/apigateway/api-ref/grpc/ApiGateway/create.md) gRPC API call.

{% endlist %}


## Check the result {#check-out}

{% note info %}

You will need [cURL](https://curl.haxx.se) and [jq](https://github.com/jqlang/jq) to test your API gateway.

{% endnote %}

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

```bash
curl --verbose \
  https://<service_domain>/synthesis \
  --data '{"text": "Hello! 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
```

After you run the above command, Yandex SpeechKit will save the synthesized speech to the `audio.mp3` file in the current directory. You can listen to the output file in your browser, e.g., [Yandex Browser](https://browser.yandex.ru) or [Mozilla Firefox](http://www.mozilla.org).

To learn more about the format of the text provided in the `-d` parameter, see [this Yandex SpeechKit guide](https://aistudio.yandex.ru/docs/en/speechkit/tts/request).


## How to delete the resources you created {#clear-out}

If you no longer need the resources you created:

* [Delete the API gateway](../../api-gateway/operations/api-gw-delete.md).
* [Delete the service account](../../iam/operations/sa/delete.md).