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

    Update task configuration

    Update task configuration

    POST
    https://api.agora.io/api/speech-to-text/v1/projects/{appid}/agents/{agentId}/update

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

    Request​

    Path parameters​

    appId stringrequired

    The App ID of the project

    agentId stringrequired

    The unique identifier of the agent you received in the response body of the join method.

    Query parameters​

    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 arraynullable

      Configure the transcription language for the specified user ID. Supports up to 5 configuration items. If you set this field when calling join and now wish to specify no users, set this field to an empty array [].

        • uid stringrequired

          The ID of the user to be transcribed.

        • languages array[string]required

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

    • rtcConfig objectnullable

      Subscription configuration.

        • 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 booleannullable

          Whether to translate the transcribed text:

          • true: Translate.
          • false: Do not translate.
            If you enabled translation when calling join, 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 arraynullable

          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 10 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
      • agent_id string

        The ID of the agent.

      • create_ts integer

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

      • status string

        The current status of the agent:

        • IDLE: The agent is not initialized
        • STARTING: The agent is starting
        • RUNNING: The agent is running
        • STOPPING: The agent is exiting
        • STOPPED: The agent exited successfully
        • RECOVERING: The agent is recovering
        • FAILED: Agent exit failed

    • If the returned status code is not 200, the request failed. Refer to the detail and reason fields to understand the possible reasons for failure.

      Non-200
      • detail string

        Details of the request failure.

      • reason string

        The reason why the request failed.

    Authorization

    This endpoint requires Basic Auth.

    Request example


    _3
    curl --request post \
    _3
    --url 'https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentId/update?sequenceId=&updateMask=' \
    _3
    --header 'Authorization: Basic <credentials>'

    Response example


    _5
    {
    _5
    "agent_id": "Agent ID.",
    _5
    "create_ts": null,
    _5
    "status": "RUNNING"
    _5
    }

    vundefined