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. 认证体系与调用规范
开放平台采用两阶段凭证安全模型:
- 第一阶段(换取 Access Token):使用开发者 API Key(持久凭据)和项目/终端用户标识,调用
/v1/auth/token接口换取短效access_token(JWT,有效期通常为 24 小时)。 - 第二阶段(调用业务能力):使用获取到的
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 个分类概率,默认 5partString否 佩戴部位(如 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 格式) - 响应体模型:
BirdDetectResponsegetData().getAnnotatedImage(): 绘制了检测锚框的 Base64 图像getData().getDetections(): 检测出的鸟类物种列表(包含位置坐标、中英文名称、置信度及 Top-5 候选)
4.4 宠物档案模块 (client.petProfiles())
管理用户名下的宠物健康与基础生物档案(支持犬、猫及其他常见品种)。
| 方法名 | 方法签名 | 描述 |
|---|---|---|
create | PetProfileResponse create(Map<String, Object> body) | 创建新宠物档案(含姓名、物种、品种、出生日期、绝育状态、体重等) |
list | PetProfileListResponse list(Map<String, Object> queryParams) | 分页查询当前用户/项目绑定的宠物列表 |
get | PetProfileResponse get(String petId) | 获取指定宠物的详细健康资料与档案 |
update | PetProfileResponse update(String petId, Map<String, Object> body) | 修改并更新指定宠物档案字段 |
delete | ApiResponse delete(String petId) | 软删除或注销指定宠物档案 |
listBreeds | BreedListResponse listBreeds(Map<String, Object> queryParams) | 查询系统支持的标准宠物物种与细分品种字典 |
getPetInfo | PetInfoResponse getPetInfo(String petId) | 便捷获取宠物精简基础信息 |
4.5 智能问诊模块 (client.consultation())
全流程智能宠物健康咨询与多轮对话系统。
| 方法名 | 方法签名 | 描述 |
|---|---|---|
createSession | ConsultationSessionResponse createSession(Map<String, Object> body) | 开启新的问诊会话,获取 session_id |
analysis | ConsultationAnalysisResponse analysis(Map<String, Object> body) | 主会话深度分析与问答回复 |
keywords | ConsultationKeywordsResponse keywords(Map<String, Object> body) | 提取症状核心关键词与关联特征 |
preQuestion | ConsultationQuestionResponse preQuestion(Map<String, Object> body) | 会话初期的预设追问与引导问题生成 |
reasonInfo | ConsultationReasonResponse reasonInfo(Map<String, Object> body) | 获取 AI 推理逻辑、鉴别诊断思路及医学依据 |
relatedQuestion | ConsultationRelatedResponse relatedQuestion(Map<String, Object> body) | 生成用户可能感兴趣的延伸就诊建议与相关问题 |
ifContinueAsk | ConsultationAskResponse ifContinueAsk(Map<String, Object> body) | 评估当前病情描述是否完备,判断是否需要继续追问 |
ifNeedImage | ConsultationImageJudgeResponse ifNeedImage(Map<String, Object> body) | 判断当前体征是否需要引导用户拍摄并上传患处图像 |
picResult | ConsultationPicResultResponse picResult(Map<String, Object> body) | 结合患处图像进行多模态综合病情判定 |
summary | ConsultationSummaryResponse summary(Map<String, Object> body) | 生成咨询阶段总结与初步病情研判 |
report | ConsultationReportResponse report(Map<String, Object> body) | 生成结构化完整电子病历与诊疗建议报告 |
getTask | ConsultationTaskResponse getTask(String taskId) | 轮询异步问诊报告生成任务的执行进度 |
getMedicalRecord | MedicalRecordResponse getMedicalRecord(String recordId) | 获取归档病历报告的详情内容 |
saveMessage | ApiResponse saveMessage(Map<String, Object> body) | 手动持久化问诊过程中的历史消息记录 |
listMessages | ConsultationMessageListResponse listMessages(String sessionId) | 检索指定问诊会话的历史完整对话记录 |
4.6 图像病症识别模块 (client.imageRecognition())
面向宠物皮肤病、眼科、口腔及常见体表异状的多模态图像识别能力。
| 方法名 | 方法签名 | 描述 |
|---|---|---|
summary | ImageRecognitionSummaryResponse summary(Map<String, Object> body) | 针对上传病灶图像生成多模态诊断与风险评估总结 |
summaryStream | void summaryStream(Map<String, Object> body, StreamCallback callback) | 以流式(Server-Sent Events)逐步输出诊断与病理分析文本 |
createReportTask | ImageReportTaskResponse createReportTask(Map<String, Object> body) | 提交深度图像识别与结构化病症报告异步生成任务 |
getReportTask | ImageReportTaskResponse getReportTask(String taskId) | 轮询异步图像识别任务的执行状态 |
getMedicalRecord | MedicalRecordResponse getMedicalRecord(String recordId) | 获取由图像识别生成的完整医疗报告记录 |
4.7 多媒体与音频模块 (client.multimedia())
覆盖宠物视频动作识别、吠叫意图音频分析与长音频多模态理解。
| 方法名 | 方法签名 | 描述 |
|---|---|---|
understandVideo | MultimediaTaskResponse understandVideo(Map<String, Object> body) | 提交宠物长/短视频行为理解与事件抽取异步任务 |
getVideoResult | MultimediaResultResponse getVideoResult(String taskId) | 获取视频理解任务分析结果与关键帧事件段落 |
translateSound | MultimediaTaskResponse translateSound(Map<String, Object> body) | 提交犬吠、猫鸣等音频意图分析与情绪翻译任务 |
getVoiceResult | MultimediaResultResponse getVoiceResult(String taskId) | 查询宠物叫声翻译分析任务的执行结果 |
streamVoiceAnalysis | void streamVoiceAnalysis(Map<String, Object> body, StreamCallback callback) | 流式获取音频声学特征识别与情绪反馈结果 |
4.8 资源直传模块 (client.oss())
为多模态识别、音频分析和图像诊断提供便捷的对象存储凭据与文件直传。
| 方法名 | 方法签名 | 描述 |
|---|---|---|
uploadImage | OssUploadResponse uploadImage(File file) | 上传图片文件并返回合规的公网或签名访问 URL |
uploadAudio | OssUploadResponse uploadAudio(File file) | 上传音频文件并返回可用访问 URL |
uploadVideo | OssUploadResponse 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());
}