# Update task configuration (/en/api-reference/api-ref/speech-to-text/update)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Updates the configuration of a Real-time STT task.

- OpenAPI: /openapi/speech-to-text/v7.en.yaml
- Operation ID: update
- Method: POST
- Path: /api/speech-to-text/v1/projects/{appid}/agents/{agentId}/update
- Endpoint: https://api.agora.io/api/speech-to-text/v1/projects/{appid}/agents/{agentId}/update

## Servers

- https://api.agora.io

Use 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.


## Authorization

This endpoint requires authentication.

- `BasicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `agentId` (path, required, string) - The unique identifier of the agent you received in the response body of the `join` method.
- `sequenceId` (query, required, integer) - 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.
  - Format: `int64`
- `updateMask` (query, required, string) - 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

- `languages` (array) - The transcription languages to recognize. You can specify up to 4 languages. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages#real-time-translation) for details. Choosing multiple transcription languages can affect both quality and cost. For best practices, see [Optimize transcription quality and cost](/en/realtime-media/speech-to-text/build/extend-and-optimize/optimize-quality).
  - Max items: `4`
  - `languages.items` (string)
- `keywords` (array) - Keyword list. Use it to improve the recognition accuracy of specific words during transcription. Supports up to 500 words.
  - Max items: `500`
  - `keywords.items` (string)
- `uidLanguagesConfig` (array) - 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 `[]`.
  - Max items: `5`
  - `uidLanguagesConfig.items` (object) - Configure the transcription language for the specified user ID. Supports up to 5 configuration items.
    - `uidLanguagesConfig.items.uid` (string, required) - The ID of the user to be transcribed. You may configure a maximum of 5 uids for language recognition at the uid level.
    - `uidLanguagesConfig.items.languages` (array, required) - The transcription languages to recognize. Each uid can support a maximum of 4 languages. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages) for details.
      - Max items: `4`
      - `uidLanguagesConfig.items.languages.items` (string)
- `rtcConfig` (object) - Subscription configuration.
  - `rtcConfig.subscribeAudioUids` (array) - 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.
    - Max items: `32`
    - `rtcConfig.subscribeAudioUids.items` (string)
- `translateConfig` (object) - Subtitle translation configuration.
  - `translateConfig.enable` (boolean) - 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`.
  - `translateConfig.languages` (array) - The translation languages array. You can specify a maximum of 4 different source languages.
    - Max items: `4`
    - `translateConfig.languages.items` (object) - Translation language pair configuration.
      - `translateConfig.languages.items.source` (string, required) - The source language for translation. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages#real-time-translation) for details.
      - `translateConfig.languages.items.target` (array, required) - The target languages for translation. You can configure up to 10 target languages for each source language. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages#real-time-translation) 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.
        - Max items: `10`
        - `translateConfig.languages.items.target.items` (string)

## Request examples

### curl

```bash
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"]
      }
    ]
  }
}'
```

### Python

```python
import requests

url = "https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentid/update"
params = {
    "sequenceId": 1,
    "updateMask": "translateConfig.enable,translateConfig.languages"
}
payload = {
    "translateConfig": {
        "enable": True,
        "languages": [
            {
                "source": "en-US",
                "target": ["ja-JP"]
            }
        ]
    }
}
headers = {"Authorization": "Basic <credentials>"}

response = requests.request("POST", url, params=params, json=payload, headers=headers)
print(response.text)
```

### Node.js

```javascript
const url = 'https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentid/update?sequenceId=1&updateMask=translateConfig.enable,translateConfig.languages';
const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <credentials>'},
  body: JSON.stringify({
    translateConfig: {
      enable: true,
      languages: [
        {
          source: 'en-US',
          target: ['ja-JP']
        }
      ]
    }
  })
};

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


### Response

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


## Responses

### 200

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
  - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `RECOVERING` | `FAILED`
### default

Error response.

- `detail` (string) - Details of the request failure.
- `reason` (string) - The reason why the request failed.

### Response

Refer to the detail and reason fields to understand the possible reasons for failure.


## Response examples

### 200

```json
{
  "agent_id": "Agent ID.",
  "create_ts": null,
  "status": "RUNNING"
}
```
### default

```json
{
  "detail": "Details of the request failure.",
  "reason": "The reason why the request failed."
}
```