Update task configuration

Endpoint

• Method: PATCH

• Endpoint: https://api.agora.io/v1/projects/{appId}/rtsc/speech-to-text/tasks/{taskId}

Use this method to update the configuration of a Real-Time STT task.

Request

Path parameters

appId Type: string Required

The App ID of the project

taskId Type: string Required

The unique identifier of the Real-Time STT task you received in the response body of the start method.

Query parameters

builderToken Type: string Required

The tokenName value you obtained in the response body of the acquire method.

sequenceId Type: integer Required

The sequence number of update requests. The integer value must be greater than or equal to 0. Ensure that the sequenceId of the next update request is greater than the value you specified for the previous request. The parameter ensures that Agora updates the transcription task according to the latest configuration you specified.

updateMask Type: string Required

The specified update configuration item. To update multiple fields, use a comma separator. For example: updateMask=languages,rtcConfig.subscribeAudioUids,translateConfig.enable,translateConfig.languages.

Request body

APPLICATION/JSON

BODY

languages Type: array[string] Optional

The transcription languages to recognize. You can specify up to 4 languages. Refer to Supported Languages for details.

uidLanguagesConfig Type: object Optional

Configure the transcription language for the specified user ID. Supports up to 5 configuration items. uid Type: string Required

The ID of the user to be transcribed.

languages Type: string Required

You can specify up to 4 languages. Refer to Supported Languages for details.

rtcConfig Type: object Optional

subscribeAudioUids Type: array[string] Optional

The user IDs of the audio streams you want to subscribe to. Specify this parameter only if you need to subscribe to specific users. To subscribe to audio streams of all users, use ["all"]. Maximum array length: 32.

translateConfig Type: object Optional

Subtitle translation configuration enable Type: boolean Required

Whether to translate the transcribed text:

• true: Translate.
• false: Do not translate.
  If you enabled translation when calling start, you can turn it off by setting enable to false. If you did not enable translation, you can turn it on by setting enable to true and specifying languages.

languages Type: array Required

The translation languages array. You can specify a maximum of 2 different source languages. The source language and target language must be different, otherwise an error is reported.
Each array item is an object with: source Type: string Required

The source language for translation. Refer to Supported Languages for details.

target Type: array[string] Required

The target languages for translation. You can specify a maximum of 5 target languages for each source language. Refer to Supported Languages for details.

Response

• If the returned status code is 200, the request was successful. The response body contains the result of the request.

  OK

taskId Type: string Required

The unique identifier of this transcription task.

createTs Type: integer Required

The Unix timestamp (in seconds) when the transcription task was created.

status Type: string Required

The current status of the transcription task:

• IDLE: Task not initialized

• PREPARING: Task has received an initialization request

• PREPARED: Task initialization completed

• STARTING: Task is beginning to start

• CREATED: Task startup partially completed

• STARTED: Task startup fully completed

• IN_PROGRESS: Task is currently running

• STOPPING: Task is in the process of being paused

• STOPPED: Task has been terminated

• FAILURE_STOP: Task termination failed

• If the returned status code is not 200, the request failed. Refer to message field to understand the possible reasons for failure.

Non-200

message Type: string

The reason why the request failed.

Authorization

This endpoint requires Basic Auth.

Request example

      curl --request PATCH \
        --url 'https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks/:taskId?builderToken=your_builder_token&sequenceId=your_sequence_id&updateMask=your_update_mask' \
        --header 'Authorization: Basic <credentials>' \
        --header 'Content-Type: <string>' \
        --data '
      {
        "languages": [
          "en-US"
        ],
        "uidLanguagesConfig": [
          {
            "uid": "12345",
            "languages": [
              "en-US"
            ]
          }
        ],
        "rtcConfig": {
          "subscribeAudioUids": [
            "47091",
            "88222"
          ]
        },
        "translateConfig": {
          "enable": true,
          "languages": [
            {
              "source": "en-US",
              "target": [
                "es-ES",
                "ar-SA"
              ]
            }
          ]
        }
      }'

    import requests

    url = "https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks/:taskId?builderToken=your_builder_token&sequenceId=your_sequence_id&updateMask=your_update_mask"

    payload = {
        "languages": ["en-US"],
        "uidLanguagesConfig": [
            {
                "uid": "12345",
                "languages": ["en-US"]
            }
        ],
        "rtcConfig": { "subscribeAudioUids": ["47091", "88222"] },
        "translateConfig": {
            "enable": True,
            "languages": [
                {
                    "source": "en-US",
                    "target": ["es-ES", "ar-SA"]
                }
            ]
        }
    }
    headers = {
        "Authorization": "Basic <credentials>",
        "Content-Type": "<string>"
    }

    response = requests.request("PATCH", url, json=payload, headers=headers)

    print(response.text)

    const url = 'https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks/:taskId?builderToken=your_builder_token&sequenceId=your_sequence_id&updateMask=your_update_mask';
    const options = {
      method: 'PATCH',
      headers: {Authorization: 'Basic <credentials>', 'Content-Type': '<string>'},
      body: JSON.stringify({
        languages: ['en-US'],
        uidLanguagesConfig: [{uid: '12345', languages: ['en-US']}],
        rtcConfig: {subscribeAudioUids: ['47091', '88222']},
        translateConfig: {enable: true, languages: [{source: 'en-US', target: ['es-ES', 'ar-SA']}]}
      })
    };

    fetch(url, options)
      .then(res => res.json())
      .then(json => console.log(json))
      .catch(err => console.error(err));

Response example

200

    {
      "taskId": "XXXX",
      "createTs": 1678505852,
      "status": "IN_PROGRESS"
    }

Non-200

    {
      "message": "The reason why the request failed.",
    }