2026-07-27

date: "2026-07-24"

实现数字人实时播报

本文档用于说明如何调用 AI Agent 相关后台接口，实现数字人实时播报。

与数字人视频通话不同，数字人播报是单向观看场景——即用户不和数字人进行互动，只是拉数字人播报内容进行观看。客户端只需要登录 RTC 房间并拉取数字人流，不需要采集或推送用户的音视频流。创建播报实例后，服务端可以通过 TTS 接口主动让数字人播报指定文本。

适用于数字人直播、新闻播报、活动主持和固定话术播报等场景。

与数字人视频通话的区别

对比项	数字人视频通话	数字人实时播报
交互方式	双向，用户说话后数字人回答	单向，用户仅观看数字人播报内容
适用场景	AI 互动、AI 客服、数字人老师	数字人直播、新闻播报
客户端是否需要采集用户音频	是	否
数字人驱动机制	收到用户音频后，LLM 输出回复，通过 TTS 驱动数字人	播报内容完全由服务端控制，通过 TTS 驱动数字人
创建实例接口	CreateDigitalHumanAgentInstance	CreateLiveDigitalHumanAgentInstance
是否需要 user_id、user_stream_id	是	否

前提条件

已在 ZEGO 控制台创建项目，并申请有效的 AppID 和 ServerSecret（用于服务端 API 签名与 RTC Token04 生成），详情请参考控制台 - 项目信息。
已在 ZEGO 控制台开通了实时互动 AI Agent 服务
已获取了 LLM 和 TTS 相关配置信息。，详细请参考控制台 - 实时互动 AI Agent。
已获取有效的 digital_human_id（测试时可使用公共 ID：c4b56d5c-db98-4d91-86d4-5a97b507da97）。

说明

在接入测试期间(AI Agent 服务开通 2 周内)，可以将 LLM 和 TTS 的鉴权参数设置为 "zego_test" 即可使用相关服务。具体鉴权参数配置请参考注册智能体 > BODY 参数说明。

同时可自行采购ZEGO支持LLM、TTS服务并获取鉴权信息使用。也可通过联系ZEGO商务直接采购TTS服务。

示例代码

以下是接入实时互动 AI Agent API 的业务后台示例代码，您可以参考示例代码来实现自己的业务逻辑。

业务后台示例代码

包含最基本的获取 ZEGO Token、注册智能体、创建智能体实例、删除智能体实例等能力。

以下是客户端示例代码，您可以参考示例代码来实现自己的业务逻辑。

Android 客户端示例代码

包含最基本的登录、推流、拉流、退出房间等能力。

iOS 客户端示例代码

包含最基本的登录、推流、拉流、退出房间等能力。

Web 客户端示例代码

包含最基本的登录、推流、拉流、退出房间等能力。

Flutter 客户端示例代码

包含最基本的登录、推流、拉流、退出房间等能力。

整体业务流程

服务端，跑通业务后台示例代码，部署好业务后台
- 接入实时互动 AI Agent API 管理智能体。

客户端，参考 Android 端快速开始、 iOS 端快速开始或 Web 端快速开始文档跑通客户端示例代码
- 通过业务后台创建和管理播报数字人实例。
- 集成 ZEGO Express SDK 完成进房和拉流。
- Android/iOS 集成数字人 SDK 完成数字人渲染。
- 按需调用 TTS 接口让数字人主动播报。

完成以上两个步骤后即可实现观看数字人播报。

核心能力实现

注册智能体

注册智能体用于设定智能体基础配置，包括智能体名称、LLM、TTS、ASR等相关配置。注册后可以将该智能体作为模板创建多个实例与多个真实用户进行互动。

通常智能体是相对比较固定的，一旦设定好智能体的相关参数（人设形象）就不会经常改动。所以建议按照业务流程需要在适当时机注册智能体即可。智能体注册后不会自动销毁和回收，创建智能体实例后即可与该智能体进行语音交互。

说明

一个智能体只能注册一次（同一个ID），如果重复注册会返回错误码 410001008。

以下是调用注册智能体接口的示例：

Server(NodeJS)

// 请将以下示例中的 LLM 和 TTS 的 ApiKey、appid、token 等鉴权参数换成你实际的鉴权参数。  
async registerAgent(agentId: string, agentName: string) {  
    // 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=RegisterAgent  
    const action = 'RegisterAgent';  
    const body = {  
        AgentId: agentId,  
        Name: agentName,  
        LLM: {  
            Url: "https://ark.cn-beijing.volces.com/api/v3/chat/completions",  
            ApiKey: "zego_test",  
            Model: "doubao-1-5-pro-32k-250115",  
            SystemPrompt: "你是一个智能体，请根据用户的问题回答。"  
        },  
        TTS: {  
            Vendor: "ByteDance",  
            Params: {  
                "app": {  
                    "appid": "zego_test",  
                    "token": "zego_test",  
                    "cluster": "volcano_tts"  
                },  
                "audio": {  
                    "voice_type": "zh_female_wanwanxiaohe_moon_bigtts"  
                }  
            }  
        }  
    };  
    // sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest<any>(action, body);  
}

Server(NodeJS)

// 请将以下示例中的 LLM 和 TTS 的 ApiKey、appid、token 等鉴权参数换成你实际的鉴权参数。  
async registerAgent(agentId: string, agentName: string) {  
    // 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=RegisterAgent  
    const action = 'RegisterAgent';  
    const body = {  
        AgentId: agentId,  
        Name: agentName,  
        LLM: {  
            Url: "https://ark.cn-beijing.volces.com/api/v3/chat/completions",  
            ApiKey: "zego_test",  
            Model: "doubao-1-5-pro-32k-250115",  
            SystemPrompt: "你是一个智能体，请根据用户的问题回答。"  
        },  
        TTS: {  
            Vendor: "ByteDance",  
            Params: {  
                "app": {  
                    "appid": "zego_test",  
                    "token": "zego_test",  
                    "cluster": "volcano_tts"  
                },  
                "audio": {  
                    "voice_type": "zh_female_wanwanxiaohe_moon_bigtts"  
                }  
            }  
        }  
    };  
    // sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest<any>(action, body);  
}

注意

请确保 LLM 所有参数都按照 LLM 服务提供商官方文档填写正确，否则您可能无法看到智能体回答的文本内容也无法听到智能体输出语音。
请确保 TTS 所有参数都按照 TTS 服务提供商官方文档填写正确，否则您可能可以看到智能体回答的文本内容却无法听到智能体输出语音。
如遇智能体无法输出文本内容或语音，请先检查 LLM 和 TTS 参数配置是否完全正确，或参考获取智能体服务状态 - 监听服务端异常事件确定具体的问题。

获取 RTC Token

客户端登录 RTC 房间需要 Token，可通过业务后台基于 AppID 和 ServerSecret 生成 Token04。

GET /api/zego-token?user_id=<user_id>

GET /api/zego-token?user_id=<user_id>

响应示例：

{  
  "code": 0,  
  "token": "eyJhbGciOi..."  
}

{  
  "code": 0,  
  "token": "eyJhbGciOi..."  
}

创建播报数字人智能体实例

可以用已注册的智能体为模板创建播报数字人智能体实例。与数字人视频通话不同，播报数字人只需要加入 RTC 房间并推送数字人流，不需要接收真实用户的流，因此调用创建接口时不需要传 UserId 和 UserStreamId。

客户端调用业务后台的 POST /api/start-live-digital-human，RTC 模式下请求体示例如下：

{  
    "digital_human_id": "digital_human_id",  
    "config_id": "mobile",  
    "room_id": "room_id"  
}

{  
    "digital_human_id": "digital_human_id",  
    "config_id": "mobile",  
    "room_id": "room_id"  
}

业务后台收到请求后，调用 CreateLiveDigitalHumanAgentInstance 创建实例，并将 AgentInstanceId、AgentStreamId、AgentUserId 和 DigitalHumanConfig 转换后返回给客户端。客户端保存 AgentInstanceId，后续用于调用 SendAgentInstanceTTS 和删除实例。

以下是调用创建播报数字人智能体实例接口的示例：

说明

RTC 和 CDN 两个参数二选一，如果都设置则以 CDN 为准。

Server(NodeJS) — RTC 模式

async createLiveDigitalHumanAgentInstance(agentId: string, rtcInfo: RtcInfo, digitalHuman: DigitalHumanInfo) {  
    // 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=CreateLiveDigitalHumanAgentInstance  
    const action = 'CreateLiveDigitalHumanAgentInstance';  
    const body = {  
        AgentId: agentId,  
        RTC: rtcInfo, // RTC 模式  
        DigitalHuman: digitalHuman, // 测试时可使用公共 ID ：c4b56d5c-db98-4d91-86d4-5a97b507da97  
    };  
    const result = await this.sendRequest<any>(action, body);  
    return {  
        code: 0,  
        message: 'success',  
        agent_instance_id: result.AgentInstanceId,  
        agent_stream_id: result.AgentStreamId,  
        agent_user_id: result.AgentUserId,  
        digital_human_config: result.DigitalHumanConfig  
    };  
}

async createLiveDigitalHumanAgentInstance(agentId: string, rtcInfo: RtcInfo, digitalHuman: DigitalHumanInfo) {  
    // 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=CreateLiveDigitalHumanAgentInstance  
    const action = 'CreateLiveDigitalHumanAgentInstance';  
    const body = {  
        AgentId: agentId,  
        RTC: rtcInfo, // RTC 模式  
        DigitalHuman: digitalHuman, // 测试时可使用公共 ID ：c4b56d5c-db98-4d91-86d4-5a97b507da97  
    };  
    const result = await this.sendRequest<any>(action, body);  
    return {  
        code: 0,  
        message: 'success',  
        agent_instance_id: result.AgentInstanceId,  
        agent_stream_id: result.AgentStreamId,  
        agent_user_id: result.AgentUserId,  
        digital_human_config: result.DigitalHumanConfig  
    };  
}

注意

默认情况下一个账号下最多同时存在 10 个数字人智能体实例，超过限制后创建实例会失败，如需调整请联系 ZEGO 商务。

主动调用 TTS

创建播报数字人实例后，业务后台可以调用 SendAgentInstanceTTS 主动发送播报文本。

Server(NodeJS)

async sendAgentInstanceTTS(agentInstanceId: string, text: string) {  
    const action = 'SendAgentInstanceTTS';  
    const body = {  
        AgentInstanceId: agentInstanceId,  
        Text: text  
    };  
    return this.sendRequest<any>(action, body);  
}

Server(NodeJS)

async sendAgentInstanceTTS(agentInstanceId: string, text: string) {  
    const action = 'SendAgentInstanceTTS';  
    const body = {  
        AgentInstanceId: agentInstanceId,  
        Text: text  
    };  
    return this.sendRequest<any>(action, body);  
}

如果业务后台对外封装 quick-start server 接口，可使用：

POST /api/send-agent-instance-tts

Content-Type: application/json

Content-Type: application/json

请求示例：

{  
  "agent_instance_id": "1912124734317838336",  
  "text": "尊敬的开发者你好，欢迎使用 ZEGO RTC 共建实时互动世界。"  
}

{  
  "agent_instance_id": "1912124734317838336",  
  "text": "尊敬的开发者你好，欢迎使用 ZEGO RTC 共建实时互动世界。"  
}

说明

Text 最大长度不超过 300 个字符。
可选参数：AddHistory、Priority、SamePriorityOption，详见主动调用 TTS 和 SendAgentInstanceTTS。
实例默认空闲 900 秒未调 SendAgentInstanceTTS 自动销毁。长直播可通过 AdvancedConfig.MaxIdleTime 调整（30~86400 秒）。

停止播报并删除实例

播报结束后，业务后台调用 POST /api/stop 停止并删除播报实例，传入 agent_instance_id。删除后数字人会自动退出房间并停止推流。

{  
  "agent_instance_id": "1912124734317838336"  
}

{  
  "agent_instance_id": "1912124734317838336"  
}

说明

关于通用的删除智能体实例接口，请参考下方删除智能体实例步骤。

展示用户与智能体状态

如需查看用户与智能体状态，请参考展示用户与智能体状态。

播报数字人的状态说明：

空闲中：数字人实例已创建成功，等待服务端输入驱动内容。
说话中：数字人已接收来自服务端的驱动内容并进行实时播报，播报结束后自动切换回「空闲中」。

集成客户端 SDK

请参考以下文档完成客户端的集成开发：

Android

快速开始

iOS

快速开始

Web

快速开始

恭喜您🎉！完成这一步骤后，您已经成功集成客户端 SDK 并可以观看数字人播报，也可以通过 TTS 接口主动触发数字人播报。

删除智能体实例

删除智能体实例后，播报数字人会自动退出房间并停止推流。客户端停止拉流并退出房间后，一次完整的播报就结束了。

以下是调用删除智能体实例接口的示例：

Server(NodeJS)

async deleteAgentInstance(agentInstanceId: string) {  
    // 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=DeleteAgentInstance  
    const action = 'DeleteAgentInstance';  
    const body = {  
        AgentInstanceId: agentInstanceId  
    };  
    // sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest(action, body);  
}

Server(NodeJS)

async deleteAgentInstance(agentInstanceId: string) {  
    // 请求接口：https://aigc-aiagent-api.zegotech.cn?Action=DeleteAgentInstance  
    const action = 'DeleteAgentInstance';  
    const body = {  
        AgentInstanceId: agentInstanceId  
    };  
    // sendRequest 方法封装了请求的 URL 和公共参数。详情参考：/aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest(action, body);  
}

以上就是您实现数字人实时播报的完整核心流程。

监听回调

注意

由于 LLM 和 TTS 等参数比较多且复杂，在接入测试过程中容易因为参数配置错误导致的智能体不回答或者不说话等各种异常问题。我们强烈建议您在接入测试过程中监听回调，并根据回调信息快速排查问题。

接收回调

点击查看监听回调指引。监听回调中 Event 为 Exception 的事件。通过 Data.Code 和 Data.Message 可以快速定位问题。

异常错误码

点击查看异常错误码列表。

播报排查清单

排查指引

画面静止：检查 digital_human_config 是否有效、agent_stream_id 是否正确、是否在 startPlayingStream 前开启了自定义渲染（Android/iOS）、是否将视频帧和 SEI 数据传给了数字人 SDK（Android/iOS）。
TTS 不播报：检查 SendAgentInstanceTTS 返回 Code 是否为 0、检查 MaxIdleTime 是否过期、检查 DisableTTS 是否被设置。
创建实例失败：检查 digital_human_id 是否有效、AppID 和 ServerSecret 是否正确。

2026-07-27

date: "2026-07-24"

快速发起语音通话

实现数字人视频通话

数字人介绍

实现数字人实时播报

与数字人视频通话的区别

前提条件

示例代码

整体业务流程

核心能力实现

注册智能体

Server(NodeJS)

获取 RTC Token

创建播报数字人智能体实例

Server(NodeJS) — RTC 模式

主动调用 TTS

Server(NodeJS)

停止播报并删除实例

展示用户与智能体状态

集成客户端 SDK

删除智能体实例

Server(NodeJS)

监听回调

播报排查清单