Skip to content

公共接口 ​

以下接口被智能问诊和宠物特征识别共用。所有接口地址均基于:

text
https://open-api.habitaxx.com/v1/ms-ai-fast

除图片上传外,JSON 接口请求头为:

http
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

当前 Runtime 还要求用户上下文请求头:

http
x-qj-user: <USER_UUID>

服务本身不校验 Authorization,用户身份完全取自 x-qj-user:由开放平台网关校验 Bearer 后注入。外部开发者按网关约定发送 Authorization 即可,不要自行伪造或修改 x-qj-user;直接调用服务而缺少该请求头时请求会失败。

报告全字段与前端页面映射

报告包含病情回顾、诊断部位图、三阶段治疗方案等丰富层级。前端研发与页面接入同学请参考专门的 问诊报告字段详解与页面映射。

查询可用语言 ​

GET
/locales

返回示例 ​

json
{
  "code": 200,
  "message": "success",
  "data": ["zh-CN", "zh-Hant-HK", "en-US"]
}

data 是当前环境启用的语言代码列表。创建会话时使用其中一个语言代码;实际可用值以本接口当前响应为准。

统一媒体上传 ​

POST
/v1/common/files/upload

此接口用于在各类流程中安全上传各种类型的物理文件资产到开放平台。

系统内置智能校验拦截防伪装木马文件,不执行直接持久化入库,通过校验的文件数据将被存放在 OSS 中,最终向调用方透出安全的可用链接以供后续使用。

请求参数 ​

请求表单 (Form-Data) ​

请求包含 multipart/form-data:

字段类型必填说明
filefile是本地需上传的文件二进制实体。

Query 参数 ​

参数类型必填默认值说明
media_typestring否image限定物理层面上允许的格式类别。支持 image、video、audio、document (仅限 PDF)。系统会底层做强校验,与文件实体验证冲突将拦截报错。
domainstring是-业务所在的大主域结构。如 ai(智能分析)、profile(资料身份)、trade(交易财务)。
purposestring是-具体的文件用途标识。必填枚举限制:比如 pic:skin(AI看图-皮肤病)、pet:avatar(档案-宠物头像)、order:proof(交易-汇款凭证) 。

领域与用途(Domain/Purpose)规范说明 ​

1. 智能诊断域 (domain=ai)

算法主侧细分部位/场景推荐 purpose限制 (media_type)
图片识别(pic)面部与表情识别pic:faceJPG/PNG/WebP (image)
品种鉴定识别pic:breedJPG/PNG/WebP (image)
牙齿与口腔问题pic:toothJPG/PNG/WebP (image)
皮肤与毛发病变pic:skinJPG/PNG/WebP (image)
呕吐物性状诊断pic:vomitJPG/PNG/WebP (image)
大便性状分析pic:faecesJPG/PNG/WebP (image)
耳道与耳廓健康pic:earJPG/PNG/WebP (image)
眼部健康状态pic:eyeJPG/PNG/WebP (image)
视频分析(video)步态异常与跛行video:gaitMP4/MOV/WebM (video)
异常抽搐/震颤video:behaviorMP4/MOV/WebM (video)
声音分析(voice)咳嗽声提取voice:coughMP3/WAV/M4A (audio)
异常呼吸/喘鸣voice:breatheMP3/WAV/M4A (audio)
叫声情绪分析voice:meowMP3/WAV/M4A (audio)
智能问诊(doc)检验报告补充doc:reportPDF/JPG/PNG (document/image)

2. 身份与档案域 (domain=profile)

业务主侧细分实体推荐 purpose限制 (media_type)
宠物档案(pet)宠物相册及主头像pet:avatarJPG/PNG/WebP (image)

3. 系统支撑域 (domain=system) / 其他

功能推荐 purpose限制 (media_type)
底层开放能力调用capability_input任意有效多媒体格式

返回示例 ​

成功返回 200 JSON 或拒绝返回错误:

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"
  }
}

返回字段释义 ​

字段类型说明
urlstring核心值,平台底层存储返回的文件全称直连安全调用地址(请以此替代 img_url / attachment_url 发起提交)。
object_keystringOSS 标准对象键结构。
media_typestring请求落定的归类分组。
domainstring声明的主业务域。
purposestring声明的具体用途。
content_typestring真实 MIME 指纹。
file_namestring清洗后的文件原名。
size_bytesint真实的字节体积。
checksum_sha256string用于查验对比的哈希值。

img_url 必须使用本次上传响应中 url 的原值。不要使用第三方 URL、自行拼接的 OSS 地址或带 query 的地址。

查询会话消息 ​

GET
/session-records/sessions/{session_id}/messages

session_id 是路径参数;page、limit 等为 Query 参数。

Query 参数 ​

参数类型必填默认值说明
pageinteger否1页码,最小 1。
limitinteger否20每页数量,最大 200。
module_typeinteger否-按模块过滤。
include_hiddenboolean否false是否包含隐藏消息。
exclude_stage_8boolean否true是否排除阶段 8 的消息。

返回示例 ​

json
{
  "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 为消息数组,按时间升序;下表为数组项字段。

字段类型说明
[].idinteger消息 ID。
[].session_idstring会话 ID。
[].rolestringuser、assistant 或 system。
[].contentstring消息文本或 JSON 字符串。
[].content_typeinteger1 文本、2 图片、3 JSON。
[].module_typeinteger1 问诊、5 图片识别。
[].stageinteger/null业务阶段。
[].parent_sessionstring/null关联父会话。
[].imagestring/null弃用,图片信息在 content JSON 的 images 列表中。
[].evaluationobject/null对回答的反馈点赞。
[].extra_jsonobject/null其他参数如 message_id。
[].is_hiddeninteger对外不可见标志:0 否、1 是。

查询业务记录列表 ​

GET
/medical-records

按页码分页查询当前用户的 AI 业务记录(问诊、图片识别等)。图片识别的历史记录用 module_type=5 查询。

Query 参数 ​

参数类型必填说明
pageinteger否页码,默认 1。
limitinteger否每页数量,默认 10,最大 200。
module_typeinteger否模块类型;问诊为 1,图片识别为 5。
sub_module_typeinteger否图片识别子类型 1 至 8。
pet_profile_idinteger否按宠物档案过滤。
statusinteger否业务状态;报告是否完成请以 report_status 为准。
report_statusinteger否报告状态:0 未开始、1 处理中、2 成功、3 失败、4 已取消、5 图片不合格。

返回示例 ​

json
{
  "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_idstring会话 ID。
[].pet_profile_idinteger/null宠物档案 ID。
[].module_typeinteger模块类型:1 问诊、5 图片识别。
[].sub_module_typeinteger/null图片识别子类型。
[].statusinteger会话状态。
[].report_statusinteger报告状态。
[].langstring会话语言。
[].summarystring/null识别小结。
[].report_timedatetime/null报告生成时间。
[].idinteger记录 ID,等同于报告 ID。
[].report_typestring/null报告版本。
[].report_urlstring/null报告 URL。
[].stagestring/null问诊阶段快照。
[].is_paidinteger是否付费:0 否、1 是。
[].trace_idstring/null链路 ID。
[].created_at / [].updated_atdatetime创建与更新时间。
[].image_recognition_statusinteger已弃用,兼容返回 report_status。

查询业务记录详情 ​

GET
/medical-records/{record_id}

按记录 ID 查询单条业务记录及其报告分片。record_id 即报告 ID(report_id)。

返回示例 ​

json
{
  "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": "报告分片内容"
      }
    ]
  }
}

返回字段 ​

字段类型说明
recordobject业务记录对象,字段含义同查询业务记录列表。
report_contentsobject[]报告分片列表。

三个报告查询接口怎么选

需求用哪个接口
已知会话 ID,要完整报告GET /medical-record?session_id=...
已知报告 ID,要完整报告GET /medical-record?report_id=...
列出历史记录(按类型/档案筛选)GET /medical-records?module_type=5&...
已知记录 ID,要记录详情与分片GET /medical-records/{record_id}
最近更新

栖界开放平台 · API Documentation