Best practice in enabling Real-Time STT on the client side

Real-Time STT is designed to provide service for channels. The recommended solution is to call RESTful APIs on the server side. But in a real-world scenario, the service is always enabled on the end user's side. This requires the user's app to notify the app's server, and the server to call RESTful APIs.

If the end user's app calls RESTful APIs, the app needs to store the customer ID and customer secret to generate a Base64-encoded credential and fill it in the HTTP header (as explained in Authenticate REST calls. Since it is not safe to store the customer ID and secret in the app, Agora provides a new method for HTTP authentication without storing customer ID and secret.

This page explains how to enable Real-Time STT on the client's side. For more information, see Authenticate REST calls.

To follow this procedure, you must:

• Have a valid Agora Account.

• Have a valid Agora project with an app ID and a temporary token or a token server. For details, see Agora account management.

• Have a computer with access to the internet. If your network has a firewall, follow the steps in Firewall requirements.

• Join a Video SDK channel as a host and start streaming. Refer to the Voice SDK quickstart guide.

• Make sure Real-Time STT is enabled for your app.

To let an end user's app call RESTful API with lower security risks, substitute the original Base64-encoded credential (generated from the customer ID and secret) with an RTC token (AccessToken2).

Take the following steps:

1. Refer to Secure authentication with tokens to generate an RTC token. An AccessToken2 will be required. For example, "007eJxTYLj64d/9y/N6FnXGZ4nWvZ9TcL7O2u7XrrCdnPe4p1QIbZ2pwGCaZGppkmxsZGaWZmRibmlkmWRiZmBikGpsZGBkaJyY9KCqIFWAj4FBI/gaMyMDEwMjEIL4PAwlqcUl8aXFqUXxmSkAuBgi6g=="

2. Use this token to replace the value of "Authorization" in HTTP headers: "Authorization: agora token="007eJxTYLj64d/9y/N6FnXGZ4nWvZ9TcL7O2u7XrrCdnPe4p1QIbZ2pwGCaZGppkmxsZGaWZmRibmlkmWRiZmBikGpsZGBkaJyY9KCqIFWAj4FBI/gaMyMDEwMjEIL4PAwlqcUl8aXFqUXxmSkAuBgi6g==".

3. Use this header to call RESTful APIs.

Examples

• curl

  
  

  _6

  curl --location --request POST 'https://api.agora.io/v1/projects/YOUR_APP_ID/rtsc/speech-to-text/builderTokens' \

  _6

  --header 'Content-Type: Application/json' \

  _6

  --header 'Authorization: agora token="007eJxTYLj64d/9y/N6FnXGZ4nWvZ9TcL7O2u7XrrCdnPe4p1QIbZ2pwGCaZGppkmxsZGaWZmRibmlkmWRiZmBikGpsZGBkaJyY9KCqIFWAj4FBI/gaMyMDEwMjEIL4PAwlqcUl8aXFqUXxmSkAuBgi6g=="' \

  _6

  --data-raw '{

  _6

  "instanceId" : "YOUR_INSTANCE_ID"

  _6

  }'

  
  

• Valid token:

  • Response status: 200 OK

  • Response body:

    
    

    _5

    {

    _5

    "createTs": 1718791667,

    _5

    "instanceId": "YOUR_STT_INSTANCE_ID",

    _5

    "tokenName": "YOUR_STT_TOKEN"

    _5

    }

    
    

• Expired token:

  • Response status: 401 Unauthorized

  • Response body:

    • Token was valid but expired at the time of request:
    
    

    _1

    {"message": "Token is expired"}

    
    
    • Token was not properly generated:
    
    

    _1

    {"message": "Invalid token"}

    
    

Multiple clients may enable Real-Time STT simultaneously (within 1s), creating 2 or more transcription tasks. This will generate twice or more usage. To avoid this, take the following precautions:

• Add a lock in the apps.
• Prevent calling RESTful API from the same app more frequently than every second.