Skip to content

Java SDK 开发指南 ​

Habitaxx 官方提供的 Java 服务端 SDK,基于现代化 Java 设计,封装了开放平台的全量 AI 能力与管理能力,提供强类型数据模型、OkHttp 稳健网络传输以及对统一响应与错误码的完整封装。

SDK 源码目录:sdk/habitaxx-java


1. 安装与准备 ​

Maven 依赖配置 ​

xml
<dependency>
    <groupId>com.habitaxx</groupId>
    <artifactId>habitaxx-java</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle 依赖配置 ​

groovy
implementation 'com.habitaxx:habitaxx-java:0.1.0'

依赖环境 ​

  • Java 8 或 Java 11 及以上版本

2. 认证体系与调用规范 ​

开放平台采用两阶段凭证安全模型:

  1. 第一阶段(换取 Access Token):使用开发者 API Key(持久凭据)和项目/终端用户标识,调用 /v1/auth/token 接口换取短效 access_token(JWT,有效期通常为 24 小时)。
  2. 第二阶段(调用业务能力):使用获取到的 access_token 初始化业务客户端,调用具体 AI 能力接口。网关将对 Token 进行鉴权与限流计量。

统一响应与错误排查 ​

开放平台对外接口统一响应 HTTP 200 状态码,实际调用结果由响应体的 code 与业务字段呈现:

json
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "call_id": "call_6a96d6bda27ff05dee01244b314e5662"
}

当接口鉴权失败、参数错误或限流时,HTTP 状态码依然保持 200,并返回平台标准错误码结构:

json
{
  "code": 10002,
  "error_code": "INVALID_API_KEY",
  "message": "API Key 无效",
  "data": null,
  "call_id": "call_6a96d6bda27ff05dee01244b314e5662"
}

所有系统级与业务级异常均已收敛脱敏,客户端可直接通过 call_id 向平台技术支持反馈追踪。


3. 完整调用示例 ​

java
package com.example;

import com.habitaxx.HabitaxxClient;
import com.habitaxx.models.auth.AuthTokenResponse;
import com.habitaxx.models.imu.ImuPredictResponse;
import com.habitaxx.models.bird.BirdDetectResponse;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        // 开发者凭据(示例已脱敏)
        String apiKey = "qj_live_your_api_key_here";
        String projectNo = "prj_your_project_no_here";
        String userId = "user_unique_identifier_123";

        // 1. 初始化认证阶段客户端
        HabitaxxClient authClient = HabitaxxClient.builder()
                .apiKey("placeholder")
                .baseUrl("https://open-api.habitaxx.com")
                .build();

        // 2. 换取短效 Access Token
        AuthTokenResponse tokenResp = authClient.auth().token(apiKey, projectNo, userId);
        String accessToken = tokenResp.getData().getAccessToken();
        System.out.println("成功获取 Access Token: " + accessToken);

        // 3. 使用 Access Token 初始化业务客户端
        HabitaxxClient client = HabitaxxClient.builder()
                .apiKey(accessToken)
                .baseUrl("https://open-api.habitaxx.com")
                .build();

        // 4. 调用 IMU 行为姿态预测
        List<List<Double>> samples = new ArrayList<>();
        // 推荐传入 100 组 6 轴时序采样数据 (1 秒时序数据)
        samples.add(Arrays.asList(-0.322, -0.498, -0.657, -32.217, -21.967, 1.33));

        Map<String, Object> imuBody = new HashMap<>();
        imuBody.put("samples", samples);
        imuBody.put("top_k", 5);

        ImuPredictResponse imuResp = client.imu().predict(imuBody);
        System.out.println("预测主行为: " + imuResp.getData().getPrediction().getNameZh());

        // 5. 调用鸟类多模态识别
        File imageFile = new File("./sample_bird.jpg");
        BirdDetectResponse birdResp = client.bird().detect(imageFile);
        System.out.println("检测识别数量: " + birdResp.getData().getDetections().size());
    }
}

4. 模块详细参考 (API Reference) ​

Habitaxx 客户端实例 client 包含以下资源服务对象:

模块方法对应资源服务类描述
client.auth()AuthService凭证交换与鉴权管理
client.imu()ImuService智能项圈 IMU 行为时序多轴传感器算法识别
client.bird()BirdService鸟类与野生动物多模态目标检测与细粒度物种识别
client.petProfiles()PetProfilesService宠物档案管理(增删改查、品种列表与基本信息)
client.consultation()ConsultationService智能健康问诊与问答交互全流程
client.imageRecognition()ImageRecognitionService宠物图像病症多模态识别与诊断总结
client.multimedia()MultimediaService宠物视频行为理解、吠声意图翻译与音频多模态分析
client.oss()OssService开放平台媒体资源直传与转存对象存储服务

4.1 认证模块 (client.auth()) ​

用于凭据转换与短效令牌签发。

方法:auth().token(apiKey, projectNo, userId) ​

  • 方法签名:AuthTokenResponse token(String apiKey, String projectNo, String userId)
  • 参数说明:
    参数名类型是否必填描述
    apiKeyString是平台颁发的永久 API Key(以 qj_live_ 开头)
    projectNoString是关联的项目编号(例如 prj_xxx)
    userIdString是终端用户或设备唯一标识字符串
  • 响应体模型:AuthTokenResponse(包含 getCode(), getMessage(), getData().getAccessToken(), getCallId())

4.2 IMU 行为预测模块 (client.imu()) ​

处理来自穿戴设备(如智能宠物项圈)的高频时序 6 轴加速度计与陀螺仪传感器数据,智能识别趴卧、行走、奔跑、玩耍等精细行为姿态。

方法 1:imu().predict(requestBody) ​

通用 IMU 时序数据姿态预测。

  • 方法签名:ImuPredictResponse predict(Map<String, Object> requestBody)
  • 请求参数:
    参数 Key类型是否必填描述
    samplesList<List<Double>>是6 轴传感器采样矩阵,格式为 [[ax, ay, az, gx, gy, gz], ...],建议 100 组
    top_kInteger否返回置信度前 K 个分类概率,默认 5
    partString否佩戴部位(如 neck、back),默认 neck
  • 响应体模型:ImuPredictResponse,提供主预测类别、多维度置信度分布与硬件采样统计信息。

方法 2:imu().predict(deviceId, requestBody) ​

指定硬件设备 ID 的 IMU 数据推理。

  • 方法签名:ImuPredictResponse predict(String deviceId, Map<String, Object> requestBody)
  • 请求参数:
    参数 Key类型是否必填描述
    deviceIdString是硬件设备标识(如设备出厂 SN 码)
    requestBodyMap<String, Object>是同 imu().predict(requestBody) 请求参数

4.3 鸟类多模态识别模块 (client.bird()) ​

支持对野外或家庭环境拍摄的鸟类图像进行目标检测、边界框定位、物种精细分类(支持数百种常见鸟类)与 top-5 置信度评估。

方法:bird().detect(imageFile) ​

上传并识别鸟类图像。

  • 方法签名:BirdDetectResponse detect(File imageFile)
  • 参数说明:
    参数名类型是否必填描述
    imageFilejava.io.File是本地待检测图片文件(支持 JPG / PNG 格式)
  • 响应体模型:BirdDetectResponse
    • getData().getAnnotatedImage(): 绘制了检测锚框的 Base64 图像
    • getData().getDetections(): 检测出的鸟类物种列表(包含位置坐标、中英文名称、置信度及 Top-5 候选)

4.4 宠物档案模块 (client.petProfiles()) ​

管理用户名下的宠物健康与基础生物档案(支持犬、猫及其他常见品种)。

方法名方法签名描述
createPetProfileResponse create(Map<String, Object> body)创建新宠物档案(含姓名、物种、品种、出生日期、绝育状态、体重等)
listPetProfileListResponse list(Map<String, Object> queryParams)分页查询当前用户/项目绑定的宠物列表
getPetProfileResponse get(String petId)获取指定宠物的详细健康资料与档案
updatePetProfileResponse update(String petId, Map<String, Object> body)修改并更新指定宠物档案字段
deleteApiResponse delete(String petId)软删除或注销指定宠物档案
listBreedsBreedListResponse listBreeds(Map<String, Object> queryParams)查询系统支持的标准宠物物种与细分品种字典
getPetInfoPetInfoResponse getPetInfo(String petId)便捷获取宠物精简基础信息

4.5 智能问诊模块 (client.consultation()) ​

全流程智能宠物健康咨询与多轮对话系统。

方法名方法签名描述
createSessionConsultationSessionResponse createSession(Map<String, Object> body)开启新的问诊会话,获取 session_id
analysisConsultationAnalysisResponse analysis(Map<String, Object> body)主会话深度分析与问答回复
keywordsConsultationKeywordsResponse keywords(Map<String, Object> body)提取症状核心关键词与关联特征
preQuestionConsultationQuestionResponse preQuestion(Map<String, Object> body)会话初期的预设追问与引导问题生成
reasonInfoConsultationReasonResponse reasonInfo(Map<String, Object> body)获取 AI 推理逻辑、鉴别诊断思路及医学依据
relatedQuestionConsultationRelatedResponse relatedQuestion(Map<String, Object> body)生成用户可能感兴趣的延伸就诊建议与相关问题
ifContinueAskConsultationAskResponse ifContinueAsk(Map<String, Object> body)评估当前病情描述是否完备,判断是否需要继续追问
ifNeedImageConsultationImageJudgeResponse ifNeedImage(Map<String, Object> body)判断当前体征是否需要引导用户拍摄并上传患处图像
picResultConsultationPicResultResponse picResult(Map<String, Object> body)结合患处图像进行多模态综合病情判定
summaryConsultationSummaryResponse summary(Map<String, Object> body)生成咨询阶段总结与初步病情研判
reportConsultationReportResponse report(Map<String, Object> body)生成结构化完整电子病历与诊疗建议报告
getTaskConsultationTaskResponse getTask(String taskId)轮询异步问诊报告生成任务的执行进度
getMedicalRecordMedicalRecordResponse getMedicalRecord(String recordId)获取归档病历报告的详情内容
saveMessageApiResponse saveMessage(Map<String, Object> body)手动持久化问诊过程中的历史消息记录
listMessagesConsultationMessageListResponse listMessages(String sessionId)检索指定问诊会话的历史完整对话记录

4.6 图像病症识别模块 (client.imageRecognition()) ​

面向宠物皮肤病、眼科、口腔及常见体表异状的多模态图像识别能力。

方法名方法签名描述
summaryImageRecognitionSummaryResponse summary(Map<String, Object> body)针对上传病灶图像生成多模态诊断与风险评估总结
summaryStreamvoid summaryStream(Map<String, Object> body, StreamCallback callback)以流式(Server-Sent Events)逐步输出诊断与病理分析文本
createReportTaskImageReportTaskResponse createReportTask(Map<String, Object> body)提交深度图像识别与结构化病症报告异步生成任务
getReportTaskImageReportTaskResponse getReportTask(String taskId)轮询异步图像识别任务的执行状态
getMedicalRecordMedicalRecordResponse getMedicalRecord(String recordId)获取由图像识别生成的完整医疗报告记录

4.7 多媒体与音频模块 (client.multimedia()) ​

覆盖宠物视频动作识别、吠叫意图音频分析与长音频多模态理解。

方法名方法签名描述
understandVideoMultimediaTaskResponse understandVideo(Map<String, Object> body)提交宠物长/短视频行为理解与事件抽取异步任务
getVideoResultMultimediaResultResponse getVideoResult(String taskId)获取视频理解任务分析结果与关键帧事件段落
translateSoundMultimediaTaskResponse translateSound(Map<String, Object> body)提交犬吠、猫鸣等音频意图分析与情绪翻译任务
getVoiceResultMultimediaResultResponse getVoiceResult(String taskId)查询宠物叫声翻译分析任务的执行结果
streamVoiceAnalysisvoid streamVoiceAnalysis(Map<String, Object> body, StreamCallback callback)流式获取音频声学特征识别与情绪反馈结果

4.8 资源直传模块 (client.oss()) ​

为多模态识别、音频分析和图像诊断提供便捷的对象存储凭据与文件直传。

方法名方法签名描述
uploadImageOssUploadResponse uploadImage(File file)上传图片文件并返回合规的公网或签名访问 URL
uploadAudioOssUploadResponse uploadAudio(File file)上传音频文件并返回可用访问 URL
uploadVideoOssUploadResponse uploadVideo(File file)上传视频文件并返回可用访问 URL

5. 错误处理与规范 ​

SDK 将所有响应体统一按规范映射。当返回 code != 200 时,可从响应体中获取具体错误信息:

java
try {
    ImuPredictResponse response = client.imu().predict(requestBody);
    if (response.getCode() != 200) {
        System.err.printf("业务异常 [%s]: %s (call_id: %s)%n",
                response.getErrorCode(), response.getMessage(), response.getCallId());
    } else {
        System.out.println("调用成功: " + response.getData());
    }
} catch (HabitaxxException e) {
    System.err.println("网络或传输层异常: " + e.getMessage());
}
最近更新

栖界开放平台 · API Documentation