Skip to main content

Update service

Real-Time STT supports the update command, which allows modification of parameters without stopping and restarting the service. For example, when transcription is enabled for a specified host only, and this host disconnects and rejoins the channel with a different UID, the Real-Time STT service needs to subscribe to the new UID and transcribe their audio. The update command can help resolve this problem.

The update command scope includes the following:

  • Update transcription languages.
  • Update UIDs of specified hosts whose audio needs to be transcribed.
  • Switch between transcribing all hosts and a specified host.

Prerequisites

To follow this procedure, you must:

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

Implementation

Follow the API call sequence from the REST Quickstart.

Request examples

  • Update the transcription language:


    _7
    curl --location -g --request PATCH 'https://api.agora.io/v1/projects/{{appId}}/rtsc/speech-to-text/tasks/{{taskId}}?builderToken={{tokenName}}&sequenceId=1&updateMask=languages' \
    _7
    --header 'Content-Type: application/json'
    _7
    --data '{
    _7
    "languages": [
    _7
    "<YourTranscribeLanguages>" // Max can configure 2 languages. e.g. "en-US", "ru-RU". If set 2 languages, STT service will automaticly enable Language Detection feature it will cause addtional cost.
    _7
    ],
    _7
    }'

  • Update the UID


    _7
    curl --location -g --request PATCH 'https://api.agora.io/v1/projects/{{appId}}/rtsc/speech-to-text/tasks/{{taskId}}?builderToken={{tokenName}}&sequenceId=1&updateMask=rtcConfig.subscribeAudioUids' \
    _7
    --header 'Content-Type: application/json'
    _7
    --data '{
    _7
    "rtcConfig": {
    _7
    "subscribeAudioUids": "[uint]}", // ["all"] or ["uid1", "uid2", "uid3"], "all" means service channel.
    _7
    },
    _7
    }'

Response examples

  • Success


    _5
    {
    _5
    "taskId": "String", // taskId
    _5
    "createTs": number, // create ts
    _5
    "status": enum(STATUS) // task status: IDLE, PREPARING, IN_PROGRESS, STOPPING, STOPPED
    _5
    }

  • Failure


    _3
    {
    _3
    "message": string // error reason
    _3
    }

Notice

  • Calling update requires at least 5-second intervals, specifically:
    • After calling start, the app needs to wait at least 5 seconds to call the update command.
    • After calling update, the app needs to wait at least 5 seconds before calling update again.
    • There is no interval limitation for calling update with query and stop commands.
  • When updated, the new parameter fully replaces the old parameter, unless the old parameter is masked with updateMask. For example, say the audio of hosts with UID 100 and 200 is being transcribed. The host with the UID 200 disconnects and rejoins with the new UID 300. The update command needs to use "subscribeAudioUids": "[ "100", "300" ]. If it uses only "subscribeAudioUids": "[ "300" ], then only the UID 300 host's audio will be transcribed. The languages configuration will not be updated.
  • If languages and host UIDs are updated together, pass in "updateMask=languages,rtcConfig.subscribeAudioUids".
  • sequenceId should increase by 1 for each request.
vundefined