Skip to content

宠物特征识别 ​

宠物特征识别统一使用 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 总结接口,返回结果见对应接口的返回示例。
生成并读取报告
提交报告任务,轮询至成功后读取完整医疗记录。

图片 URL 的传递关系 ​

图片识别和智能问诊共用 POST /oss/images。这里的 url 指的是上传接口返回 JSON 中的字段,不是图片识别接口返回的字段。图片识别接口的请求体字段名是 img_url,它的值必须来自上传响应的 url,并且保持原样。

顺序接口或字段要求
1POST /oss/images使用 multipart/form-data,表单字段名为 file。
2上传响应的最外层 url读取服务端登记后的图片 URL,并保存这个字符串。
3POST /ai-pic/summary/stream 请求体的 img_url填写第 2 步返回的同一个 URL,不要改写。
4其他图片识别请求体的 img_urlPOST /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普通 JSONmodule_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/streamSSE 流逐段展示 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 一起作为最小审计信息。
  • 图片与识别结果涉及宠物及用户信息,按项目自身的数据授权与保留期限要求处理。
  • 识别结果用于健康筛查辅助,不构成兽医诊断、处方或紧急救治意见。
最近更新

栖界开放平台 · API Documentation