猎户星空机器人 API 完整参考手册

本手册整合猎户星空机器人三层 API 能力（本地 APK/OPK 端 + 服务端 API + NLP 配置），按功能维度整理，供开发人员快速查阅。

一、API 能力全景

猎户星空机器人提供三层开发接入方式：

层级	接入方式	说明
本地端 APK	Android 原生 SDK	使用 Java/Kotlin 开发，直接调用 RobotOS SDK
本地端 OPK	React Native 插件	使用 JavaScript 开发，通过 orionos-eve-core 库
服务端 API	HTTPS RESTful API	远程控制机器人，域名 openapi.orionstar.com
NLP 配置	开发者平台配置	在 console.orionbase.cn 配置语音交互规则

二、服务端 API（远程控制）

基础域名：https://openapi.orionstar.com 协议：HTTPS RESTful 鉴权方式：Bearer Token（通过 appId + appSecret 获取）

2.1 鉴权

方法	路径	说明
POST	`/auth/token`	获取访问令牌（使用 appId + appSecret）

2.2 企业信息

方法	路径	说明
GET	`/enterprise/info`	获取企业信息
GET	`/enterprise/robot/list`	获取企业下所有机器人列表

2.3 企业 SSO 免登录

方法	路径	说明
POST	`/enterprise/sso/create`	创建 SSO 登录链接
POST	`/enterprise/sso/verify`	验证 SSO Token
POST	`/enterprise/sso/logout`	注销 SSO 会话

2.4 企业人员管理

方法	路径	说明
POST	`/enterprise/person/create`	创建人员（含人脸图片）
POST	`/enterprise/person/update`	更新人员信息
POST	`/enterprise/person/delete`	删除人员
POST	`/enterprise/person/search`	人脸识别搜索

2.5 企业访客邀约

方法	路径	说明
POST	`/enterprise/visitor/invite`	创建访客邀约
GET	`/enterprise/visitor/list`	获取访客列表

2.6 机器人信息

方法	路径	说明
GET	`/robot/info`	获取单台机器人详情（SN、在线状态、电量、位置等）
GET	`/robot/status`	获取机器人实时状态
GET	`/robot/list`	获取机器人列表
POST	`/robot/config/get`	获取机器人层级配置
POST	`/robot/config/set`	设置机器人层级配置

2.7 机器人地图信息

方法	路径	说明
GET	`/robot/map/list`	获取机器人地图列表
GET	`/robot/map/info`	获取地图详情（含位置点）
GET	`/robot/map/current`	获取当前使用地图

2.8 机器人控制（12 个接口）

核心远程控制能力，可通过服务端直接操控机器人行为。

方法	路径	说明
POST	`/robot/control/navigate`	远程导航到指定位置点
POST	`/robot/control/navigate/stop`	停止导航
POST	`/robot/control/tts`	远程 TTS 语音播报
POST	`/robot/control/tts/stop`	停止 TTS
POST	`/robot/control/voice`	远程语音指令（模拟 ASR 输入）
POST	`/robot/control/mode`	切换工作模式（接待/巡逻/静默等）
POST	`/robot/control/sleep`	休眠
POST	`/robot/control/wakeup`	唤醒
POST	`/robot/control/reboot`	重启
POST	`/robot/control/shutdown`	关机
POST	`/robot/control/charge`	回充
POST	`/robot/control/charge/leave`	脱离充电桩

2.9 机器人任务

方法	路径	说明
POST	`/robot/task/create`	创建任务（招财豹/豹小递/豹厂通）
GET	`/robot/task/list`	获取任务列表
GET	`/robot/task/info`	获取任务详情
POST	`/robot/task/cancel`	取消任务

2.10 QA 问答管理

企业级 QA

方法	路径	说明
POST	`/qa/enterprise/create`	创建企业级 QA
POST	`/qa/enterprise/update`	更新企业级 QA
POST	`/qa/enterprise/delete`	删除企业级 QA
GET	`/qa/enterprise/list`	获取企业级 QA 列表

设备级 QA

方法	路径	说明
POST	`/qa/device/create`	创建设备级 QA
POST	`/qa/device/update`	更新设备级 QA
POST	`/qa/device/delete`	删除设备级 QA
GET	`/qa/device/list`	获取设备级 QA 列表

2.11 统计数据

招财豹统计：迎宾次数、互动时长、客流分析等
豹小秘统计：接待次数、导航次数、语音交互次数等
共 15 个 统计接口

2.12 事件回调

回调类型	说明
任务事件回调	任务开始/完成/失败等事件推送
预警通知回调	设备异常、电量低等预警推送

三、本地端 APK 原生开发 API

开发语言：Java / Kotlin 接入方式：引入 RobotOS SDK（AAR 包）需在 Manifest 中声明权限和服务通过 Server 连接、状态监听、reqId 管理调用

3.1 SDK 接入

基于 Android，引入 RobotOS SDK（AAR 包）
需在 Manifest 中声明权限和服务
通过 Server 连接、状态监听、reqId 管理调用

3.2 视觉能力 API（PersonApi）

API	说明
`PersonApi.detectFace()`	人脸检测
`PersonApi.registerFace()`	人脸注册
`PersonApi.recognizeFace()`	人脸识别
`PersonApi.switchCamera()`	切换摄像头（前/后/广角）
`SurfaceShareApi`	摄像头数据流共享（获取 YUV 原始数据）

3.3 基础运动 API

API	说明
`RobotApi.goForward(speed)`	前进（线速度 0~1.2 m/s）
`RobotApi.goBackward(speed)`	后退（无避障！）
`RobotApi.turnLeft(angularSpeed)`	左转（角速度 0~2.2 rad/s）
`RobotApi.turnRight(angularSpeed)`	右转
`RobotApi.stopMove()`	停止运动
`RobotApi.setLinearVelocity(v)`	设置线速度
`RobotApi.setAngularVelocity(w)`	设置角速度
`RobotApi.controlHead(horizontalAngle, verticalAngle)`	控制云台头部

3.4 地图与定位 API

API	说明
`RobotApi.isRobotEstimate()`	是否已定位
`RobotApi.getPosition()`	获取当前坐标 `{x, y, theta}`
`RobotApi.getMapName()`	获取当前地图名
`RobotApi.getPlace(placeName)`	获取位置点坐标
`RobotApi.getPlaceList()`	获取所有位置点列表
`RobotApi.switchMap(mapName)`	切换地图
`RobotApi.setFixedEstimate(pose)`	固定位姿定位 `{px, py, theta}`
`RobotApi.getMultiFloorConfigAndCommonPose()`	获取多楼层配置和点位

3.5 导航 API

API	说明
`RobotApi.startNavigation(destination)`	导航到指定位置（7 种重载）

导航参数：

destination - 目标点名称
linearSpeed - 线速度
angularSpeed - 角速度
arrivalRange - 到达范围
timeout - 超时时间
支持加减速模式

导航状态码：

状态码	说明
32730001	开始导航
32730004	避障中
32730011	堵死
32730009	定位丢失

导航结果码：

结果码	说明
32610007	到达目的地
-32620001	未定位
-32620009	路径规划失败

3.6 梯控导航 API（跨楼层）

API	说明
`RobotApi.startElevatorNavigation(floorIndex, destination)`	乘电梯导航

梯控状态码：

状态码	说明
32750004	到达电梯门
32750005	进入电梯
32750009	离开电梯

3.7 过闸机导航 API

闸机路径判断与通过流程

3.8 基础场景 API

场景	说明
引领模式	人跟机器人走
焦点跟随	机器人视线追踪人脸
唤醒	检测到人后唤醒交互

3.9 语音 API

功能模块	说明
`SkillApi`	场景管理（注册/切换/退出语音场景）
`SkillCallback`	语音回调（ASR 结果、NLP 解析、唤醒事件等）
TTS 播放	普通/流式播放
拾音模式	单次/持续识别
NLP 处理	意图识别结果解析
音频采集	原始音频流获取
Text 转 MP3	文本转语音文件

3.10 语音大模型流式数据

ChatStreamInterface 结构：

字段	说明
`sid`	会话 ID
`idx`	消息序号
`content`	文本内容
`tts`	TTS 音频数据
`sender`	发送者
`extra`	扩展字段

支持流式接收和关闭控制

3.11 电量控制 API

API	说明
`RobotApi.getBatteryLevel()`	获取电量（1-100）
`RobotApi.startCharge()`	自动回充
`RobotApi.stopCharge()`	离桩
`RobotApi.disableSystemCharge()`	禁用系统自动充电

3.12 多机协作 API

ESP32 模块通信
MultiRobotStatus 数据结构（多机状态同步）

3.13 电动门控制 API

两种控制方式（自动/手动）
Door1-4 独立控制
门状态查询

3.14 系统功能 API

功能	说明
状态监控	获取系统运行状态
灯效控制	底盘灯带/按钮灯
设备信息	SN 号、版本号
禁用系统功能	关闭默认行为
休眠控制	控制机器人休眠/唤醒
安装 APK	远程安装应用

四、本地端 OPK 插件开发 API

开发语言：JavaScript（React Native）核心库：orionos-eve-core

4.1 功能组件

4.1.1 导航组件 NavigationComponent

参数：

参数	说明	默认值
`destination`	目标位置点（必填）	-
`coordinate_deviation`	到达范围	0.5m
线速度	移动速度	0.1-1.2 m/s
角速度	转弯速度	0.2-1.8 rad/s
避障距离	检测障碍物距离	-
超时时间	导航超时	-

状态事件码： 开始导航、避障、堵死、定位丢失等

结果事件码： 到达、未定位、路径失败、目标不存在等

4.1.2 巡逻组件 CruiseComponent

参数：

参数	说明
巡逻路线	JSON 数组，至少 2 个点
堵死超时	堵死后等待超时时间
起始点	巡逻起始位置

支持多点循环巡逻

4.1.3 头部控制 HeadTurnComponent

参数	范围
水平角度	-80° ~ 80°
垂直角度	50° ~ 95°

4.1.4 人脸识别组件（6 个）

组件	说明
`WakeupAndPreWakeupStartCheckComponent`	唤醒/预唤醒检测
`PersonAppearComponent`	按条件找人
`PersonDisappearComponent`	人丢失检测
`RegisterComponent`	人脸注册
`RecognizeComponent`	查询注册信息
`ReceptionRegisterCameraView`	注册预览

4.1.5 引领追踪组件（5 个）

组件	说明
`SoundLocalizationComponent`	声源定位转向
`FaceTrackSoundLocalizationComponent`	人脸追踪 + 拾音
`StandardFaceTrackComponent`	自动追踪最近人脸
`FaceTrackComponent`	追踪指定人
`LeadingTrackComponent`	引领（人跟机器人走）

4.1.6 充电组件

组件	说明
`ChargeStartComponent`	自动回充
`LeavePileComponent`	脱离充电桩

4.1.7 梯控组件

组件	说明
`NavigationElevatorComponent`	导航乘梯（跨楼层）
`ChargeElevatorComponent`	充电乘梯

4.2 基础接口

4.2.1 地图与位置（11 个 API）

API	说明
`RobotApi.isRobotEstimate()`	是否已定位
`RobotApi.getPosition()`	获取当前坐标
`RobotApi.getMapName()`	获取当前地图名
`RobotApi.getPlace()`	获取位置点坐标
`RobotApi.getPlaceList()`	获取所有位置点列表
`RobotApi.getPlaceListWithName()`	按名称获取位置点列表
`RobotApi.resumeSpecialPlaceTheta()`	恢复特殊位置点角度
`RobotApi.switchMap()`	切换地图
`RobotApi.setFixedEstimate()`	固定位姿定位
`locationEstimateUtil.havePlace()`	判断位置点是否存在
`locationEstimateUtil.isInPlace()`	判断是否在某位置点范围内

4.2.2 运动控制

API	说明
`RobotApi.motionArcWithObstacles(lineSpeed, angularSpeed)`	弧线运动（带避障）

线速度范围：-1.2 ~ 1.2 m/s
角速度范围：-2.2 ~ 2.2 rad/s

4.2.3 电源管理（5 个 API）

API	说明
`RobotApi.getBatteryLevel()`	获取电量百分比
`RobotApi.getBatteryTimeRemaining()`	获取剩余使用时间
`RobotApi.getChargeTimeRemaining()`	获取剩余充电时间
`RobotSettingApi.isCharging()`	是否正在充电
`SettingsUtil.isCharging()`	是否正在充电（工具类）

4.2.4 语音接口（11 个 API）

TTS（文本转语音）：

API	说明
`speechApi.playText()`	播放文本语音
`speechApi.playStreamText()`	流式播放文本语音
`speechApi.stopTTS()`	停止 TTS 播放

ASR（语音识别）：

API	说明
`speechApi.setRecognizable()`	设置是否可识别
`speechApi.setRecognizeMode()`	设置识别模式
`speechApi.queryByText()`	文本查询（模拟语音输入）

声源定位：

API	说明
`speechApi.setAngleCenterRange()`	设置拾音角度范围
`speechApi.resetAngleCenterRange()`	重置拾音角度范围

音频播放：

API	说明
`speechApi.playToneByLocalPath()`	播放本地音频文件
`speechApi.stopTone()`	停止音频播放

大模型：

API	说明
`speechApi.closeStreamDataReceived()`	关闭流式数据接收

4.2.5 灯带控制（3 个 API）

API	说明
`LightApi.playEffect()`	播放灯效
`LightApi.playLightColor()`	设置灯带颜色
`LightApi.playLightAnimation()`	播放灯带动画

4.2.6 人脸识别（4 个 API，1.x 版本）

API	说明
`PersonManager.getAllPerson()`	获取所有已注册人员
`PersonManager.getAllPersonNum()`	获取已注册人员数量
`PersonManager.getLastPersonId()`	获取最近识别人员 ID
`PersonManager.getLastPersonName()`	获取最近识别人员姓名

4.2.7 应用管理（9 个 API）

API	说明
`AppManager.getAppJson()`	获取应用配置 JSON
`AppManager.getOpkExtraPath()`	获取 OPK 附加资源路径
`AppManager.getOpkPath()`	获取 OPK 安装路径
`AppManager.getAppConfig()`	获取应用配置
`AppManager.setConfigUpdateListener()`	设置配置更新监听
`AppManager.getAppId()`	获取应用 ID
`AppManager.getAppIcon()`	获取应用图标
`AppManager.restartApp()`	重启应用
`OpenAppApi.openThirdPartyApp()`	打开第三方应用

4.2.8 系统信息（3 个 API）

API	说明
`SystemInfo.getRobotVersion()`	获取机器人系统版本
`SystemInfo.getDeviceSn()`	获取设备 SN 号
`SystemInfo.getVersionByROM()`	获取 ROM 版本号

4.3 UI 组件

组件	说明
`ExDisplay`	大屏显示
`ImageFrame`	帧动画
`BlurOverlay`	高斯模糊
`RNCameraFilterView`	摄像头预览（含拍照）
`emojiPlayerModel`	大眼睛表情
`UiController.showStatusBar()`	状态栏显示/隐藏

4.4 高级功能

功能	说明
语音大模型流式数据	接入大模型流式输出
视频通话 TRTC	仅豹小秘 Mini 支持
定时任务 Crontab	OPK 内定时任务调度
梯控系统	跨楼层导航
OPK 首页设置	自定义首页展示
多入口配置	多个语音/触屏入口
动态扩展组件	加载 dex/so 库

五、NLP 配置能力

5.1 配置入口

开发者平台：console.orionbase.cn

5.2 核心概念

概念	说明	示例
Domain	领域	`medical`、`navigation`
Intent	意图	`guide_to`、`query_report`
Slot	槽位	`department_name`、`patient_id`

5.3 配置方式

配置项	说明
自定义语音指令	定义触发关键词和对应动作
意图识别规则	配置 NLU 规则匹配用户意图
多轮对话设计	设计多轮交互流程
第三方 NLP 插入	支持 Dialogflow 等外部 NLP 引擎
语音链路测试	在线测试语音识别和意图解析

5.4 NLP 数据流

语音输入 → ASR 识别 → NLP 意图解析 → 匹配 Domain & Intent → 触发对应 OPK/APK 应用

六、适用机型对照

机型	导航	人脸	追踪	回充	TRTC	梯控	屏幕
豹小秘	✅	✅	✅	✅	❌	❌	有
豹小秘 Mini	✅	✅	✅	✅	✅	❌	有
豹小秘2	✅	✅	✅	✅	-	-	有
招财豹	✅	✅	✅	✅	❌	❌	有
招财豹Pro	✅	✅	✅	✅	-	-	有
豹小递 Max	✅	✅	✅	✅	❌	❌	有
豹小秘 DP	部分	✅	❌	部分	❌	❌	大屏
消毒豹	✅	-	-	-	-	✅	-

本手册基于猎户星空开发者文档整理，如有更新请以官方文档为准。

猎户星空API完整参考手册.md 17 KB Permalink History Raw