灵珠AI API接口调用与开发实战指南

在基于Rokid灵珠AI平台进行应用开发时，如何高效、安全地调用各类API，往往是决定项目成败的关键一环。无论是集成外部服务，还是调用平台自身的智能体能力，都离不开对HTTP节点、鉴权方式和数据格式的精准配置。下面，我们就来拆解四种核心的调用路径，帮你理清思路，避开那些常见的“坑”。

一、通过灵珠平台HTTP节点调用12306等第三方API

直接让客户端去调用第三方API？这通常会面临跨域限制和风控拦截的双重挑战。一个更稳妥的方案，是利用灵珠平台内置的HTTP节点。它本质上是一个云端袋里，帮你把调用逻辑托管在平台侧，统一管理请求头、参数拼接乃至错误重试策略。

具体操作起来并不复杂：在工作流编辑器中拖入“HTTP”节点，选择GET或POST方法，填入目标URL。关键在于鉴权——你需要在Headers里添加Authorization: Bearer {your_api_key}，而这个密钥需要提前在平台的“凭证管理”中绑定好。请求体通常选用JSON格式，动态填入参数。最后别忘了勾选“启用响应解析”，把返回数据里需要的字段（比如data.trains）映射成变量，这样后续节点就能直接引用了。

二、使用灵珠生成的智能体API供Android端SDK调用

当你完成一个智能体的开发并发布后，灵珠平台会自动为其生成一个专属的HTTPS API端点。这意味着，你的Android应用（特别是眼镜端应用）可以通过Rokid CXR-S SDK，直接与这个云端智能体对话。

首先，发布智能体后，记下它的API地址。接着，去“凭证管理”创建一个新的Token，拿到Access Key ID和Secret Access Key。在Android代码中，初始化RokidAgentClient，传入这三项信息。之后，无论是发送文本指令还是上传图片（需base64编码），调用sendMessage()方法即可。处理响应时，重点关注回调JSON中的output.text或output.image_url字段，它们就是你需要渲染到UI上的内容。

三、自定义SSE流式API接入私有大模型

对于一些对数据隐私、模型可控性要求极高的场景，你可能需要接入私有化部署的大模型。灵珠平台通过SSE（Server-Sent Events）协议提供了这种可能性。简单说，平台会把用户输入标准化后，推送到你的私有服务端点，并以流式方式接收返回结果。

接入的前提，是你的私有服务必须提供一个符合SSE规范的接口，响应头Content-Type需为text/event-stream，数据格式以data:开头。在灵珠平台的智能体设置中，找到“自定义模型”选项，填入你的SSE服务地址，并配置好必要的请求头（如Authorization）。剩下的关键两步是“入参映射”和“响应解析”：你需要告诉平台，如何将用户消息、历史上下文等组装成请求体；也需要指定从SSE返回的data:字段中，提取内容的JSON路径（例如choices.0.message.content）。

四、在工作流中调用灵珠内置工具节点实现免代码API编排

如果你觉得写代码调用API太麻烦，灵珠平台还准备了一组“开箱即用”的工具节点。像“日期解析”、“地理编码”、“文本摘要”这类常见功能，都被封装成了可视化的节点。你只需要像搭积木一样，在工作流中拖拽、连接它们，就能完成复杂的数据处理逻辑，实现真正的免代码API编排。

举个例子，想根据用户说的地址查询天气？可以先拖入一个“高德地图地理编码”工具节点，将用户输入的地址字符串映射到它的address参数上。为了提升鲁棒性，可以给它开启“自动重试”。节点执行成功后，会返回结构化的经纬度信息。这时，你可以连接一个“条件判断”节点，依据返回状态码分流。最后，将解析出的location.lng和location.lat作为变量，传入下一个HTTP节点，去调用天气查询API。整个过程清晰直观，无需编写一行底层代码。