Skip to content

SDK 与开发工具参考文档 ​

HabitaXX 开放平台为各主流编程语言提供了官方 SDK,并提供了官方命令行工具 CLI 及 AI 智能体 Skill 插件,帮助开发者快速接入平台鉴权、健康检查以及各项 AI 能力(如鸟类多模态识别、宠物 IMU 行为分析、宠物档案、智能问诊等)。

工具与生态清单 ​

名称 / 工具源码 / 包目录文档入口核心特性
Python SDKsdk/habitaxx-pythonPython SDK API 文档原生类型提示、同步与异步双客户端、全模块覆盖
Node.js SDKsdk/habitaxx-nodeNode.js SDK API 文档TypeScript 原生、Promise / Async-Await、现代开发体验
Go SDKsdk/habitaxx-goGo SDK API 文档高性能、基于标准库、结构体强类型约束
Java SDKsdk/habitaxx-javaJava SDK API 文档零第三方依赖、Java 8+ 纯标准库兼容、泛型强类型支持
CLI 命令行工具sdk/cliCLI 命令行工具设备授权流程(RFC 8628)、凭证本地隔离存储、免写代码直调能力
Agent Skill 插件sdk/habitaxx-skillAgent Skill 插件面向 AI 编程助手的 Skill 规范,凭证零泄露安全调度

统一鉴权流程 ​

HabitaXX 开放平台采用两阶段统一认证模式:

  1. 获取 Access Token:开发者使用分配的 x-api-key、project_no 和终端 user_id 向网关换取终端用户的短期 JWT(Access Token)。
  2. 携带 Token 调用能力:在后续请求中通过 HTTP 请求头 Authorization: Bearer <access_token> 访问具体 AI 能力接口。
mermaid
sequenceDiagram
    autonumber
    actor Client as 客户端 (SDK / CLI)
    participant Gateway as 平台网关 (/v1/auth/token)
    participant Capability as AI 能力服务 (/v1/...)

    Client->>Gateway: POST /v1/auth/token (x-api-key + project_no + user_id)
    Gateway-->>Client: 200 OK (access_token, expires_in)
    Client->>Client: 缓存并设置 Authorization: Bearer <access_token>
    Client->>Capability: POST /v1/bird/detect (带图片与 Token)
    Capability-->>Client: 200 OK (code=200, message="success", data=...)

统一返回结构 ​

所有 SDK 及网关接口均返回统一的封装对象(HTTP 状态码固定为 200):

成功返回 ​

json
{
  "code": 200,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}
  • code: 业务状态码,200 表示操作成功。
  • message: 描述提示信息。
  • data: 业务负载,类型对应各语言 SDK 中的响应模型。

失败统一返回结构 (HTTP 200) ​

json
{
  "code": 10002,
  "error_code": "INVALID_API_KEY",
  "message": "访问密钥无效或已过期",
  "data": null,
  "call_id": "call_94b5952f4dc248dbb4f6236bb5ff64cf"
}
  • code: 平台统一数字状态码。非 200 表示调用失败。
  • error_code: 英文机器识别大写常量(如 INVALID_API_KEY、TOKEN_EXPIRED)。
  • message: 错误提示文案。
  • data: 失败时固定为 null。
  • call_id: 单次请求唯一排查标识(以 call_ 开头),与响应头 X-QJ-Request-ID 一致。系统故障时固定返回 50001 + SERVICE_BUSY(服务繁忙)。
最近更新

栖界开放平台 · API Documentation