公共接口
以下接口被智能问诊和宠物特征识别共用。所有接口地址均基于:
https://open-api.habitaxx.com/v1/ms-ai-fast除图片上传外,JSON 接口请求头为:
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json当前 Runtime 还要求用户上下文请求头:
x-qj-user: <USER_UUID>服务本身不校验 Authorization,用户身份完全取自 x-qj-user:由开放平台网关校验 Bearer 后注入。外部开发者按网关约定发送 Authorization 即可,不要自行伪造或修改 x-qj-user;直接调用服务而缺少该请求头时请求会失败。
报告全字段与前端页面映射
报告包含病情回顾、诊断部位图、三阶段治疗方案等丰富层级。前端研发与页面接入同学请参考专门的 问诊报告字段详解与页面映射。
查询可用语言
返回示例
{
"code": 200,
"message": "success",
"data": ["zh-CN", "zh-Hant-HK", "en-US"]
}data 是当前环境启用的语言代码列表。创建会话时使用其中一个语言代码;实际可用值以本接口当前响应为准。
统一媒体上传
此接口用于在各类流程中安全上传各种类型的物理文件资产到开放平台。
系统内置智能校验拦截防伪装木马文件,不执行直接持久化入库,通过校验的文件数据将被存放在 OSS 中,最终向调用方透出安全的可用链接以供后续使用。
请求参数
请求表单 (Form-Data)
请求包含 multipart/form-data:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | 本地需上传的文件二进制实体。 |
Query 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
media_type | string | 否 | image | 限定物理层面上允许的格式类别。支持 image、video、audio、document (仅限 PDF)。系统会底层做强校验,与文件实体验证冲突将拦截报错。 |
domain | string | 是 | - | 业务所在的大主域结构。如 ai(智能分析)、profile(资料身份)、trade(交易财务)。 |
purpose | string | 是 | - | 具体的文件用途标识。必填枚举限制:比如 pic:skin(AI看图-皮肤病)、pet:avatar(档案-宠物头像)、order:proof(交易-汇款凭证) 。 |
领域与用途(Domain/Purpose)规范说明
1. 智能诊断域 (domain=ai)
| 算法主侧 | 细分部位/场景 | 推荐 purpose | 限制 (media_type) |
|---|---|---|---|
| 图片识别(pic) | 面部与表情识别 | pic:face | JPG/PNG/WebP (image) |
| 品种鉴定识别 | pic:breed | JPG/PNG/WebP (image) | |
| 牙齿与口腔问题 | pic:tooth | JPG/PNG/WebP (image) | |
| 皮肤与毛发病变 | pic:skin | JPG/PNG/WebP (image) | |
| 呕吐物性状诊断 | pic:vomit | JPG/PNG/WebP (image) | |
| 大便性状分析 | pic:faeces | JPG/PNG/WebP (image) | |
| 耳道与耳廓健康 | pic:ear | JPG/PNG/WebP (image) | |
| 眼部健康状态 | pic:eye | JPG/PNG/WebP (image) | |
| 视频分析(video) | 步态异常与跛行 | video:gait | MP4/MOV/WebM (video) |
| 异常抽搐/震颤 | video:behavior | MP4/MOV/WebM (video) | |
| 声音分析(voice) | 咳嗽声提取 | voice:cough | MP3/WAV/M4A (audio) |
| 异常呼吸/喘鸣 | voice:breathe | MP3/WAV/M4A (audio) | |
| 叫声情绪分析 | voice:meow | MP3/WAV/M4A (audio) | |
| 智能问诊(doc) | 检验报告补充 | doc:report | PDF/JPG/PNG (document/image) |
2. 身份与档案域 (domain=profile)
| 业务主侧 | 细分实体 | 推荐 purpose | 限制 (media_type) |
|---|---|---|---|
| 宠物档案(pet) | 宠物相册及主头像 | pet:avatar | JPG/PNG/WebP (image) |
3. 系统支撑域 (domain=system) / 其他
| 功能 | 推荐 purpose | 限制 (media_type) |
|---|---|---|
| 底层开放能力调用 | capability_input | 任意有效多媒体格式 |
返回示例
成功返回 200 JSON 或拒绝返回错误:
{
"code": 200,
"message": "success",
"data": {
"url": "https://bucket-name.oss-cn-shanghai.aliyuncs.com/development/ai/pic/skin/images/2026/09/xxx.webp",
"object_key": "development/ai/pic/skin/images/2026/09/xxx.webp",
"file_name": "cat_skin_disease.png",
"media_type": "image",
"domain": "ai",
"purpose": "pic:skin",
"content_type": "image/webp",
"size_bytes": 272188,
"checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
}返回字段释义
| 字段 | 类型 | 说明 |
|---|---|---|
url | string | 核心值,平台底层存储返回的文件全称直连安全调用地址(请以此替代 img_url / attachment_url 发起提交)。 |
object_key | string | OSS 标准对象键结构。 |
media_type | string | 请求落定的归类分组。 |
domain | string | 声明的主业务域。 |
purpose | string | 声明的具体用途。 |
content_type | string | 真实 MIME 指纹。 |
file_name | string | 清洗后的文件原名。 |
size_bytes | int | 真实的字节体积。 |
checksum_sha256 | string | 用于查验对比的哈希值。 |
img_url 必须使用本次上传响应中 url 的原值。不要使用第三方 URL、自行拼接的 OSS 地址或带 query 的地址。
查询会话消息
session_id 是路径参数;page、limit 等为 Query 参数。
Query 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
page | integer | 否 | 1 | 页码,最小 1。 |
limit | integer | 否 | 20 | 每页数量,最大 200。 |
module_type | integer | 否 | - | 按模块过滤。 |
include_hidden | boolean | 否 | false | 是否包含隐藏消息。 |
exclude_stage_8 | boolean | 否 | true | 是否排除阶段 8 的消息。 |
返回示例
{
"code": 200,
"message": "success",
"data": [
{
"id": 2,
"created_at": "2026-09-14T10:05:00+08:00",
"updated_at": "2026-09-14T10:05:00+08:00",
"session_id": "<SESSION_ID>",
"user_uuid": "<USER_UUID>",
"module_type": 1,
"role": "user",
"content": "最近没有更换食物。",
"content_type": 1,
"stage": null,
"parent_session": null,
"image": null,
"evaluation": null,
"extra_json": null,
"is_hidden": 0
}
]
}返回字段
响应 data 为消息数组,按时间升序;下表为数组项字段。
| 字段 | 类型 | 说明 |
|---|---|---|
[].id | integer | 消息 ID。 |
[].session_id | string | 会话 ID。 |
[].role | string | user、assistant 或 system。 |
[].content | string | 消息文本或 JSON 字符串。 |
[].content_type | integer | 1 文本、2 图片、3 JSON。 |
[].module_type | integer | 1 问诊、5 图片识别。 |
[].stage | integer/null | 业务阶段。 |
[].parent_session | string/null | 关联父会话。 |
[].image | string/null | 弃用,图片信息在 content JSON 的 images 列表中。 |
[].evaluation | object/null | 对回答的反馈点赞。 |
[].extra_json | object/null | 其他参数如 message_id。 |
[].is_hidden | integer | 对外不可见标志:0 否、1 是。 |
查询业务记录列表
按页码分页查询当前用户的 AI 业务记录(问诊、图片识别等)。图片识别的历史记录用 module_type=5 查询。
Query 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | integer | 否 | 页码,默认 1。 |
limit | integer | 否 | 每页数量,默认 10,最大 200。 |
module_type | integer | 否 | 模块类型;问诊为 1,图片识别为 5。 |
sub_module_type | integer | 否 | 图片识别子类型 1 至 8。 |
pet_profile_id | integer | 否 | 按宠物档案过滤。 |
status | integer | 否 | 业务状态;报告是否完成请以 report_status 为准。 |
report_status | integer | 否 | 报告状态:0 未开始、1 处理中、2 成功、3 失败、4 已取消、5 图片不合格。 |
返回示例
{
"code": 200,
"message": "success",
"data": [
{
"session_id": "<SESSION_ID>",
"user_uuid": "<USER_UUID>",
"pet_profile_id": 44,
"module_type": 5,
"sub_module_type": 6,
"stage": null,
"status": 1,
"report_status": 2,
"report_type": null,
"lang": "zh-CN",
"summary": "图片识别小结",
"report_url": null,
"report_time": "2026-09-14T10:10:08+08:00",
"created_at": "2026-09-14T10:09:50+08:00",
"updated_at": "2026-09-14T10:10:08+08:00"
}
]
}返回字段
响应 data 为业务记录数组;下表为数组项字段。
| 字段 | 类型 | 说明 |
|---|---|---|
[].session_id | string | 会话 ID。 |
[].pet_profile_id | integer/null | 宠物档案 ID。 |
[].module_type | integer | 模块类型:1 问诊、5 图片识别。 |
[].sub_module_type | integer/null | 图片识别子类型。 |
[].status | integer | 会话状态。 |
[].report_status | integer | 报告状态。 |
[].lang | string | 会话语言。 |
[].summary | string/null | 识别小结。 |
[].report_time | datetime/null | 报告生成时间。 |
[].id | integer | 记录 ID,等同于报告 ID。 |
[].report_type | string/null | 报告版本。 |
[].report_url | string/null | 报告 URL。 |
[].stage | string/null | 问诊阶段快照。 |
[].is_paid | integer | 是否付费:0 否、1 是。 |
[].trace_id | string/null | 链路 ID。 |
[].created_at / [].updated_at | datetime | 创建与更新时间。 |
[].image_recognition_status | integer | 已弃用,兼容返回 report_status。 |
查询业务记录详情
按记录 ID 查询单条业务记录及其报告分片。record_id 即报告 ID(report_id)。
返回示例
{
"code": 200,
"message": "success",
"data": {
"record": {
"session_id": "<SESSION_ID>",
"user_uuid": "<USER_UUID>",
"pet_profile_id": 44,
"module_type": 5,
"sub_module_type": 6,
"status": 1,
"report_status": 2,
"lang": "zh-CN",
"summary": "图片识别小结",
"report_time": "2026-09-14T10:10:08+08:00",
"created_at": "2026-09-14T10:09:50+08:00",
"updated_at": "2026-09-14T10:10:08+08:00"
},
"report_contents": [
{
"id": 1,
"content": "报告分片内容"
}
]
}
}返回字段
| 字段 | 类型 | 说明 |
|---|---|---|
record | object | 业务记录对象,字段含义同查询业务记录列表。 |
report_contents | object[] | 报告分片列表。 |
三个报告查询接口怎么选
| 需求 | 用哪个接口 |
|---|---|
| 已知会话 ID,要完整报告 | GET /medical-record?session_id=... |
| 已知报告 ID,要完整报告 | GET /medical-record?report_id=... |
| 列出历史记录(按类型/档案筛选) | GET /medical-records?module_type=5&... |
| 已知记录 ID,要记录详情与分片 | GET /medical-records/{record_id} |