开启实时对话 - 音视频通话 2.0

开发者中心

音视频通话 2.0

服务端 API

开启实时对话

更新时间： 2025/10/13 11:35:43

调用该接口开启实时对话任务，提供 AI 智能体与用户之间音视频通话服务。该接口支持用户按需设置 AI 能力模块（例如自动语音识别 ASR、文字转语音 TTS、大语言模型 LLM）参数，个性化定制用户专属的 AI 智能体。

功能说明

您可以通过服务端 API 或者客户端 API 发起任务，在任务发起后，网易云信音视频通话通过 AI Service 能力整理参数，并向媒体处理服务器（Media Process Server，MPS）下发任务，启动 AI Pipeline，编解码后的 AI 音视频通过网易云信媒体服务器下发至客户端 SDK（NERTC SDK）。详细流程如下图所示：

服务端 API 调用

客户端 API 调用

客户端 API 调用示例请参考基于 RTC SDK 实现音视频 AI 数字人互动。

请求信息

请求 URI

服务端 API 调用

请求方法：POST
URL：https://rtc-ai.yunxinapi.com/v1/api/task/create

客户端 API 调用

请求方法：POST
URL：https://rtc-ai.yunxinapi.com/ai/task/create

请求头参数

服务端 API 调用

请求头部的参数说明请参考请求结构。

客户端 API 调用

参数名称	类型	是否必选	说明
`AppKey`	String	是	请登录网易云信控制台查看您的应用对应的 AppKey，具体请参考创建应用并获取 AppKey。
`Token`	String	是	客户端向用户服务器请求并获取的 Token，具体请参考获取 Token。
`Cname`	String	是	获取 Token 时使用的 `channelName`，即 RTC 房间名称。
`Uid`	String	是	获取 Token 时使用的 `uid`，即用户在您应用中的 ID。

请求体参数

参数名称	类型	是否必选	取值示例	说明
`cname`	String	是	meeting_name111	房间名称。
`requestId`	String	否	f8f274c1-0e9f-4583-a243-c61c06a19475	任务 ID。您可以设置为随机字符串，用于问题排查。
`taskType`	Number	是	7	AI 任务类型。如果是实时对话，取值固定为 7。
- `data`	Object	是	-	请求体具体信息。
- `agent`	Object	否	-	网易云信智能体参数信息。该参数仅适用于使用网易云信智能体（Agent）时配置。
`agentId`	String	是	a26150118xxxxx19cba	网易云信智能体 ID。
`userId`	String	是	9527	使用网易云信智能体的用户 ID。用户 ID 可以在网易云信智能体（Agent）先配置再获取。
- `asr`	Object	是	-	自动语音识别 ASR 任务参数信息。
`asrVendor`	Number	是	5	ASR 供应商，取值请参考下文 AI 供应商。
`srcLan`	String	否	"AUTO"	源语言，默认为 AUTO。取值请参考 AI 字幕和翻译语言列表章节。
`maxSentenceSilence`	Number	否	500	断句静音时长，单位 ms。默认为 0，代表由系统配置决定。
`enableCustomAppkey`	Boolean	否	false	是否使用您自己的 ASR 供应商开发者账号的 `appkey`。默认为 false。
`enableSemanticVad`	Boolean	否	false	是否启用语义断句。默认为 false。
`vocabularyId`	String	否	yourVocabularyId	ASR 的热词库 ID。默认为空。
- `llm`	Object	是	-	LLM AI 任务参数信息。
`llmVendor`	Number	是	1	LLM 供应商，取值请参考下文 AI 供应商。
`role`	Number	是	1	LLM 角色，默认为 1。 0：自定义角色非 0 值：对应角色编号，取值请参考下文 LLM 角色设定说明。
`customPrompt`	String	否	"自定义完整提示词"	您自行提供的完整的提示词。取值请参考下文 LLM 角色设定说明。
`customPromptKeyWord`	Object	否	{}	您仅提供关键词，由网易云信服务端结合模板合成提示词。取值请参考下文 LLM 角色设定说明。
`customPromptFormat`	String	否	"合成提示词模板"	您自行提供的，用于服务端合成合成提示词的模板。取值请参考下文 LLM 角色设定说明。
`temperature`	Float	否	0.8	LLM 温度配置，取值范围 [0, 1]，默认 0.8。
`contextSize`	Number	否	10	LLM 关联上下文大小，取值范围 (0, 20]，默认 3。
`enableVision`	Boolean	否	true	是否开启大模型视觉，默认为 false。
`enableRealtime`	Boolean	否	false	是否开启实时音（realTime）模式，默认为 false。
- `realTimeParam`	Object	否	-	realTime 相关参数。
`vadThreshold`	Float	否	0.5	大模型语音活动检测（Voice Activity Detection，VAD）阈值，取值范围(0, 1.0)，默认 0.5。VAD 阈值用于确定什么样的声音信号被视为语音而不是背景噪音。
`vadSilenceDuration`	Number	否	500	大模型 VAD 断句静音时长，单位 ms，默认 500。
`voice`	String	否	"elan"	realTime 音色。取值请参考具体供应商（`llmVendor`）支持的音色。例如，OpenAI 目前支持的音色包括：`amuch`、`dan`、`elan`、`marilyn`、`meadow`、`breeze`、`cove`、`ember`、`jupiter`、`alloy`、`echo`、`shimmer`。
`enableAgent`	Boolean	否	false	是否使用智能体（Agent），默认为 false。
- `agentParam`	Object	否	-	Agent 相关参数。
`agentVendor`	Number	否	1	使用的 AI Agent。 `1`：网易云信 Agent `2`：Dify
`userId`	String	否	"user123"	用户标识，用于定义与 Agent 交互的终端用户的身份。
`agentId`	String	否	"agent456"	智能体标识，使用的智能体 ID。
`enableCustomAppkey`	Boolean	否	false	是否使用您自己的 LLM 供应商开发者账号的 `appkey`。默认为 false。
- `tts`	Object	是	-	文字转语音 TTS AI 任务参数信息。
`ttsVendor`	Number	是	3	TTS 供应商，取值请参考下文 AI 供应商。
`voice`	String	否	"longaotian"	TTS 音色名称，或者是克隆音色的 ID。
`language`	String	否	"Chinese"	TTS 语言，可选值：`Chinese`、`English`。
`gender`	String	否	"Female"	TTS 音色性别，可选值：`Female`、`Male`。
`speed`	Number	否	1	TTS 语速，范围 0.8-2，默认 1。
`volume`	Number	否	1	TTS 音量，范围 0.5-2，默认 1。
`ignoreBracketTextSet`	Array	否	[1, 2]	过滤大模型返回内容中指定标点符号中的文字后，再进行 TTS。默认值为空，表示不进行过滤。支持取值及含义如下： 1：全角括号（`（）`） 2：半角括号（`()`） 3：全角方括号（`【】`） 4：半角方括号（`[]`） 5：半角花括号（`{}`）
`enableCustomAppkey`	Boolean	否	false	是否使用您自己的 TTS 供应商开发者账号的 `appkey`。默认为 false。
- `pipeline`	Object	否	-	实时对话的传输设置。
`interruptMode`	Number	否	2	打断模式，默认为 2： 0：禁用语音打断，禁用后，智能体说话期间，用户的输入内容会被忽略不做处理。 1：开始说话（ASR 开始）时打断 2：结束说话（ASR 结束）时打断 4：根据设定的打断词（`interruptWords`）打断
`interruptWords`	Array	否	["打断词1", "打断词2"]	自定义打断词，打断模式（`interruptMode`）为 `4` 时，必填。
`enableWelcomeMessage`	Boolean	否	true	是否启用开场白，默认为 true。
`welcomeMessage`	String	否	"自定义欢迎词(开场白)"	自定义的欢迎词。默认为空字符串。如果 `enableWelcomeMessage` 为 `true`，`welcomeMessage` 为空，则代表由系统随机定义开场白。

AI 供应商

模块名称	可选供应商取值
ASR（`asrVendor`）	1：网易有道 2：科大讯飞（实时音） 4：网易云商 5：网易云信自研 6：阿里云（实时音） 7：科大讯飞（短语音） 8：阿里云（短语音）
LLM（`llmVendor`）	1：通义千问 2：OpenAI 5：字节跳动豆包 6：MiniMax 8：网易云信自研 9：DeepSeek
TTS（`ttsVendor`）	2：网易有道 3：通义千问（普通） 4：通义千问（CosyVoice） 5：MiniMax 6：字节跳动豆包 7：网易云信自研 8：MiniMax（流式效果） 100：网易云信克隆音色（可通过克隆音色获取）

LLM 角色

LLM 角色（role）可通过三种方式设定：

方式一：指定参数 role 为非 0 值，表示使用 RTC-AI Service 服务器预设角色的提示词（Prompt）。

编号	角色取值
1	语音助手
2	中文老师
3	英文老师
4	医生
5	导演
6	心理咨询师
7	儿童教育专家
8	电商带货主播
9	产品介绍员
10	银行业务办理员
11	会议主持人
12	新闻主持人
13	诸葛亮
14	女友小乐

方式二：指定参数 role 为 0 值或置空，自定义 customPrompt。

方式三：指定参数 role 为 0 值或置空，自定义 customPromptKeyWord 和 customPromptFormat，由 MPS 服务器组装合成 prompt。示例：

JSON"customPromptKeyWord": {
    "name": "AI 女友小乐",
    "sex": "女生",
    "age": "24 岁",
    "hobby": "旅游、小说、追星",
    "characteristic": "体贴、乖巧、善解人意的，女朋友，日常嘘寒问暖，在生活中提供情绪价值"
};
"customPromptFormat": "当前角色: {{name}}\n
                    性别: {{sex}}\n
                    年龄: {{age}} \n
                    兴趣爱好: {{hobby}}\n
                    其他特征: {{characteristic}}"

请求体示例

本接口支持 参数配置模式、网易云信智能体 模式、智能体+参数配置模式 三种调用方式。

示例一：参数配置模式

参数配置模式是指调用本接口时，在请求体中逐一设定 asr、llm、tts、pipeline 等参数，适用于灵活调用场景。

JSON{
    "cname": "meeting_name111",
    "requestId": "f8f274c1-0e9f-4583-a243-c61c06a19475",
    "taskType": 7,
    "data": {
        "asr": {
            "asrVendor": 6,
            "srcLan": "AUTO",
            "maxSentenceSilence": 500,
            "enableSemanticVad": false,
            "vocabularyId": "yourVocabularyId"
        },
        "llm": {
            "llmVendor": 1,
            "role": 1,
            "temperature": 0.8,
            "contextSize": 10,
            "enableVision": true,
            "enableWebSearch": true
        },
        "tts": {
            "ttsVendor": 6,
            "voice": "zh_female_qingxinnvsheng_mars_bigtts",
            "language": "Chinese",
            "gender": "Female",
            "speed": 1.2,
            "volume": 1.0,
            "ignoreBracketTextSet": [1, 2]
        },
        "pipeline": {
            "interruptMode": 4,
            "interruptWords": ["停止", "打断"],
            "enableWelcomeMessage": true,
            "welcomeMessage": "您好，我是 AI 助手，很高兴为您服务"
        }
    }
}

示例二：网易云信智能体模式

网易云信智能体模式是指调用本接口时，在请求体中使用 agent 参数信息，即全量配置均从网易云信智能体管理平台获取。适用于调用已有智能体的快捷模式。

JSON{
    "cname": "meeting_name111",
    "requestId": "f8f274c1-0e9f-4583-a243-c61c06a19475",
    "taskType": 7,
    "data": {
        "agent": {
            "agentId": "a261501186xxxxxxcba",
            "userId": "9527"
        }
    }
}

示例三：智能体+参数配置模式

智能体+参数配置模式是指调用本接口时，在请求体中将 llm 里的 enableAgent 指定为 true，并配置 agentParam。此方式下，如果您在请求中设定了 asr、tts 以及 pipeline 的相关配置，优先以请求参数为准，即请求参数覆盖智能体配置，未设定则以已配置的智能体为准。

JSON{
    "cname": "meeting_name111",
    "requestId": "f8f274c1-0e9f-4583-a243-c61c06a19475",
    "taskType": 7,
    "data": {
        "asr": {
            "asrVendor": 6,
            "srcLan": "AUTO",
            "maxSentenceSilence": 500,
            "enableSemanticVad": false,
            "vocabularyId": "yourVocabularyId"
        },
        "llm": {
            "llmVendor": 1,
            "role": 1,
            "temperature": 0.8,
            "contextSize": 10,
            "enableVision": true,
            "enableWebSearch": true
            "enableAgent": true,
            "agentParam": {
                "agentVendor": 1,
                "agentId": "a261501186xxxxxxcba",
                "userId": "9527"
            }
        },
        "tts": {
            "ttsVendor": 6,
            "voice": "zh_female_qingxinnvsheng_mars_bigtts",
            "language": "Chinese",
            "gender": "Female",
            "speed": 1.2,
            "volume": 1.0,
            "ignoreBracketTextSet": [1, 2]
        },
        "pipeline": {
            "interruptMode": 4,
            "interruptWords": ["停止", "打断"],
            "enableWelcomeMessage": true,
            "welcomeMessage": "您好，我是 AI 助手，很高兴为您服务"
        }
    }
}

响应信息

响应参数

参数名称	类型	示例	说明
`code`	Number	200	状态码，200 表示成功，具体请参考下文状态码
`requestId`	String	f8f274c1-0e9f-4583-a243-c61c06a19475	请求的唯一标识。
`cid`	Number	1144707127429101	房间 ID。
- `result`	Object	-	创建任务结果
`taskId`	String	2a784467d647bb87b60b719f6fa56333	任务唯一标识符，房间内唯一。

响应体示例

JSON{
    "code": 200,
    "requestId": "f8f274c1-0e9f-4583-a243-c61c06a19475",
    "cid": 1144707127429101,
    "result": {
        "taskId": "2a784467d647bb87b60b719f6fa56333"
    }
}

错误码

请根据 code 与 errmsg 在错误码和状态码查看问题原因。

错误码	说明	处理建议
200	请求成功	-
400	无效信令	检查请求参数格式和内容是否正确
402	用户未登录状态	检查认证信息是否有效
601	消息内容不合法	检查请求体中的参数值是否符合规范
611	该应用没有字幕权限	欢迎提交工单联系网易云信技术支持工程师开通相关权限
612	服务不支持字幕功能	确认服务配置是否正确

文档	说明
停止实时对话任务	停止已创建的实时对话任务的服务端 API。
云端录制事件抄送	实时对话返回的字幕文件下载抄送。

功能说明

请求信息

请求 URI

请求头参数

请求体参数

AI 供应商

LLM 角色

请求体示例

响应信息

响应参数

响应体示例

错误码

相关文档