> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

## 上行事件 {#3482fcbd}
### 更新语音识别配置 {#a7ca67ab}

* **事件类型**：`transcriptions.update`
* **事件说明**：更新语音识别配置。若更新成功，会收到 `transcriptions.updated` 的下行事件，否则，会收到 `error` 下行事件。
* **事件结构**：
   <!-- @cols-width: 224,100,100,414 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `transcriptions.update`。 |
   | | | | | \
   |data |Object |可选 |事件数据，包含语音识别配置的详细信息。 |
   | | | | | \
   |data.input_audio |Object |可选 |输入音频格式。 |
   | | | | | \
   |data.input_audio.format |String |可选 |输入音频的格式，支持 `pcm`、`wav`、`ogg`。默认为 `wav`。 |
   | | | | | \
   |data.input_audio.codec |String |可选 |输入音频的编码，支持 `pcm`、`opus`。默认为 `pcm`。 |
   | | | | | \
   |data.input_audio.sample_rate |Integer |可选 |输入音频的采样率，默认 24000。 |
   | | | | | \
   |data.input_audio.channel |Integer |可选 |输入音频的声道数，默认是 1（单声道）。 |
   | | | | | \
   |data.input_audio.bit_depth |Integer |可选 |输入音频的位深，默认是 16。 |
   | | | | | \
   |data.asr_config |Object |可选 |语音识别配置，包括热词和上下文信息，以便优化语音识别的准确性和相关性。 |
   | | | | | \
   |data.asr_config.hot_words |Array<String> |可选 |输入热词列表，以便提升这些词汇的识别准确率。 |\
   | | | |所有热词加起来最多100个 Tokens，超出部分将自动截断。 |
   | | | | | \
   |data.asr_config.context |String |可选 |输入上下文信息。 |\
   | | | |最多输入 800 个 Tokens，超出部分将自动截断。 |
   | | | | | \
   |data.asr_config.user_language |String |可选  |用户说话的语种，默认为 `common`。选项包括：  |\
   | | | | |\
   | | | |* common：大模型语音识别，可自动识别中英粤。 |\
   | | | |* zh：小模型语音识别，中文。 |\
   | | | |* cant：小模型语音识别，粤语。 |\
   | | | |* sc：小模型语音识别，川渝。 |\
   | | | |* en：小模型语音识别，英语。 |\
   | | | |* ja：小模型语音识别，日语。 |\
   | | | |* ko：小模型语音识别，韩语。 |\
   | | | |* fr：小模型语音识别，法语。 |\
   | | | |* id：小模型语音识别，印尼语。 |\
   | | | |* es：小模型语音识别，西班牙语。 |\
   | | | |* pt：小模型语音识别，葡萄牙语。 |\
   | | | |* ms：小模型语音识别，马来语。 |\
   | | | |* ru：小模型语音识别，俄语。 |
   | | | | | \
   |data.asr_config.enable_ddc |Boolean |可选  |将语音转为文本时，是否启用语义顺滑。默认为 `true`。 |\
   | | | | |\
   | | | |* `true`：系统在进行语音处理时，会去掉识别结果中诸如 “啊”“嗯” 等语气词，使得输出的文本语义更加流畅自然，符合正常的语言表达习惯，尤其适用于对文本质量要求较高的场景，如正式的会议记录、新闻稿件生成等。 |\
   | | | |* `false`：系统不会对识别结果中的语气词进行处理，识别结果会保留原始的语气词。 |
   | | | | | \
   |data.asr_config.enable_itn |Boolean |可选  |将语音转为文本时，是否开启文本规范化（ITN）处理，将识别结果转换为更符合书面表达习惯的格式以提升可读性。默认为 `true`。 |\
   | | | |开启后，会将口语化数字转换为标准数字格式，示例： |\
   | | | | |\
   | | | |* 将`两点十五分`转换为 `14:15`。 |\
   | | | |* 将`一百美元`转换为 `$100`。 |
   | | | | | \
   |data.asr_config.enable_punc |Boolean |可选  |将语音转为文本时，是否给文本加上标点符号。默认为 `true`。 |




* **事件示例**：

```JSON
{
  "id": "event_id",
  "event_type": "transcriptions.update",
  "data": {
      "input_audio": {
          "format": "pcm",
          "codec": "pcm",
          "sample_rate": 24000,
          "channel": 1,
          "bit_depth": 16
      }
  }
}
```

### 流式上传音频片段 {#9ef6e6ca}

* **事件类型**：`input_audio_buffer.append`
* **事件说明**：流式向服务端提交音频的片段。
* **事件结构**：

<!-- @cols-width: 100,100,100,387 -->
| | | | | \
|**参数** |**类型** |**是否必选** |**说明** |
|---|---|---|---|
| | | | | \
|id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
| | | | | \
|event_type |String |必选 |固定为 `input_audio_buffer.append`。 |
| | | | | \
|data |Object |必选 |事件数据，包含音频片段信息。 |
| | | | | \
|data.delta |String |必选 |base64 编码后的音频片段。 |


* **事件示例**：

```JSON
{
  "id": "event_id",
  "event_type": "input_audio_buffer.append",
  "data": {
     "delta": "base64EncodedAudioDelta"
  }
}
```

### 提交音频  {#f5d76c87}

* **事件类型**：`input_audio_buffer.complete`
* **事件说明**：客户端发送 `input_audio_buffer.complete` 事件来告诉服务端提交音频缓冲区的数据。服务端提交成功后会返回 `input_audio_buffer.completed` 事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,434 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.complete`。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_id",
     "event_type": "input_audio_buffer.complete"
   }
   ```


### 清除缓冲区音频 {#e98db543}

* **事件类型**：`input_audio_buffer.clear`
* **事件说明**：客户端发送 `input_audio_buffer.clear` 事件来告诉服务端清除缓冲区的音频数据。服务端清除完后将返回 `input_audio_buffer.cleared` 事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,391 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.clear`。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_1",
     "event_type": "input_audio_buffer.clear"
   }
   ```


## 下行事件 {#9f1a57d6}
### 连接成功  {#06d772a3}

* **事件类型**：`transcriptions.created`
* **事件说明**：语音识别连接成功后，返回此事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |服务端生成的唯一 ID。 |
   | | | | | \
   |event_type |String |必选 |固定为 `transcriptions.created`。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```JSON
   {
     "id": "7446668538246561xxxx",
     "event_type": "transcriptions.created",
     "detail": {
         "logid": "20241210152726467C48D89D6DB2F3***"
     }
   }
   ```


### 配置更新成功 {#3f842df1}

* **事件类型**：`transcriptions.updated`
* **事件说明**：配置更新成功后，会返回最新的配置。
* **事件结构**：
   <!-- @cols-width: 224,100,100,425 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `transcriptions.updated`。 |
   | | | | | \
   |data |Object |必选 |事件数据，包含语音识别配置的详细信息。 |
   | | | | | \
   |data.input_audio |Object |必选 |输入音频格式。 |
   | | | | | \
   |data.input_audio.format |String |必选 |输入音频的格式，支持 `pcm`、`wav`、`ogg`。默认为 `wav`。 |
   | | | | | \
   |data.input_audio.codec |String |必选 |输入音频的编码，支持 `pcm`、`opus`。默认为 `pcm`。 |
   | | | | | \
   |data.input_audio.sample_rate |Integer |必选 |输入音频的采样率，默认 24000。 |
   | | | | | \
   |data.input_audio.channel |Integer |必选 |输入音频的声道数，默认是 1（单声道）。 |
   | | | | | \
   |data.input_audio.bit_depth |Integer |必选 |输入音频的位深，默认是 16。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_id",
     "event_type": "transcriptions.updated",
     "data": {
         "input_audio": {
             "format": "pcm",
             "codec": "pcm",
             "sample_rate": 24000,
             "channel": 1,
             "bit_depth": 16
         }
     },
     "detail": {
         "logid": "20241210152726467C48D89D6DB2F3***"
     }
   }
   ```


### 音频提交完成 {#8d747148}

* **事件类型**：`input_audio_buffer.completed`
* **事件说明**：流式提交的音频完成后，返回此事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.completed`。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_id",
     "event_type": "input_audio_buffer.completed",
     "detail": {
         "logid": "20241210152726467C48D89D6DB2F3***"
     }
   }
   ```


### 音频清除成功 {#8211875b}

* **事件类型**：`input_audio_buffer.cleared`
* **事件说明**：清除缓冲区音频成功后，返回此事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.cleared`。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```Python
   {
       "id": "event_id",
       "event_type": "input_audio_buffer.cleared",
       "detail": {
           "logid": "20241210152726467C48D89D6DB2F3***"
       }
   }
   ```


### 识别出文字 {#772e6d2d}

* **事件类型**：`transcriptions.message.update`
* **事件说明**：语音识别出文字后，返回此事件，每次都返回全量的识别出来的文字。
* **事件结构**：
   <!-- @cols-width: 100,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `transcriptions.message.update`。 |
   | | | | | \
   |data |Object |必选 |事件数据，包含识别出的文字。 |
   | | | | | \
   |data.content |String |必选 |识别出的文字。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_id",
     "event_type": "transcriptions.message.update",
     "data": {
         "content": "text"
     },
     "detail": {
         "logid": "20241210152726467C48D89D6DB2F3***"
     }
   }
   ```


### 识别完成 {#0c36158c}

* **事件类型**：`transcriptions.message.completed`
* **事件说明**：语音识别完成后，返回此事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `transcriptions.message.completed`。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```HTTP
   {
     "id": "event_id",
     "event_type": "transcriptions.message.completed",
     "detail": {
         "logid": "20241210152726467C48D89D6DB2F3***"
     }
   }
   ```


### 发生错误 {#06be77c0}

* **事件类型**：`error`
* **事件说明**：识别过程中的错误事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |服务端生成的唯一 ID。 |
   | | | | | \
   |event_type |String |必选 |固定为 `error`。 |
   | | | | | \
   |data |Object |必选 |事件数据，包含错误信息。 |
   | | | | | \
   |data.code |Integer |必选 |错误码。 |
   | | | | | \
   |data.msg |String |必选 |错误信息。 |
   | | | | | \
   |detail |Object |必选 |事件详情。 |
   | | | | | \
   |detail.logid |String |必选 |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_1",
     "event_type": "error",
     "data": {
         "code": 1,
         "msg": "发生异常"
     },
     "detail": {
         "logid": "20241210152726467C48D89D6DB2F3***"
     }
   }
   ```