# 更新实时转录翻译任务 (/zh-CN/api-reference/api-ref/speech-to-text/update)

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

更新实时转录翻译任务配置。

- OpenAPI: /openapi/speech-to-text/v7.zh-CN.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

通过 [`join`](join) 方法开始转写任务后，你可以发起 `update` 请求更新转写任务配置。

调用该方法更新转写语言、翻译语言、订阅用户等配置不会重置空闲超时计时器，也不会重置任务最长运行时长计时器。上述计时器的起点固定为任务创建完成时刻。


## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `appid` (path, required, string) - 你的项目的 App ID，可在[声网控制台](https://console.shengwang.cn/)获取。
- `agentId` (path, required, string) - 服务的 ID。通过 [`join`](./join) 方法中的响应包体获取。
- `sequenceId` (query, required, integer) - 已废弃。`update` 请求的序列号。取值需要大于或等于 0。请确保后一次 `update` 请求的序列号大于前一次 `update` 请求的序列号。序列号可以确保声网服务器按照你指定的最新配置来更新转写任务。
  - Format: `int64`
- `updateMask` (query, required, string) - 已废弃。指定的更新配置项。如果需要更新多个字段的配置，则需要以逗号作为间隔符。例如：`updateMask=languages,rtcConfig.subscribeAudioUids,translateConfig.enable,translateConfig.languages,uidLanguagesConfig`。

## Request body

- `languages` (array) - 实时转录翻译需要识别的语种，最多支持 4 种语言。
可参考[支持识别的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)进行设置。

  - Max items: `4`
  - `languages.items` (string)
- `keywords` (array) - 热词列表。用于提升转写时对特定词汇的识别准确率。最多支持 500 个词。

  - Max items: `500`
  - `keywords.items` (string)
- `uidLanguagesConfig` (array) - 配置指定用户 ID 的转写语种。最多支持 5 个配置项。
> [!CAUTION]
> 如果你在调用 [`join`](./join) 时设置了该字段，现在需要不指定任何用户，则将该字段设为 `[]`（空数组）。

  - Max items: `5`
  - `uidLanguagesConfig.items` (object)
    - `uidLanguagesConfig.items.uid` (string, required) - 必选，需要进行转写的用户 ID。最多允许为 5 个 uid 配置 uid 维度的语种识别。

    - `uidLanguagesConfig.items.languages` (array, required) - 必选，需要识别的转录语种。每个 uid 最多支持设置 4 种语言。
可参考[支持的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)进行设置。

      - Max items: `4`
      - `uidLanguagesConfig.items.languages.items` (string)
- `rtcConfig` (object) - 订阅配置。
  - `rtcConfig.subscribeAudioUids` (array) - 用户 ID。如果你需要指定订阅某些用户的音频流，可以设置该字段。
如果需要订阅所有用户的音频流，则 `subscribeAudioUids` 填 `["all"]`。
数组长度不得超过 32。

    - Max items: `32`
    - `rtcConfig.subscribeAudioUids.items` (string)
- `translateConfig` (object) - 字幕翻译配置。如果你在调用 [`join`](./join) 时启用了翻译功能，如需关闭该功能，可将 `enable` 设为 `false`。
如果你未启用翻译功能，可将 `enable` 设为 `true` 并设置 `languages` 来开启翻译功能。

  - `translateConfig.enable` (boolean) - 是否把转写后的文字进行翻译：
- `true`：翻译。
- `false`：不翻译。

  - `translateConfig.languages` (array) - 翻译语言数组。数组长度不得超过 4，即最多支持对 4 种不同的源语进行翻译。

    - Max items: `4`
    - `translateConfig.languages.items` (object) - 翻译语言对配置
      - `translateConfig.languages.items.source` (string, required) - 必选，翻译的源语言。
支持翻译的源语言详见[支持的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)。

      - `translateConfig.languages.items.target` (array, required) - 必选，翻译的目标语言。数组长度不得超过 10。
支持翻译的目标语言详见[支持的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)。
> [!CAUTION]
> - 源语言为单语言时，翻译的目标语言需要和源语言不同，否则会报错。例如中文输入时，翻译的目标语言不能选择中文。
> - 源语言为多语言混合输入时，翻译的目标语言可以和源语种重复，例如中文和英文混合输入时，翻译的目标语言可以是中文，那么混入输入的中文和英文都会被翻译成中文。

        - Max items: `10`
        - `translateConfig.languages.items.target.items` (string)

## Responses

### 200

如果返回的状态码为 `200`，表示请求成功。

- `agent_id` (string) - 服务的 ID。
- `create_ts` (integer) - 服务创建时的 Unix 时间戳（秒）。
- `status` (string) - 服务的状态：
- `STARTING`：服务开始启动。
- `RUNNING`：服务进行中。
- `STOPPING`：服务退出中。
- `STOPPED`：服务退出成功。
- `RECOVERING`：服务恢复中。
- `FAILED`：服务退出失败。
  - Allowed: `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `RECOVERING` | `FAILED`
### default

如果返回的状态码不为 `200`，请求失败。请根据 `details` 和 `reason` 字段进行排查。

- `detail` (string) - 请求失败的详细信息。
- `reason` (string) - 请求失败的原因。

## Response examples

### 200

```json
{
  "agent_id": "1NT29X11GQSxxxxx80BEIN56XF",
  "create_ts": 1735035893,
  "status": "RUNNING"
}
```
### default

```json
{
  "detail": "请求失败的详细信息。",
  "reason": "请求失败的原因。"
}
```