Skip to content

宠物智能问诊 ​

宠物智能问诊是一条以会话为中心的多步骤流程:收集主诉、提取关键词、展示推理说明、分析与追问、按需补充图片、生成总结,并异步生成完整报告。

网关能力前缀https://open-api.habitaxx.com/v1/ms-ai-fast

先读流程,再接接口

智能问诊不是单次请求。请先完成完整流程,再按接口总览实现接口调用、SSE 消费与报告轮询。

接入前提 ​

  1. 按身份认证使用项目 API Key 换取 ACCESS_TOKEN;业务请求统一携带 Authorization: Bearer <ACCESS_TOKEN>。

注意:源码层还要求 x-qj-user。如果通过公开网关调用,应由网关在完成 Authorization 校验后注入该请求头;外部客户端不要自行伪造。直接调用服务端时,请按接口总览中的说明显式携带它。

  1. 为每位最终用户维护独立 Token 上下文;不要把不同用户的 session_id、图片 URL 或报告 ID 混用。
  2. 所有 AI 请求均使用文档列出的 /v1/ms-ai-fast/... 网关路径。不要在该前缀后添加任何未列出的路径段;未发布的地址会返回 404 Not Found。
  3. module_type: 1 的问诊会话必须提供数字 pet_profile_id 和非空初始主诉 content。pet_profile_id 通过宠物档案接口取得,是数值 ID(例如 44)。

推荐集成路径 ​

下表只说明接口调用顺序和接口之间需要传递的字段。每个接口的完整请求、返回示例和字段说明见接口总览。

步骤调用接口本次请求成功后使用的返回字段下一步
—轮次说明第 3~7 步构成一轮问答;后端不强制轮次,常见做法是 3~4 轮—未到约定轮次时直接进入下一轮,不判断继续。
1GET /ai-doc/pre-question(可选)Query:pet_profile_id、lang预设问题列表创建会话,或直接创建会话。
2POST /session-records/sessionsJSON:module_type、pet_profile_id、content、lang完整成功响应 data 对象中的 session_id后续问诊接口统一使用该会话 ID。
3POST /ai-doc/keywordsJSON:session_id、pet_profile_id、content关键词接口返回的结构化结果调用推理说明或病情分析。
4POST /ai-doc/reason-info(SSE)JSON:session_id、pet_profile_idtype=done 中的最终结果调用病情分析。
5POST /ai-doc/analysisJSON:session_id、pet_profile_id病情分析结果获取关联追问。
6POST /ai-doc/related-questionJSON:session_id、pet_profile_id关联问题列表展示问题并收集用户回答。
7POST /session-records/messagesJSON:session_id、role、content消息保存结果第 1、2 轮直接进入下一轮;第 3 轮判断是否继续;第 4 轮进入图片判断。
8POST /ai-doc/if-continue-ask(SSE)仅第 3 轮后调用一次JSON:session_id、pet_profile_id完整 type=done 事件的业务结果对象中的 content:True 或 FalseTrue 进入第 4 轮问答;False 调用图片判断。
9POST /ai-doc/if-need-imageJSON:session_id、pet_profile_id完整成功响应业务结果对象中的 is_pic 和 pic_explainTrue 上传图片;False 直接生成总结。
10POST /oss/images(需要图片时)multipart 表单:file完整上传成功响应 data 对象中的 url将同一个 URL 填入图片补充接口的 img_url。
11POST /ai-doc/pic-result(需要图片时)JSON:session_id、pet_profile_id、img_url图片补充结果生成问诊总结。
12POST /ai-doc/summary(SSE)JSON:session_id、pet_profile_idtype=done 中的最终总结提交报告任务。
13POST /ai-doc/reportJSON:session_id、report_type完整成功响应 data 对象中 task.task_id查询异步任务状态。
14GET /ai-tasks/{task_id}Path:task_id完整成功响应 data 对象中的 status状态为 succeeded 后读取完整报告。
15GET /medical-recordQuery:session_id 或 report_id(二选一)完整医疗记录流程结束。

接口分组 ​

分组接口用途
会话准备GET /ai-doc/pre-question、POST /session-records/sessions读取预设问题、创建会话。
问答分析POST /ai-doc/keywords、POST /ai-doc/reason-info、POST /ai-doc/analysis、POST /ai-doc/related-question从用户输入形成追问与分析。
流程分支POST /session-records/messages、POST /ai-doc/if-continue-ask、POST /ai-doc/if-need-image保存回答、决定继续追问或补图。
图片补充POST /oss/images、POST /ai-doc/pic-result上传问诊图片并获取图片补充结果。
总结与报告POST /ai-doc/summary、POST /ai-doc/report、GET /ai-tasks/{task_id}、GET /medical-record流式总结、异步生成并读取完整报告。

各接口的完整网关地址见接口总览。

关键集成规则 ​

content 会生成 initial_message ​

content 是创建会话的请求字段,问诊会话必填;服务会把它保存为首条用户消息。响应的 initial_message 是这条消息对象,提交的原文在 initial_message.content——它不是第二个请求字段。

SSE 以终止事件为准 ​

reason-info、if-continue-ask、summary 都返回 text/event-stream。流从 metadata 开始,可能包含多个 content,最终只会以 type=done 或 type=error 之一结束:

  • data: {"type":"content",...} 只用于逐步展示,不代表当前业务步骤完成;
  • 仅在收到 data: {"type":"done",...} 后,才能执行下一步骤;最终结果位于该 JSON 的 data 字段中,具体字段以对应接口的“返回字段”表为准;
  • 收到 error 或连接在没有终止事件时断开,均应按失败处理;
  • error.retryable=true 时可有限重试;否则应提示用户调整输入或稍后重试。

详细事件格式和状态分支见完整流程。

问诊图片必须是平台登记资产 ​

POST /ai-doc/pic-result 不接受任意外部 URL。图片补充分支的字段传递关系如下:

顺序接口或字段要求
1POST /oss/images使用 multipart/form-data 上传图片。
2上传响应的 url获取服务端返回的平台图片 URL。
3POST /ai-doc/pic-result 请求体的 img_url填写第 2 步返回的同一个 URL,不要改写。

该 URL 必须属于当前用户、状态为 ready、为图片类型,且与上传登记的规范 OSS URL 完全一致。不要使用第三方 URL、自己拼接的对象地址、历史用户资产或示例域名 URL。

报告只需提交一次 ​

POST /ai-doc/report 的请求体只包含 session_id 和 report_type。report_type 允许值为 1、2、3、4、7,省略时默认 1。当前报告生成会汇总这些报告分片;对同一会话的正常流程只需提交一次报告任务,随后轮询 task.task_id,成功后通过 GET /medical-record?session_id=<SESSION_ID> 读取完整报告。不要按五个类型连续提交五次。

最近更新

栖界开放平台 · API Documentation