宠物特征识别
宠物特征识别统一使用 module_type = 5,并通过 sub_module_type 选择具体能力。有效值只有 1 至 8。一次会话只能对应一种识别能力和一张输入图片;如需检测其他部位或更换图片,请重新创建会话。
网关能力前缀
https://open-api.habitaxx.com/v1/ms-ai-fast推荐接入方式
最短的报告链路依次为:创建识别会话、上传图片、流式识别并生成小结、提交报告任务、轮询任务并读取报告。需要完整时序、SSE 终止规则或语言规则时,请先阅读宠物特征识别完整流程。
能力矩阵
sub_module_type | 能力 |
|---|---|
1 | 品种识别 |
2 | 表情识别 |
3 | 牙齿检测 |
4 | 排泄物检测 |
5 | 呕吐物检测 |
6 | 皮肤检测 |
7 | 耳道检测 |
8 | 眼睛检测 |
sub_module_type 是接口参数,不是展示标签。它必须与创建会话时一致:例如皮肤检测固定传 6,不能在同一 session_id 内改成 8。
推荐流程
上传图片
调用
调用
POST /oss/images;在完整成功响应 JSON 的最外层 data 对象中读取 url,再将这个原值作为后续请求的 img_url。取得识别结果
调用即时识别接口;不传
调用即时识别接口;不传
session_id 时,服务会自动创建 pic_... 会话。可选生成总结
已有会话可调用同步或 SSE 总结接口,返回结果见对应接口的返回示例。
已有会话可调用同步或 SSE 总结接口,返回结果见对应接口的返回示例。
生成并读取报告
提交报告任务,轮询至成功后读取完整医疗记录。
提交报告任务,轮询至成功后读取完整医疗记录。
图片 URL 的传递关系
图片识别和智能问诊共用 POST /oss/images。这里的 url 指的是上传接口返回 JSON 中的字段,不是图片识别接口返回的字段。图片识别接口的请求体字段名是 img_url,它的值必须来自上传响应的 url,并且保持原样。
| 顺序 | 接口或字段 | 要求 |
|---|---|---|
| 1 | POST /oss/images | 使用 multipart/form-data,表单字段名为 file。 |
| 2 | 上传响应的最外层 url | 读取服务端登记后的图片 URL,并保存这个字符串。 |
| 3 | POST /ai-pic/summary/stream 请求体的 img_url | 填写第 2 步返回的同一个 URL,不要改写。 |
| 4 | 其他图片识别请求体的 img_url | POST /ai-pic/sessions/report-tasks 继续使用同一个 URL。 |
上传成功响应的完整结构示例:
json
{
"code": 200,
"message": "success",
"data": {
"media_type": "image",
"file_name": "server-generated-name.jpg",
"object_key": "test/ai-pic/server-generated-name.jpg",
"content_type": "image/jpeg",
"size_bytes": 245810,
"etag": "<ETAG>",
"url": "<UPLOAD_RESPONSE_DATA_URL>"
}
}图片识别请求体中的对应关系:
json
{
"pet_profile_id": 44,
"img_url": "<UPLOAD_RESPONSE_DATA_URL>",
"sub_module_type": 6,
"lang": "zh-CN"
}不要把 url 改成图片网页地址、自拼接的 OSS 地址、第三方 URL、带 query 或 fragment 的 URL,也不要使用其他用户上传的图片地址。
选择要调用的接口
下表只说明“调用哪个接口”和“成功后做什么”。字段的实际位置请以接口总览中的完整示例和每个接口页为准,不用孤立的字段路径代替完整响应。
| 使用场景 | 接口 | 返回方式 | 成功后怎么处理 |
|---|---|---|---|
| 创建识别会话 | POST /session-records/sessions | 普通 JSON | module_type 固定为 5,带上 sub_module_type(1~8)和数字 pet_profile_id;从完整响应的 data 对象里取 session_id。 |
| 上传图片 | POST /oss/images | 普通 JSON | 从完整响应最外层 data 对象里取 url,原样用于后续接口的 img_url。 |
| 首次识别并生成小结 | POST /ai-pic/summary/stream | SSE 流 | 逐段展示 type 为 content 的事件;只有收到完整的 type 为 done 的终止事件,才算识别成功,最终结果在 done 事件里。 |
| 生成完整报告 | POST /ai-pic/sessions/report-tasks | 普通 JSON,返回后台任务 | 从完整成功响应的 task 对象中取得 task_id,再调用 GET /ai-tasks/{task_id},直到任务状态变为 succeeded、failed 或 canceled。该接口可以与识别接口并行提交。 |
| 读取报告 | GET /medical-records/{record_id} | 普通 JSON | 报告任务成功后读取记录详情与报告分片;历史识别记录用 GET /medical-records?module_type=5 查询。 |
只有“生成完整报告”会创建需要轮询的后台任务,任务类型为 ai_pic_report_generate。识别本身由 summary/stream 完成,不需要也不应该去轮询识别任务。
图片与会话前提
- 上传图片格式:
jpg、jpeg、png、webp、gif;最大 10 MiB;上传细节见公共接口。 - 图片识别会话的
pet_profile_id是通过宠物档案接口取得的数值 ID(例如44),必须与会话一致。 - 图片识别的语言字段是请求 Body 中的
lang,默认zh-CN;它与宠物档案查询参数?locale=...不是同一个字段。创建会话后,后续请求如传lang,必须与会话语言一致。 /oss/images成功响应中,最外层data对象的url字段就是后续图片接口的img_url。请完整读取该响应后复制这个字符串,不要使用第三方 URL、自行拼接的 OSS URL、带 query 参数的 URL 或其他用户的资源;典型错误码为MEDIA_URL_NOT_ALLOWED、MEDIA_ASSET_NOT_FOUND或MEDIA_URL_INVALID。- 服务会把首次使用的图片资产绑定到会话。后续总结或报告换用另一张图片会返回
TASK_IDEMPOTENCY_CONFLICT;需要换图时请新建会话。
记录与合规
- 每次上传后记录响应中的
url,与session_id、sub_module_type一起作为最小审计信息。 - 图片与识别结果涉及宠物及用户信息,按项目自身的数据授权与保留期限要求处理。
- 识别结果用于健康筛查辅助,不构成兽医诊断、处方或紧急救治意见。