灵珠ai平台api调用含四种方式：一、restful需https+bearer认证，json入参含base64图像；二、sse用于流式输出，参数走url查询；三、websocket需首帧认证及hmac签名；四、mcp通过自然语言指令触发能力，支持上下文嵌入。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在调用灵珠AI平台提供的API时遇到请求失败、返回空响应或参数校验错误等问题，则可能是由于接口入参格式不合规、认证信息缺失或通信协议未正确配置所致。以下是多种可立即验证与执行的API接口参数配置与调用方式：
一、RESTful API调用方式与核心参数
该方式适用于需要同步获取结构化响应的场景，如诗词识别结果回传、OCR文本提取、支付订单创建等。所有请求必须通过HTTPS发起，且需携带有效认证凭证。
1、在灵珠平台“智能体发布”页面获取API Key与Base URL，二者均不可硬编码于前端代码中，应通过服务端环境变量注入。
2、构造POST请求，Header中设置：Content-Type: application/json 与 Authorization: Bearer {your_api_key}。
3、Body中按智能体定义的入参结构提交JSON对象，例如含图片上传字段时，必须先将图像Base64编码为字符串，并以USER_INPUT_IMAGE为键名封装；若含文本输入，则使用str_USER_INPUT作为键名。
4、接收响应后，检查HTTP状态码是否为200，再解析JSON中的data字段，其内嵌result为业务结果，trace_id用于平台侧日志追溯。
二、Server-Sent Events（SSE）长连接调用方式
该方式适用于需持续接收流式输出的场景，如语音合成TTS逐字播报、多步骤工作流状态推送、实时渔情分析过程反馈等，可避免轮询开销并保障低延迟。
1、使用EventSource对象初始化连接，URL为平台生成的SSE Endpoint，格式为https://{base_url}/v1/workflow/{workflow_id}/stream。
2、连接建立后，客户端监听message事件，每条事件数据以data:前缀开头，内容为JSON字符串，需手动调用JSON.parse()解析。
3、发送初始参数时，须在URL Query中拼接input_image=base64_string或input_text=xxx，不支持Request Body。
4、当收到event: end事件时，表示工作流执行完成，应主动关闭EventSource连接。
三、WebSocket双向实时通信方式
该方式适用于眼镜端需与云端保持全双工交互的场景，如AR叠加内容动态更新、手势指令与视觉识别结果协同反馈、多模态会话上下文维持等。
1、从灵珠平台“设备管理”页获取WebSocket地址，格式为wss://{gateway_domain}/ws/v1/device/{device_id}，其中device_id由Rokid Glasses SDK初始化时上报并绑定。
2、建立连接后，首帧必须为认证帧，类型为auth，Payload包含api_key与timestamp（毫秒级），且需进行HMAC-SHA256签名验证。
3、后续消息以JSON格式发送，必含type字段（如camera_frame、voice_asr、ar_overlay），payload结构严格匹配所选智能体的节点定义。
4、云端响应帧中status为success时，data字段携带渲染指令或文本内容；若为error，则code字段标识错误类型（如INVALID_PAYLOAD、EXPIRED_TOKEN）。
四、MCP（模型上下文协议）自然语言能力调用方式
该方式适用于无需预定义接口契约、仅通过语义描述即可触发封装能力的场景，如“把这张图里的菜名翻译成英文”、“查一下这个插座支持的最大功率”等零代码集成需求。
1、在灵珠平台“能力中心”启用MCP服务，并确认目标能力已标记为public且处于active状态。
2、构造标准MCP请求体，顶层字段为request，值为自然语言指令字符串；附加字段context中可嵌入当前图像Base64、地理位置坐标、设备传感器读数等上下文数据。
3、向MCP网关地址发起POST请求，Header中设置X-MCP-Version: 1.0与Content-Type: application/mcp+json。
4、响应体中response字段为结构化结果，若含tool_calls数组，则表示AI已自动路由至对应工具节点，需按序执行其function.name与function.arguments。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
