Skip to content

宠物特征识别业务流程与接口总览 ​

本页是宠物特征识别的唯一权威全景总览,汇总了识别的主流程时序、sub_module_type 取值体系与对应报告模型、接口调用清单及数据传递关系。每个接口的详细参数与代码示例见侧边栏对应的独立接口页。

业务主流程与时序 ​

text
POST /ms-ai-fast/session-records/sessions(创建识别会话,body 传 module_type=5 与 sub_module_type)
        ↓
POST /oss/images(上传宠物照片,获取临时安全访问 url)
        ↓
POST /ms-ai-fast/ai-pic/summary/stream(SSE,流式识别图像特征并输出初筛小结)
        ↓
POST /ms-ai-fast/ai-pic/sessions/report-tasks(提交异步完整分析报告任务)
        ↓
GET /ai-tasks/{task_id}(轮询异步任务进度,直至 succeeded)
        ↓
GET /ms-ai-fast/medical-records/{record_id}(读取最终结构化识别报告详情)

sub_module_type 识别能力与报告体系映射 ​

创建会话时通过 sub_module_type 指定识别场景(1 至 8)。虽然细分为 8 种场景,但在底层和前端 UI 渲染上归纳为 3 大核心报告体系:

sub_module_type识别场景所属体系核心卡片渲染与数据结构特点
1品种识别品种报告体系包含 result.prob[] 品种概率进度条与双段式饲养养护指南。
2情绪/表情识别情绪报告体系包含 result.emotion 核心情绪大徽章、局部表情信号分析与互动安抚指南。
3口腔检测通用体征体系牙、便、呕、皮、耳、眼(3~8)共用同一套结构:
包含整体健康 Banner、正常/异常 Tab、疾病风险条、四维病理卡片与用药生活指南。
4排泄物通用体征体系同上(通用体征报告模型)
5呕吐物通用体征体系同上(通用体征报告模型)
6皮肤检测通用体征体系同上(通用体征报告模型)
7耳道检查通用体征体系同上(通用体征报告模型)
8眼睛检查通用体征体系同上(通用体征报告模型)

接口调用目录与步骤清单 ​

步骤接口方法返回类型调用时机与业务说明
1/session-records/sessionsPOSTJSON必选。初始化识别会话(module_type 传 5),绑定 sub_module_type 与 pet_profile_id。
2/oss/imagesPOSTJSON上传识别原图,获得合法的 OSS 资源 url。
3/ai-pic/summary/streamPOSTSSE流式识别画面并输出初步分析小结。
4/ai-pic/sessions/report-tasksPOSTJSON提交完整结构化分析报告任务,获取 task_id。
5/ai-tasks/{task_id}GETJSON轮询任务进度,直至 succeeded。
6/medical-records/{record_id}GETJSON任务成功后,读取完整的结构化报告数据。各体系深度字段请参阅 识别报告字段详解与页面映射。

核心上下文传递链 ​

text
第 1 步 创建会话
   └── session_id ──────────────┬──> 第 3 步:流式小结的 session_id
                                └──> 第 4 步:提交报告任务的 session_id

第 2 步 上传图片
   └── url ─────────────────────────> 第 3 步与第 4 步的 img_url

第 4 步 提交报告任务
   └── task.task_id ────────────────> 第 5 步:轮询任务 /ai-tasks/{task_id}

第 5 步 任务完成
   └── 轮询至 succeeded ────────────> 第 6 步:GET /medical-records/{record_id}

分步接入要点 ​

第 1 步 创建识别会话 ​

创建会话前先选定一个 sub_module_type,该值会写入会话,之后不能修改;请求只传对应数字,不要传能力名称。

json
{
  "module_type": 5,
  "sub_module_type": 7,
  "pet_profile_id": 44,
  "lang": "zh-CN"
}

module_type 固定为 5;pet_profile_id 是通过宠物档案取得的数字 ID。保存响应 data 中的 session_id。

第 2 步 上传图片 ​

使用 multipart/form-data 上传:

表单字段值
file图片文件本体;支持 jpg、jpeg、png、webp、gif,单文件最大 10 MiB。

读取完整上传成功响应 data 内的 url 字段并持久化,后续所有 img_url 都必须原样复用它:不要使用图片网页地址、临时签名地址、自拼 OSS 地址或其他用户上传的地址。

第 3 步 流式识别并生成小结 ​

一次调用同时完成识别和小结,事件按以下规则消费:

  1. 收到唯一的 metadata 事件后,记录链路信息;
  2. 对每个 type 为 content 的事件,读取该事件 JSON 的 content 字段并渐进展示;不要用中间文本判断业务完成;
  3. 收到完整的 type 为 done 的终止事件后,读取其中的 data 对象作为结构化识别结果,此时才能把识别标记为完成;
  4. 收到 error,或连接关闭前既没有 done 也没有 error,都判定本次失败;只有 error.retryable 为 true 或网络类错误才可有限重试。

第 4 步 并行提交报告任务并读取报告 ​

报告任务可以和识别流同时提交,不必等待识别文本全部返回。

json
{
  "session_id": "<SESSION_ID>",
  "img_url": "<UPLOAD_RESPONSE_DATA_URL>"
}

从完整成功响应 data 内的 task.task_id 取得任务 ID,用 GET /ai-tasks/{task_id} 轮询:固定每 4 秒一次,最长轮询 5 分钟;状态进入 succeeded、failed 或 canceled 后立即停止。

报告任务成功后,用 GET /medical-records/{record_id} 读取报告详情与分片,或用 GET /medical-records?module_type=5 查询历史识别记录。

两条结果要分别处理

识别流和报告任务是两条独立链路:小结流失败不代表报告任务失败,报告任务成功也不代表客户端已经收到完整的 done 事件。客户端必须分别记录两条结果,并且只有收到 SSE done 才把识别标记为完成。

重试失败的报告任务时,用失败任务返回的 task_id 调用 POST /ai-tasks/{task_id}/retry,不要重复为同一会话创建报告任务。

会话不可变约束 ​

系统会把会话绑定到宠物档案、sub_module_type、语言和首次使用的图片资产。

情况公开可见的返回正确处理
流式识别时 sub_module_type 与会话不一致SSE error 事件:code 为 AI_PIC_SUB_MODULE_MISMATCH、error_code 为 6103、retryable 为 false、recommended_action 为 restart_session(HTTP 状态仍为 200)使用会话固定的类型,或新建对应类型的会话。
同一会话换图或换档案后再提交报告任务HTTP 4xx,message 提示会话或资源冲突(内部标识 TASK_IDEMPOTENCY_CONFLICT,公开数字码 6001 只在任务对象与 SSE 错误事件中出现)不要在同一会话内换图,新建会话。

这两类错误都不应直接重试。第一行的字段取值来自线上实测的 SSE 错误事件。

lang 与 locale ​

宠物档案接口用 Query 参数 ?locale=... 控制品种展示名;图片识别用请求体的 lang 固化 AI 会话语言。两者可以取相同的 BCP 47 值,但不能互相替代。

客户端界面语言宠物档案读取图片识别创建会话
简体中文?locale=zh-CN"lang": "zh-CN"
香港繁体中文?locale=zh-Hant-HK"lang": "zh-Hant-HK"
美国英语?locale=en-US"lang": "en-US"

会话建立后:

  • 后续 AI 请求建议省略 lang,沿用会话语言;
  • 如必须传入,值必须与创建会话时完全相同;
  • 传入不同语言会返回 SESSION_LOCALE_MISMATCH,不会静默回退,也不允许在同一会话中切换语言。

失败后的处理 ​

下表的标识在哪里可见

表中名称是服务端内部原因标识:流式接口失败时它出现在 SSE error 事件的 code 字段(同一事件还给出公开数字码 error_code);普通 HTTP 4xx/5xx 只返回 {code, message, data},既不含内部标识也不含数字错误码,只能按 HTTP 状态与 message 判断;异步任务失败时数字码在任务对象的 data.error_code。

触发条件(内部标识 / 公开可见返回)是否重试正确处理
网络超时或 SSE retryable: true可有限重试使用相同的请求参数重试。
未收到 SSE 终止事件可有限重试将本次流视为失败,重新发起整个流;不要把零散 content 当最终结果。
MEDIA_URL_NOT_ALLOWED / MEDIA_URL_INVALID
HTTP 400,message「媒体URL不是当前服务登记的OSS地址」(SSE 场景下也可能以 error 事件返回)
不直接重试重新上传,并使用上传响应中的 url 原值。
AI_PIC_SUB_MODULE_MISMATCH
SSE error 事件,error_code 6103
不直接重试使用会话固定的类型,或新建会话。
TASK_IDEMPOTENCY_CONFLICT
HTTP 4xx(仅 message 可见)
不直接重试不在旧会话换图,新建会话。
报告任务 failed先看错误码记录 task_id、session_id 和 error_code;错误码可重试时再调用重试接口。
最近更新

栖界开放平台 · API Documentation