本文面向主要服务于非中国大陆地区用户的 AI 硬件智能体项目，说明从控制台开通、智能体创建、服务端 API 域名选择到上线检查的推荐做法。

适用场景

当业务用户主要位于海外，或产品需要在海外区域提供更稳定的 AI 智能体体验时，建议按海外接入方式配置。典型场景包括：

• 海外智能硬件、AI 玩具、陪伴机器人。
• 面向北美、南美、欧洲或亚太市场的 App 内 AI 伙伴。
• 需要通过嵌入式 SDK 或 WebSocket 接入海外业务。

海外接入的核心原则是：音视频通话 2.0 服务区域、智能体所在数据中心、服务端 API Endpoint 三者保持一致或就近选择，避免控制台资源、智能体资源和接口域名跨区域混用。

接入前置条件

接入前请先完成以下准备：

1. 在 网易云信控制台 创建应用，获取应用的 AppKey。
2. 联系您的网易云信商务经理，为您的应用开通 AI 硬件智能体 服务，并根据您的产品目标市场选择中国大陆或海外数据中心。
3. 在 网易云信智能体管理平台 选择同一个 AppKey 创建智能体。详细步骤请参考 配置智能体。

智能体数据中心选择

在网易云信智能体管理平台创建智能体时，海外业务建议选择以下数据中心之一：

• 新加坡数据中心：适合亚太区域用户，通常作为海外用户默认选择。

• 美国数据中心：适合北美、南美、欧洲用户。

  

创建智能体时，先选择正确的 AppKey，再创建或复制智能体。创建表单中建议同步完成以下配置：

• 智能体名称和角色设定。
• 基础模型配置，包括 LLM、TTS、ASR。
• Pipeline 配置，包括打断策略、开场白、休眠设置、回声消除、AI 降噪、声纹识别、回调通知等。
• Tools/MCP 扩展能力。
• Agent 模式、知识库、情绪与状态配置。

AI 硬件智能体对话体验之前，还需要在平台中完成用户管理与设备绑定。一个设备需要唯一绑定一个用户和一个智能体；绑定后再通过激活授权码 License 接口为设备下发授权凭证。

服务端 API 域名选择

服务端调用 AI 硬件智能体 API 时，应根据智能体数据中心或目标用户区域选择 Endpoint。

业务/数据中心选择	推荐服务端 API 域名	说明
中国大陆	https://rtc-agent.yunxinapi.com	默认配置
新加坡数据中心/亚太区域	https://rtc-agent-ap.yunxinapi.com	海外用户默认域名
美国数据中心/欧美区域	https://rtc-agent-us.yunxinapi.com	北美、南美、欧洲专用域名
多区域或不确定区域	https://rtc-agent-g.yunxinapi.com	全球智能路由域名，不限调用区域

推荐做法：

• 新加坡数据中心创建的智能体，服务端优先使用 https://rtc-agent-ap.yunxinapi.com。
• 美国数据中心创建的智能体，服务端优先使用 https://rtc-agent-us.yunxinapi.com。
• 不建议海外业务继续使用中国大陆默认域名 https://rtc-agent.yunxinapi.com。
• 若业务覆盖多个海外区域且暂时无法拆分，可以评估使用全球智能路由域名 https://rtc-agent-g.yunxinapi.com。

完整请求 URI 由“服务接入地址 + 接口路径 + 路径参数/查询参数”组成。例如：

texthttps://rtc-agent-ap.yunxinapi.com/v1/agent
https://rtc-agent-us.yunxinapi.com/v1/agent

服务端鉴权与请求规范

所有服务端 API 请求都需要携带公共鉴权 Header：

Header	必选	说明
AppKey	是	网易云信控制台获取的应用标识
Nonce	是	随机数，最大长度 128 个字符
CurTime	是	当前 UTC 秒级时间戳
CheckSum	是	SHA1(AppSecret + Nonce + CurTime) 的小写十六进制结果

注意事项：

• CheckSum 有效期为 5 分钟，建议每次请求重新生成。
• 服务端机器需要开启 NTP 等时间同步能力，避免 CurTime 偏差导致 401。
• AppSecret 只能保存在应用服务端，不能下发到客户端、设备端或前端代码。
• 请求体使用 JSON，编码为 UTF-8，Content-Type 为 application/json。

推荐接入流程

1. 确认目标市场：亚太优先新加坡数据中心，欧美优先美国数据中心。
2. 在控制台创建应用并联系您的网易云信商务经理开通 AI 硬件智能体 海外服务。
3. 登录智能体管理平台，选择对应 AppKey。
4. 在目标数据中心创建智能体，并完成模型、音色、ASR、Pipeline、知识库等配置。
5. 创建测试用户，使用平台对话能力验证智能体效果。
6. 如接入嵌入式设备，完成设备绑定并调用 License 接口下发授权凭证。
7. 服务端按数据中心配置 API Endpoint，并完成 Header 鉴权。
8. 客户端或设备端接入嵌入式 SDK 或 WebSocket。

上线前检查清单

• AI 硬件智能体服务区域已选择海外。
• 智能体创建在新加坡或美国数据中心。
• 服务端 API Endpoint 与智能体数据中心匹配。
• AppKey、智能体 ID、用户 ID、设备 ID 的归属一致。
• AppSecret 未出现在客户端、设备端、Web 前端或日志中。
• 服务端时间同步正常，CheckSum 不复用过期值。
• 正式环境已切换为安全模式并完成 Token 鉴权。

常见问题

海外业务可以使用中国大陆默认域名吗？

不建议。海外业务应根据目标区域选择 rtc-agent-ap、rtc-agent-us 或全球智能路由域名。继续使用中国大陆默认域名可能增加跨区域访问链路复杂度，也不利于故障定位。

新加坡和美国数据中心如何选择？

如果用户主要在亚太区域，优先选择新加坡数据中心；如果用户主要在北美、南美或欧洲，优先选择美国数据中心。若业务天然覆盖多个区域，可在架构上按区域拆分应用或智能体，并为每个区域配置对应 Endpoint。

为什么服务端 API 返回 401？

优先检查以下内容：

• AppKey 是否属于当前应用。
• AppSecret 是否正确。
• Nonce、CurTime、CheckSum 是否每次请求重新生成。
• 服务端时间是否与标准时间同步。
• 请求是否打到了正确的数据中心 Endpoint。

设备已经绑定，为什么无法正常对话？

请依次确认：

• 设备 ID 是否绑定到正确用户和智能体。
• 是否已通过激活授权码 License 接口下发授权。
• 嵌入式 SDK 或 WebSocket 接入参数是否使用了正确的 AppKey、智能体 ID、用户 ID。
• 智能体是否已完成模型、ASR、TTS、Pipeline 等必要配置。