# 开始实时转录翻译 (/zh-CN/realtime-media/speech-to-text/get-started/quick-start) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 实时转录翻译服务可以订阅媒体流的音频内容,并将其实时转写为指定语言的文本。 本文介绍如何使用基本的 RESTful API 方法来启动、停止和查询实时转录翻译服务。 :::warning[注意] 命令行示例仅用于演示目的。在生产环境中,请通过你的应用服务器发送 RESTful API 请求。 ::: ## 技术原理 [#技术原理] 以下流程图概述了实现实时转录翻译的流程: ![实时转录翻译流程图](https://web-cdn.agora.io/docs-portal/img/speech-to-text/real-time-stt-flow.png) 该流程包括调用以下 RESTful API 方法: 1. `start`:调用该方法加入频道并开始转写。如果请求成功,你会在响应 Body 中收到一个 `agent_id`,用于标识当前的转写会话。 2. `update`:在转写服务运行过程中,使用 `update` 方法修改转写或翻译语言,或更新启用转写的主播。 3. `query`:在 `start` 后,调用 `query` 来查询服务状态。 4. `stop`:调用该方法停止转写。 ## 前提条件 [#前提条件] 开始前,请确保你的开发环境满足以下条件: - 参考[开通服务](/zh-CN/realtime-media/speech-to-text/build/start-transcribing-and-translating/enable-service)在声网控制台开通实时转录翻译服务,并复制保存 App ID、临时 Token、客户 ID 和客户密钥,以供后续使用。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 集成并使用声网 [实时互动 RTC SDK](/zh-CN/realtime-media/rtc/get-started/quick-start) 搭建一个极简的实时音视频互动 App。 - 参考[实现 HTTP 基本认证](/zh-CN/realtime-media/speech-to-text/build/start-transcribing-and-translating/http-basic-auth)获取 `Authorization` 值。 ## 实现实时转录翻译 [#实现实时转录翻译] 本节介绍调用 `start`、`stop`、`update` 和 `query` 实时转录翻译服务的示例 API 调用。 ### 启用服务 [#启用服务] 调用 `start` 开始字幕录制和翻译。 请求成功时,你会在 HTTP 响应 Body 中收到一个 `agent_id`。此 ID 是转写会话的唯一标识符。 **请求示例** 以下是启动实时转录翻译的简单请求示例。有关更多功能配置,请参考[加密字幕](/zh-CN/realtime-media/speech-to-text/build/process-transcription-data/encrypt-captions)、[录制字幕](/zh-CN/realtime-media/speech-to-text/build/process-transcription-data/record-captions)和[转写指定主播](/zh-CN/realtime-media/speech-to-text/build/start-transcribing-and-translating/transcribe-specified-hosts)。 ```shell curl --request post \ --url https://api.sd-rtn.com/cn/api/speech-to-text/v1/projects/:appid/join \ --header 'Authorization: Basic ' \ --data ' { "languages": [ "en-US" ], "name": "agora-test", "maxIdleTime": 50, "rtcConfig": { "channelName": "agora-test", "subBotUid": "47091", "pubBotUid": "88222" }, "translateConfig": { "languages": [ { "source": "en-US", "target": [ "ar-SA", "id-ID", "fr-FR", "ja-JP" ] } ] }, "captionConfig": { "sliceDuration": 60, "storage": { "accessKey": "test-oss", "secretKey": "test-oss", "bucket": "test-oss", "vendor": 2, "region": 3 } } }' ``` :::warning[注意] - 字符串用户 ID 仅在 128 主播环境中受支持,计划在不久的将来提供全面支持。 - `pubBotUid` 和 `subBotUid` 是 `int` 类型的用户 ID,必须不同以避免未知问题。 ::: **响应示例** - 成功 ```json { "agent_id": "Agent ID.", "create_ts": null, "status": "RUNNING" } ``` | 参数名称 | 类型 | 描述 | | --- | --- | --- | | `agent_id` | String | 服务的 ID。 | | `create_ts` | Integer | 服务创建时的 Unix 时间戳(秒)。 | | `status` | String | [quick-start-html-0-3-2 details](#table-slot-quick-start-html-0-3-2) | **quick-start-html-0-3-2 details** 服务状态: - `STARTING`:服务正在启动。 - `RUNNING`:服务正在运行。 - `STOPPING`:服务正在退出。 - `STOPPED`:服务已成功退出。 - `RECOVERING`:服务正在恢复。 - `FAILED`:服务退出失败。 - 失败 ```json { "detail": "Details of the request failure.", "reason": "The reason why the request failed." } ``` ### 查询服务状态 [#查询服务状态] 调用 `query` 获取转写会话期间服务的状态。请求成功时,你会在响应 Body 中收到当前状态和相关信息。 **请求示例** ```shell curl --request GET \ --url https://api.sd-rtn.com/cn/api/speech-to-text/v1/projects/:appid/agents/:agentId \ --header 'Authorization: Basic ' ``` **响应示例** - 成功 ```json { "message": "Details of the request result.", "agent_id": "Agent ID.", "create_ts": null, "status": "RUNNING" } ``` - 失败 ```json { "message": "Details of the failed request.", "agent_id": "Agent ID.", "create_ts": null, "status": "FAILED" } ``` ### 更新配置 [#更新配置] 详情请参考[更新配置](/zh-CN/realtime-media/speech-to-text/build/start-transcribing-and-translating/update-service)。 ### 停止服务 [#停止服务] 调用 `stop` 停止转写。请求成功时,你会在响应 Body 中收到转写会话的状态。 **请求示例** ```shell curl --request POST \ --url https://api.sd-rtn.com/cn/api/speech-to-text/v1/projects/:appid/agents/:agentId/leave \ --header 'Authorization: Basic ' ``` ## 参考信息 [#参考信息] ### 示例项目和源代码 [#示例项目和源代码] 你可以查看[Demo](https://stt-demo.agora.io) 体验实时转录翻译并评估其准确性和延迟。 你也可以参考 [GitHub 上的示例项目](https://github.com/AgoraIO-Community/Agora-RTT-Demo)了解字幕和转写的实现方式。如需更多演示代码,请联系 [support@agora.io](mailto:support@agora.io)。 ### REST API 中间件 [#rest-api-中间件] [Agora Go Backend Middleware](https://github.com/AgoraIO-Community/agora-go-backend-middleware) 是一个开源微服务,它公开了一个 RESTful API,旨在简化与声网的交互。该项目使用 Golang 编写,由 Gin 框架驱动,作为中间件连接使用声网视频 SDK 或视频 SDK 的前端应用与声网的 RESTful API。