Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace

    Update task configuration

    Update task configuration

    PATCH
    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 stringrequired

    The App ID of the project

    taskId stringrequired

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

    Query parameters​

    builderToken stringrequired

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

    sequenceId integerrequired

    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 stringrequired

    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
    BODYrequired
    • languages array[string]nullable

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

    • uidLanguagesConfig objectnullable

      Configure the transcription language for the specified user ID. Supports up to 5 configuration items.

        • uid stringrequired

          The ID of the user to be transcribed.

        • languages stringrequired

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

    • rtcConfig objectnullable
        • subscribeAudioUids array[string]nullable

          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 objectnullable

      Subtitle translation configuration

        • enable booleanrequired

          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 arrayrequired

          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 stringrequired

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

            • target 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 stringrequired

        The unique identifier of this transcription task.

      • createTs integerrequired

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

      • status stringrequired

        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 string

        The reason why the request failed.

    Authorization

    This endpoint requires Basic Auth.

    Request example


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

    Response example


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

    vundefined