Update task configuration
Updated
Updates the configuration of a Real-time STT task.
https://api.agora.io/api/speech-to-text/v1/projects/{appid}/agents/{agentId}/updateUse this method to update the configuration of a Real-time STT task. Updating the transcription languages, translation languages, or subscribed users does not reset the idle-timeout timer or the maximum task lifetime timer. Both timers start from the moment the task was created.
Path Parameters
appidstringThe App ID of the project.
agentIdstringThe unique identifier of the agent you received in the response body of the join method.
Query Parameters
sequenceIdintegerThe 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.
updateMaskstringThe 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
languagesarray<string>The transcription languages to recognize. You can specify up to 4 languages. Refer to Supported Languages for details. Choosing multiple transcription languages can affect both quality and cost. For best practices, see Optimize transcription quality and cost.
keywordsarray<string>Keyword list. Use it to improve the recognition accuracy of specific words during transcription. Supports up to 500 words.
uidLanguagesConfigarray<object>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 [].
uidstringThe ID of the user to be transcribed. You may configure a maximum of 5 uids for language recognition at the uid level.
languagesarray<string>The transcription languages to recognize. Each uid can support a maximum of 4 languages. Refer to Supported Languages for details.
rtcConfigobjectSubscription configuration.
subscribeAudioUidsarray<string>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.
translateConfigobjectSubtitle translation configuration.
enablebooleanWhether to translate the transcribed text:
true: Translate.false: Do not translate. If you enabled translation when callingjoin, you can turn it off by settingenabletofalse. If you did not enable translation, you can turn it on by settingenabletotrueand specifyinglanguages.
languagesarray<object>The translation languages array. You can specify a maximum of 4 different source languages.
sourcestringThe source language for translation. Refer to Supported Languages for details.
targetarray<string>The target languages for translation. You can configure up to 10 target languages for each source language. Refer to Supported Languages for details.
- Single-language input: If you set the source language to a single language, the target language must be different, otherwise an error is returned. For example, if you set the source language to English, you cannot set the target language to English.
- Mixed-language input: If you set the source language to mixed-language input, you can set the target language to one of the source languages. For example, if you set the source languages to Chinese and English, setting the target language to English translates both into English.
Response
- If the returned status code is
200, the request was successful. The response body contains the result of the request.
Response Body
OK
agent_idstringThe ID of the agent.
create_tsintegerThe Unix timestamp (in seconds) when the agent was created.
statusstringThe current status of the agent:
IDLE: The agent is not initializedSTARTING: The agent is startingRUNNING: The agent is runningSTOPPING: The agent is exitingSTOPPED: The agent exited successfullyRECOVERING: The agent is recoveringFAILED: Agent exit failed
Response
Refer to the detail and reason fields to understand the possible reasons for failure.
Request examples
curl --request POST \ --url 'https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentid/update?sequenceId=1&updateMask=translateConfig.enable,translateConfig.languages' \ --header 'Authorization: Basic <credentials>' \ --data '{ "translateConfig": { "enable": true, "languages": [ { "source": "en-US", "target": ["ja-JP"] } ] }}'Response example
{ "agent_id": "Agent ID.", "create_ts": null, "status": "RUNNING"}