Skip to content

调用约定 ​

服务地址 ​

BASE_URLhttps://open-api.habitaxx.com

业务接口统一前缀 /v1/ms-ai-fast:

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

例:

text
POST https://open-api.habitaxx.com/v1/ms-ai-fast/session-records/sessions

请求头 ​

请求头值说明
AuthorizationBearer <ACCESS_TOKEN>所有业务接口必填;由开放平台网关校验(服务端只信任网关注入的 x-qj-user)。
Content-Typeapplication/json有 JSON 请求体时必填。
Accepttext/event-stream流式接口(reason-info、if-continue-ask、summary、ai-pic/summary/stream)必填。

图片上传使用 multipart/form-data,让 HTTP 客户端自动生成带 boundary 的 Content-Type。

统一响应 ​

所有 JSON 接口(含失败)都是同一结构:

json
{
  "code": 200,
  "message": "success",
  "data": {}
}
字段类型说明
codeinteger200 表示成功;失败时与 HTTP 状态码一致(如 404、422)。
messagestring状态提示信息:成功固定为 "success"(网关统一归一化),失败时为安全的中文提示。不要用它做程序判断。
dataany业务数据;失败时为 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。

响应头(经开放平台网关实测):

http
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):

参数默认上限
page1—
limit10200

响应只返回数组,不返回 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,以及明确标记可重试的错误(SSE error.retryable: true;任务按错误码表的 retryable 列判断)重试。
  • 流式接口失败重试时要重新发起整个流,不要把已收到的 content 当作结果。
  • 写操作重试前先确认上一次调用的结果,避免重复创建会话或任务。
  • 429 按退避处理,不要高频重试。

仅从服务端调用

API Key 与 ACCESS_TOKEN 是项目级凭证。不要写入网页、移动端安装包、公开仓库或日志。

最近更新

栖界开放平台 · API Documentation