需通过五种标准化接口实现灵珠ai与业务系统集成：一、restful api触发工作流并轮询结果；二、sse监听实时事件流；三、websocket建立双向长连接；四、mcp协议嵌套调用ai能力；五、webhook异步回调接收最终结果。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望将灵珠AI能力嵌入现有业务系统并实现端到端自动化执行，则需通过标准化接口完成平台与外部系统的双向通信与数据协同。以下是实现该目标的多种集成路径：
一、基于RESTful API的工作流触发与结果获取
该方式适用于已有后端服务且具备HTTP调用能力的场景，通过灵珠平台开放的RESTful接口发起工作流执行请求，并同步或异步接收结构化响应结果。
1、登录灵珠平台，在「项目设置」→「API管理」中启用工作流对外暴露开关，并复制生成的API密钥与工作流ID。
2、构造POST请求，目标URL为https://api.rizon.rokid.com/v1/workflows/{workflow_id}/run，Header中携带Authorization: Bearer {api_key}。
3、在Request Body中以JSON格式传入工作流定义的输入参数，例如：{"requirement": "生成端午节祝福文案", "amount": 0, "order_title": "节日文案服务"}。
4、接收返回的execution_id，后续可通过GET /v1/executions/{execution_id}轮询获取执行状态与最终输出。
二、基于SSE（Server-Sent Events）的实时事件流监听
该方式适用于需要持续接收工作流运行过程中的中间状态、日志或分段结果的场景，尤其适合长时任务或需前端实时反馈的交互式应用。
1、在灵珠平台工作流配置页勾选「启用SSE事件推送」，并指定事件类型过滤条件（如仅接收node_completed或output_ready）。
2、前端或服务端建立EventSource连接，目标地址为https://api.rizon.rokid.com/v1/workflows/{workflow_id}/events?token={api_key}。
3、监听message事件，解析返回的data字段，提取其中的node_name与output内容，例如：{"node_name":"OCR识别","output":"文字内容：'粽叶飘香迎端午...'"}。
4、根据事件内容动态更新UI状态或触发下游动作，无需主动轮询即可获得低延迟响应。
三、基于WebSocket的双向实时会话集成
该方式适用于需与灵珠工作流保持长连接、支持多轮上下文交互及设备端指令下发的场景，典型用于Rokid Glasses端语音+视觉混合任务链路。
1、在灵珠平台「设备接入」模块中创建WebSocket接入凭证，获取ws_endpoint与device_id绑定关系。
2、眼镜端SDK调用RokidWebSocket.connect(ws_endpoint, { auth_token: 'xxx', device_id: 'glasses_abc123' })建立持久连接。
3、发送初始化消息，包含工作流ID与初始输入，格式为：{"type":"start","workflow_id":"wf_poem_pay_001","input":{"requirement":"写一首七言绝句，主题是西湖夏荷"}}。
4、监听WebSocket的onmessage回调，处理平台返回的progress、output、error等类型消息，按需调用TTS播报或AR图层渲染。
四、基于MCP（模型上下文协议）的服务能力嵌套调用
该方式适用于需将灵珠平台封装的能力作为原子服务嵌入其他AI系统或自研Agent框架中，通过自然语言描述触发预设功能，不依赖具体接口格式。
1、在灵珠平台「插件中心」中发布已配置完成的工作流为MCP服务，设定语义标识符，例如："支付订单创建服务"。
2、在外部大模型系统中注册该MCP服务，声明其支持的输入槽位（如amount, title）与返回结构（如prepay_id, qr_code_url）。
3、当外部系统生成调用指令如请调用支付订单创建服务，金额5.99元，标题为‘诗词定制服务’时，自动解析参数并转发至灵珠平台。
4、接收结构化响应后，继续执行后续逻辑，例如将qr_code_url渲染至眼镜AR界面供用户扫码。
五、基于Webhook的异步结果回调集成
该方式适用于无法维持长连接、但需确保结果最终送达的后台系统，平台在工作流结束时主动向预设地址发起HTTP回调。
1、在灵珠平台工作流编辑页底部，点击「添加Webhook」，填写目标URL（如https://your-server.com/callback/poem）与验证Token。
2、保存后平台将在工作流执行完成时，以POST方式向该地址发送JSON数据，含execution_id、status、output等字段。
3、服务端校验Header中的X-Rokid-Signature签名，确认消息来源可信，防止伪造请求。
4、解析output字段内容，例如：{"poem": "苏堤柳绿映波光，断桥烟雨醉斜阳。...", "audio_url": "https://cdn.rokid.com/aud/20260519_xxx.mp3"}，存入数据库或推送给终端用户。
