调用约定
服务地址
https://open-api.habitaxx.com业务接口统一前缀 /v1/ms-ai-fast:
https://open-api.habitaxx.com/v1/ms-ai-fast例:
POST https://open-api.habitaxx.com/v1/ms-ai-fast/session-records/sessions请求头
| 请求头 | 值 | 说明 |
|---|---|---|
Authorization | Bearer <ACCESS_TOKEN> | 所有业务接口必填;由开放平台网关校验(服务端只信任网关注入的 x-qj-user)。 |
Content-Type | application/json | 有 JSON 请求体时必填。 |
Accept | text/event-stream | 流式接口(reason-info、if-continue-ask、summary、ai-pic/summary/stream)必填。 |
图片上传使用 multipart/form-data,让 HTTP 客户端自动生成带 boundary 的 Content-Type。
统一响应
所有 JSON 接口(含失败)都是同一结构:
{
"code": 200,
"message": "success",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 200 表示成功;失败时与 HTTP 状态码一致(如 404、422)。 |
message | string | 状态提示信息:成功固定为 "success"(网关统一归一化),失败时为安全的中文提示。不要用它做程序判断。 |
data | any | 业务数据;失败时为 null。 |
成功判定:HTTP 2xx 且 code == 200。失败形态与错误码见错误处理。
响应体只有 code、message、data 三个字段:网关不会下发 success、error_code、error_key、retryable、recommended_action。异步任务失败时 HTTP 与 code 仍是 200,必须解析 data.status 判断。
本文档「返回字段」表列出的是响应 data 内部的字段路径(不再重复外层 data.):数组项的字段用 [] 前缀表示(如 [].session_id),嵌套对象保留层级(如 task.task_id、report_contents[].id)。
流式响应
reason-info、if-continue-ask、summary、ai-pic/summary/stream 返回 text/event-stream。
响应头(经开放平台网关实测):
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache
Transfer-Encoding: chunked响应不返回 Content-Length,必须按流式读取(逐帧处理,不要等整个响应结束)。服务端另会设置 X-Accel-Buffering: no 供自建反向代理使用,经网关后通常不透出;自建代理请关闭响应缓冲(如 proxy_buffering off),否则流式输出会被攒到最后一次性返回。
帧格式:每个事件是一行 data: {...},事件块之间以空行分隔;事件类型在 JSON 的 type 字段里,不使用 event: 行。
| 事件类型 | 说明 | 是否终止 |
|---|---|---|
metadata | 流开始,一个流只有一次,带 gateway_request_id(本地或服务端异常流可能带 source) | 否 |
content | 中间文本,可多次;只用于逐段展示,不能据此判断结束 | 否 |
done | 正常结束,data 为最终结果;只有收到它才算成功 | 是 |
error | 失败结束,带 code、error_code、message、retryable、recommended_action | 是 |
done 与 error 互斥,任何流都必须以其中之一结束。以下情况都算失败:首个事件不是 metadata;收到重复 metadata;出现未知事件类型;连接关闭但没有终止事件;done 的 data 无法解析。各接口 data 的具体结构见对应接口页。
分页
列表接口用 page + limit(不是游标分页,参数名不是 page_size):
| 参数 | 默认 | 上限 |
|---|---|---|
page | 1 | — |
limit | 10 | 200 |
响应只返回数组,不返回 total / page_info。需要总数时自行累计,或用"返回条数是否等于 limit"判断是否还有下一页。
时间与字段格式
- 时间字段是 ISO 8601 字符串。不带偏移的字段含义不一致,必须区分:
created_at、updated_at、report_time(业务表):东八区墙上时间,例如2026-09-16T14:55:31;started_at、finished_at(AI 任务):UTC;同一个任务实测created_at为14:56:21、started_at为06:56:21,相差 8 小时;- 两者都不带
+08:00后缀,混用会让时间判断整体偏差 8 小时。
- ID 为数值(如
pet_profile_id: 44)或平台生成的字符串(session_id、task_id)。 weight是带单位的字符串,例如"4.20kg",不是 JSON number。- 状态、类型字段为整数;
is_pic、content之类 AI 决策字段是字符串"True"/"False",不是布尔值。
会话、任务与报告 ID
| 标识 | 用途 |
|---|---|
session_id | 串联一次问诊或识别流程;创建会话时返回。 |
task_id | 轮询异步任务进度与错误:GET /ai-tasks/{task_id}。 |
report_id | 读取最终报告;等同于 AI 主记录 ID。 |
gateway_request_id | 平台侧链路 ID,排查问题时提供。 |
trace_id | 接入方可选链路标识,可按自己的规则生成。 |
幂等与重复提交
后端按会话做了冲突保护,接入方按下面规则调用即可避免绝大多数 400 错误:
| 场景 | 规则 |
|---|---|
| 报告任务 | 同一会话只提交一次(问诊 POST /ai-doc/report、识别 POST /ai-pic/sessions/report-tasks);失败用 POST /ai-tasks/{task_id}/retry 重试,不要重复提交。 |
| 图片资产 | img_url 只能是当前用户刚上传并登记成功的 url 原值;不要换图重试。 |
| 识别类型 | sub_module_type 在会话创建时固定,同一 session_id 不能更换。 |
| 会话语言 | 后续请求的 lang 必须与创建会话一致,建议直接省略。 |
| 用户回答 | 同一轮回答只保存一次;客户端重试时不要重复调用 POST /session-records/messages。 |
冲突类错误返回 400,任务级冲突码为 6001 / 6102 / 6103 / 6106(见错误处理)。
超时建议
| 调用类型 | 建议读取超时 | 说明 |
|---|---|---|
| 普通 JSON(档案、预设问题、保存消息) | 20–60 秒 | 失败直接按错误码处理。 |
同步 AI 接口(keywords、analysis、related-question、if-need-image、pic-result) | 180 秒 | 模型推理耗时较长。 |
| 流式接口(SSE) | 180 秒 | 以收到 done / error 终止事件为准,超时按失败处理。 |
| 图片上传 | 120 秒 | 单文件最大 10 MiB。 |
| 报告任务 | 轮询每 4 秒一次,最长 5 分钟 | 实测报告生成约 20–30 秒。 |
重试原则
- 仅对网络错误、连接超时、
5xx,以及明确标记可重试的错误(SSEerror.retryable: true;任务按错误码表的retryable列判断)重试。 - 流式接口失败重试时要重新发起整个流,不要把已收到的
content当作结果。 - 写操作重试前先确认上一次调用的结果,避免重复创建会话或任务。
429按退避处理,不要高频重试。
仅从服务端调用
API Key 与 ACCESS_TOKEN 是项目级凭证。不要写入网页、移动端安装包、公开仓库或日志。