API 参考文档

本文档介绍火山引擎实时对话式 AI 的核心 API，包括 StartVoiceChat、UpdateVoiceChat、StopVoiceChat 及相关配置参数。

API 概览

API	说明
StartVoiceChat	启动 AI 语音会话，在指定房间中创建 AI 智能体
StopVoiceChat	停止语音会话，释放 AI 智能体资源
UpdateVoiceChat	更新进行中的语音会话（打断、自定义播报等）

所有 API 均需要使用 AccessKey 进行 V4 签名，参考认证代理服务。

StartVoiceChat

启动 AI 语音会话，在指定房间中创建 AI 智能体。

请求地址：POST https://rtc.volcengineapi.com?Action=StartVoiceChat&Version=2024-12-01

请求参数

参数	类型	必填	说明
`AppId`	string	是	RTC 应用 ID
`RoomId`	string	是	房间 ID
`TaskId`	string	是	任务 ID，用于标识会话
`AgentConfig`	object	是	智能体配置，详见 AgentConfig
`Config`	object	是	会话配置，包含 ASR、TTS、LLM 等参数，详见 Config

AgentConfig

智能体配置：

参数	类型	必填	说明
`TargetUserId`	string[]	是	目标用户 ID 列表，即客户端用户 ID
`UserId`	string	是	智能体用户 ID（AI Bot 的身份标识）
`WelcomeMessage`	string	否	欢迎语，会话开始时自动播报
`EnableConversationStateCallback`	boolean	否	启用会话状态回调，用于接收 listening/thinking/speaking 状态
`AnsMode`	number	否	AI 降噪模式（0: 关闭, 1: 低, 2: 中, 3: 高，推荐 3）
`VoicePrint`	object	否	声纹识别配置：`Mode`（0: 关闭, 1: 开启）、`IdList`（声纹 ID 列表）

Config

会话配置：

参数	类型	说明
`ASRConfig`	object	语音识别配置，详见 ASRConfig
`TTSConfig`	object	语音合成配置，详见 TTSConfig
`LLMConfig`	object	大模型配置，详见 LLMConfig
`InterruptMode`	number	打断模式（0: 语义打断, 1: 手动打断）

响应

json

{
  "ResponseMetadata": {
    "RequestId": "20250104123456789abcdef01234567",
    "Action": "StartVoiceChat",
    "Version": "2024-12-01",
    "Service": "rtc",
    "Region": "cn-north-1"
  },
  "Result": {}
}

成功时 Result 为空对象，失败时 ResponseMetadata.Error 包含错误信息。

注意

StartVoiceChat 用于在已有房间中启动 AI 智能体。

官方文档：StartVoiceChat

StopVoiceChat

停止语音会话，释放 AI 智能体资源。

请求地址：POST https://rtc.volcengineapi.com?Action=StopVoiceChat&Version=2024-12-01

请求参数

参数	类型	必填	说明
`AppId`	string	是	RTC 应用 ID，与 StartVoiceChat 一致
`RoomId`	string	是	房间 ID，与 StartVoiceChat 一致
`TaskId`	string	是	任务 ID，与 StartVoiceChat 一致

响应

json

{
  "ResponseMetadata": {
    "RequestId": "20250104123456789abcdef01234567",
    "Action": "StopVoiceChat",
    "Version": "2024-12-01"
  },
  "Result": {}
}

成功时 Result 为空对象，失败时 ResponseMetadata.Error 包含错误信息。

官方文档：StopVoiceChat

UpdateVoiceChat

更新进行中的语音会话，支持打断、Function calling、自定义播报等操作。

请求地址：POST https://rtc.volcengineapi.com?Action=UpdateVoiceChat&Version=2024-12-01

请求参数

参数	类型	必填	说明
`AppId`	string	是	RTC 应用 ID
`RoomId`	string	是	房间 ID
`TaskId`	string	是	任务 ID
`Command`	string	是	操作命令
`Message`	string	否	播报内容（最长 200 字符）
`InterruptMode`	number	否	播报优先级

Command 命令类型

Command	说明
`Interrupt`	打断当前智能体输出
`ExternalTextToSpeech`	自定义文本转语音播报
`FunctionCallResult`	返回 Function calling 结果

InterruptMode 优先级

用于 ExternalTextToSpeech 命令时指定播报优先级：

值	说明
1	高优先级：终止当前交互，立即播放
2	中优先级：等待当前交互结束后播放
3	低优先级：如果正在交互则丢弃

使用示例

打断智能体：

json

{
  "AppId": "your-app-id",
  "RoomId": "room-uuid",
  "TaskId": "task-id",
  "Command": "Interrupt"
}

自定义播报：

json

{
  "AppId": "your-app-id",
  "RoomId": "room-uuid",
  "TaskId": "task-id",
  "Command": "ExternalTextToSpeech",
  "Message": "您有一条新消息",
  "InterruptMode": 1
}

响应

json

{
  "ResponseMetadata": {
    "RequestId": "20250104123456789abcdef01234567",
    "Action": "UpdateVoiceChat",
    "Version": "2024-12-01"
  },
  "Result": {}
}

成功时 Result 为空对象，失败时 ResponseMetadata.Error 包含错误信息。

官方文档：UpdateVoiceChat

配置参数详解

以下配置用于 StartVoiceChat 的 Config 参数。

ASRConfig

语音识别配置：

参数	类型	必填	说明
`Provider`	string	是	服务提供商，固定 `volcano`
`ProviderParams`	object	是	提供商参数
`VADConfig`	object	否	语音活动检测配置
`VolumeGain`	number	否	音量增益（0.0-1.0），默认 `0.5`
`TurnDetectionMode`	number	否	轮次检测模式
`InterruptConfig`	object	否	打断配置

ProviderParams：

参数	类型	说明
`AppId`	string	ASR 应用 ID
`Mode`	string	识别模式：`smallmodel`（小模型）、`bigmodel`（大模型）
`Cluster`	string	服务集群，默认 `volcengine_streaming_common`
`context`	string	热词上下文（JSON 格式）
`boosting_table_id`	string	热词表 ID
`correct_table_id`	string	纠错表 ID

VADConfig（语音活动检测）：

参数	类型	说明
`SilenceTime`	number	静音判定时长（毫秒），默认 `600`
`SpeechTime`	number	语音判定时长（毫秒）
`PrefixTime`	number	前缀时长（毫秒）
`SuffixTime`	number	后缀时长（毫秒）
`Sensitivity`	number	灵敏度
`AIVAD`	boolean	是否启用 AI VAD

InterruptConfig（打断配置）：

参数	类型	说明
`InterruptSpeechDuration`	number	打断语音时长（毫秒），默认 `400`
`InterruptKeywords`	string[]	语义打断关键词列表

示例配置：

json

{
  "Provider": "volcano",
  "ProviderParams": {
    "AppId": "your-asr-app-id",
    "Mode": "smallmodel",
    "Cluster": "volcengine_streaming_common"
  },
  "VADConfig": {
    "SilenceTime": 600
  },
  "VolumeGain": 0.5,
  "TurnDetectionMode": 0,
  "InterruptConfig": {
    "InterruptSpeechDuration": 400,
    "InterruptKeywords": ["停", "暂停", "等一下", "stop", "wait"]
  }
}

TTSConfig

语音合成配置：

参数	类型	必填	说明
`Provider`	string	是	服务提供商，固定 `volcano`
`ProviderParams`	object	是	提供商参数
`IgnoreBracketText`	number[]	否	忽略的括号类型

ProviderParams：

参数	类型	说明
`app`	object	应用配置
`audio`	object	音频配置
`ResourceId`	string	TTS 资源 ID
`Additions`	object	附加配置

app 配置：

参数	类型	说明
`appid`	string	TTS 应用 ID
`token`	string	TTS 应用 Token
`cluster`	string	服务集群，默认 `volcano_tts`

audio 配置：

不同 TTS 模式下的参数略有不同：

参数	类型	说明	适用模式
`voice_type`	string	音色类型	所有模式
`volume_ratio`	number	音量比例（0.5-2.0）	所有模式
`speed_ratio`	number	语速比例（0.5-2.0）	standard
`pitch_ratio`	number	音调比例（0.5-2.0）	standard
`speech_ratio`	number	语速比例（0.5-2.0）	bigtts
`pitch_rate`	number	音调变化率	bigtts
`speech_rate`	number	语速变化率	bidirection
`emotion`	string	情感类型：`happy`、`sad`、`angry`、`neutral`	支持情感的音色
`emotion_strength`	number	情感强度（0.0-1.0）	配合 emotion 使用

TTS 模式说明

standard：标准模式，使用 speed_ratio、pitch_ratio
bigtts：大模型 TTS，使用 speech_ratio、pitch_rate
bidirection：双向流式，使用 speech_rate，支持 Additions 配置

常用音色：

音色 ID	说明
`BV033_streaming`	女声，温柔
`BV001_streaming`	男声，磁性
`BV700_streaming`	女声，甜美
`BV406_streaming`	男声，沉稳

更多音色参考：火山引擎 TTS 音色列表

示例配置：

json

{
  "Provider": "volcano",
  "ProviderParams": {
    "app": {
      "appid": "your-tts-app-id",
      "token": "your-tts-token",
      "cluster": "volcano_tts"
    },
    "audio": {
      "voice_type": "BV033_streaming",
      "speed_ratio": 1.2,
      "pitch_ratio": 1.1,
      "volume_ratio": 1.0,
      "emotion": "happy",
      "emotion_strength": 0.8
    },
    "ResourceId": "your-resource-id"
  }
}

LLMConfig

大模型配置：

参数	类型	必填	说明
`Mode`	string	是	模式：`ArkV3`（方舟）或 `CustomLLM`（自定义）
`Url`	string	CustomLLM 必填	CustomLLM 回调地址
`APIKey`	string	否	API 认证密钥
`EndPointId`	string	ArkV3 必填	方舟模型端点 ID
`ModelName`	string	否	模型名称
`SystemMessages`	string[]	否	系统提示词列表
`UserPrompts`	object[]	否	预设对话历史
`Temperature`	number	否	采样温度（0.0-1.0），默认 `0.5`
`TopP`	number	否	核采样概率（0.0-1.0），默认 `0.9`
`MaxTokens`	number	否	最大生成 token 数，默认 `256`
`HistoryLength`	number	否	保留的历史轮数，默认 `15`
`EnableRoundId`	boolean	否	启用轮次 ID
`VisionConfig`	object	否	视觉理解配置：`Enable`（是否启用）、`SnapshotConfig`（截图配置）
`Custom`	string	否	自定义参数（JSON 字符串），透传给 CustomLLM

UserPrompts（预设对话历史）：

json

[
  { "Role": "assistant", "Content": "你好！有什么可以帮助你的？" },
  { "Role": "user", "Content": "你好" }
]

CustomLLM 模式示例：

json

{
  "Mode": "CustomLLM",
  "Url": "https://your-server.com/chat-stream",
  "APIKey": "your-api-key",
  "ModelName": "qwen-flash",
  "Temperature": 0.5,
  "TopP": 0.9,
  "MaxTokens": 256,
  "HistoryLength": 15,
  "EnableRoundId": true,
  "VisionConfig": {
    "Enable": false
  },
  "UserPrompts": [
    { "Role": "assistant", "Content": "嗨～我是助手，很高兴见到你！" }
  ]
}

ArkV3 模式示例：

json

{
  "Mode": "ArkV3",
  "EndPointId": "your-endpoint-id",
  "Temperature": 0.7,
  "MaxTokens": 512
}

CustomLLM 回调

使用 CustomLLM 模式时，火山引擎会将用户语音识别结果回调到自定义服务。

回调流程

用户语音 → 火山引擎 ASR → CustomLLM 服务 → 火山引擎 TTS → 用户

请求格式

火山引擎发送到 CustomLLM 服务的请求：

http

POST /chat-stream HTTP/1.1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "messages": [
    {"role": "system", "content": "你是一个智能助手"},
    {"role": "user", "content": "你好"}
  ],
  "stream": true,
  "temperature": 0.7,
  "max_tokens": 256,
  "device_id": "custom-device-id"
}

请求字段：

字段	说明
`messages`	对话历史，OpenAI 格式
`stream`	固定 `true`，流式响应
`temperature`	采样温度
`max_tokens`	最大生成长度
`device_id`	自定义参数，从 `LLMConfig.Custom` 透传

响应格式

响应需遵循 OpenAI SSE 格式：

data: {"id":"resp-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"model":"qwen-flash","created":1704355200}

data: {"id":"resp-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}],"model":"qwen-flash","created":1704355200}

data: {"id":"resp-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"！"},"finish_reason":"stop"}],"model":"qwen-flash","created":1704355200}

data: [DONE]

响应要点：

必须返回 SSE 流式响应
Content-Type: text/event-stream
每行以 data: 开头
最后一行为 data: [DONE]

官方文档：CustomLLM 接入

RTC Token

客户端加入 RTC 房间需要 Token。Token 由服务端使用 AppKey 生成。

Token 结构

Token = Version + AppId + Base64(Message + Signature)

Version：固定值 001
AppId：24 位应用标识符
Message：二进制编码的负载（RoomId、UserId、过期时间、权限等）
Signature：使用 AppKey 进行 HMAC-SHA256 签名

Token 权限

权限	说明
`PrivPublishStream`	发布音视频流
`PrivSubscribeStream`	订阅音视频流

有效期

默认 24 小时（86400 秒）。过期后需重新生成。

生成示例

typescript

import { AccessToken } from './rtctoken'

const token = new AccessToken(appId, appKey, roomId, userId)
const expireAt = Math.floor(Date.now() / 1000) + 24 * 3600
token.addPrivilege('PrivPublishStream', expireAt)
token.addPrivilege('PrivSubscribeStream', expireAt)
token.expireTime(expireAt)
const tokenString = token.serialize()

Token 生成库参考安装与测试 - 生成 RTC Token。

错误码

响应格式

json

{
  "ResponseMetadata": {
    "RequestId": "xxx",
    "Action": "StartVoiceChat",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "参数 AppId 不能为空"
    }
  }
}

公共错误码

错误码	HTTP 状态码	说明
`MissingParameter`	400	缺少必要参数（如 Action、Version）
`InvalidParameter`	400	参数格式错误或无效
`MissingRequestInfo`	400	缺少请求信息（如 X-Date 头）
`InvalidTimestamp`	400	请求过期或时间戳无效，检查 UTC 时间格式
`InvalidAuthorization`	400	Authorization 头格式错误
`InvalidCredential`	400	Credential 格式错误
`InvalidAccessKey`	401	AccessKey 无效或格式错误
`SignatureDoesNotMatch`	401	签名验证失败，检查 SecretKey
`InvalidSecretToken`	401	STS 临时凭证过期或无效
`AccessDenied`	403	IAM 权限不足
`ServiceNotFound`	404	服务不存在
`InvalidActionOrVersion`	404	API Action 或 Version 不存在
`FlowLimitExceeded`	429	请求频率超限，降低 QPS
`InternalError`	500	内部错误
`InternalServiceError`	502	服务网关错误
`ServiceUnavailableTemp`	503	服务暂时不可用
`InternalServiceTimeout`	504	服务超时

业务错误码

错误码	说明
`RoomNotExist`	房间不存在
`TaskNotExist`	任务不存在
`InvalidToken`	RTC Token 无效或过期

官方文档：公共错误码

JT/T 808 协议网关

GB/T 32960 协议网关

火山引擎 RTC

场景样例

GPT-Realtime

API 参考文档 ​

API 概览 ​

StartVoiceChat ​

请求参数 ​

AgentConfig ​

Config ​

响应 ​

StopVoiceChat ​

请求参数 ​

响应 ​

UpdateVoiceChat ​

请求参数 ​

Command 命令类型 ​

InterruptMode 优先级 ​

使用示例 ​

响应 ​

配置参数详解 ​

ASRConfig ​

TTSConfig ​

LLMConfig ​

CustomLLM 回调 ​

回调流程 ​

请求格式 ​

响应格式 ​

RTC Token ​

Token 结构 ​

Token 权限 ​

有效期 ​

生成示例 ​

错误码 ​

响应格式 ​

公共错误码 ​

业务错误码 ​

相关资源 ​

API 参考文档

API 概览

StartVoiceChat

请求参数

AgentConfig

Config

响应

StopVoiceChat

请求参数

响应

UpdateVoiceChat

请求参数

Command 命令类型

InterruptMode 优先级

使用示例

响应

配置参数详解

ASRConfig

TTSConfig

LLMConfig

CustomLLM 回调

回调流程

请求格式

响应格式

RTC Token

Token 结构

Token 权限

有效期

生成示例

错误码

响应格式

公共错误码

业务错误码

相关资源