高仙机器人开放平台

平台能力

认证服务 — OAuth 2.0 自动 Token 管理与刷新，提前 5 分钟自动续期，业务代码无需关心认证细节
机器人控制 — 状态查询、任务下发、指令控制，覆盖机器人全生命周期管理
地图管理 — 地图上传下载、区域分区查询，支持多楼层场景配置
实时推送 — 事件告警推送、任务完成通知，支持 WebSocket 长连接与回调两种模式

快速开始

安装 SDK 并完成第一次 API 调用只需三步：安装依赖、配置凭据、发起请求。

pip install gausium-sdk

import asyncio
from gausium_sdk import GausiumSDK

async def main():
    async with GausiumSDK(
        client_id="your_client_id",
        client_secret="your_client_secret",
        open_access_key="your_open_access_key",
    ) as sdk:
        # 获取机器人列表
        robots = await sdk.robot.list()
        for r in robots:
            print(f"{r.sn} — {r.name}")

        # 查询单台机器人状态
        status = await sdk.robot.get_status("GS101-00A0-A7L-0000")
        print(f"电量: {status.battery}%")

asyncio.run(main())

API 概览

平台共提供 8 组 API，涵盖认证、设备、运营、数据四大领域。所有接口以 https://openapi.gs-robot.com 为 Base URL。

服务模块	接口数量	说明
认证服务 (OAuth)	2	Token 获取与刷新
机器人信息	6	设备列表、详情、状态、版本查询
任务管理	3	任务创建、查询、取消
指令控制	4	远程指令下发与执行状态查询
地图管理	5	地图上传、下载、区域与分区查询
清洁数据	4	清洁记录、统计、报表导出
推送服务	—	事件告警与任务完成回调推送
电梯控制	—	电梯呼叫、状态查询（独立协议）

口诀认机任指地清推梯

架构设计

SDK 采用三层架构：核心层（认证 + HTTP 客户端）、服务层（按业务域拆分的 Service 类）、模型层（Pydantic 数据模型）。所有服务通过 sdk.<service> 懒加载访问，无额外初始化开销。

Auth 层自动管理 Token 生命周期，业务代码零感知
Client 层基于 httpx.AsyncClient，内置连接池复用
服务层每个方法返回强类型 Pydantic 模型，IDE 自动补全友好
通过 async with 上下文管理器确保资源正确释放