如何通过灵珠AI的API接入自己的应用程序

Rokid灵珠AI平台提供四种智能体集成方式：一、获取API凭证并调用鉴权接口获取Bearer Token；二、通过RESTful API直接调用/chat接口；三、使用CXR-SSDK集成至Android眼镜应用；四、配置Webhook接收异步事件。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您希望将 Rokid 灵珠 AI 平台创建的智能体能力集成到自有应用程序中，需通过其标准 API 接口完成调用。灵珠平台提供基于 RESTful 的 HTTP 接口，支持 JSON 格式通信，并要求使用 Bearer Token 进行身份鉴权。以下是具体接入方式：

一、获取 API 访问凭证

该步骤用于获得合法调用权限，确保请求被平台识别为已授权开发者行为。未配置有效凭证的请求将被拒绝。

1、登录灵珠平台（https://rizon.rokid.com/space/home）并进入「智能体管理」页面。

2、选择目标智能体，点击「发布设置」，在「API 调用」区域开启「启用 API 调用」开关。

3、点击「生成新密钥」，系统将生成一对 API Key 与 API Secret，请立即复制并安全保存；该密钥仅显示一次，丢失需重新生成。

4、使用 API Key 和 API Secret 调用平台鉴权接口（POST https://api.rizon.rokid.com/v1/auth/token），获取有效期为 24 小时的 Bearer Token。

二、构造智能体调用请求

此方法适用于轻量级集成场景，无需部署 SDK，直接通过 HTTP 请求触发智能体推理流程，适合 Web 后端或移动端原生网络模块调用。

1、准备请求头（Headers）：设置 Content-Type: application/json 与 Authorization: Bearer {token}。

2、构造请求体（Body）：JSON 格式，包含字段 "bot_id"（智能体唯一 ID，可在智能体详情页查看）、"input"（用户输入文本，如 "今天天气如何？"）及可选字段 "session_id"（用于多轮对话上下文维护）。

3、向接口地址 POST https://api.rizon.rokid.com/v1/bot/chat 发送请求。

4、解析响应：成功时返回 JSON，含 "output" 字段（智能体回复内容）与 "trace_id"（用于问题排查）。

三、使用 CXR-SSDK 集成至 Android 应用

该方式专为 Rokid Glasses 设备深度适配设计，支持语音唤醒、图像上传、多模态输入等端侧能力，适用于需与眼镜硬件联动的应用场景。

1、在 Android Studio 中导入 Rokid CXR-S SDK（需满足 minSdkVersion ≥ 28）。

2、在应用初始化阶段调用 CXRSDK.init(context, appId, appKey)，其中 appId 与 appKey 从灵珠平台「应用管理」中获取。

3、创建 BotClient 实例，传入智能体 ID 与已获取的 Bearer Token。

4、调用 botClient.sendText() 或 botClient.sendImage() 方法发送用户输入，结果通过回调函数接收。

5、在 AndroidManifest.xml 中声明必要权限：android.permission.CAMERA、android.permission.RECORD_AUDIO 及网络权限。

四、配置 Webhook 接收异步事件

当智能体执行耗时操作（如调用外部 OCR 服务或运行 Python 脚本）时，平台默认采用异步响应模式。本方法用于接收处理完成后的最终结果，避免客户端长时间阻塞等待。

1、在灵珠平台智能体「发布设置」中，启用「Webhook 模式」并填写您服务器的 HTTPS 回调地址。

2、确保您的服务端能接收 POST 请求，并验证请求头中的 X-Rizon-Signature 签名（使用 API Secret 计算 HMAC-SHA256）以确认来源可信。

3、平台将在智能体任务完成后，向该地址推送包含 "event_type"（如 "chat_completion"）、"output" 与 "request_id" 的 JSON 数据。

4、服务端解析后，可通过 WebSocket 或消息队列将结果推送给前端用户界面。