API Conventions
Base URL
https://open-api.habitaxx.comBusiness APIs share the prefix /v1/ms-ai-fast:
https://open-api.habitaxx.com/v1/ms-ai-fastExample:
POST https://open-api.habitaxx.com/v1/ms-ai-fast/session-records/sessionsRequest headers
| Header | Value | Notes |
|---|---|---|
Authorization | Bearer <ACCESS_TOKEN> | Required for every business endpoint; validated by the open-platform gateway (the service itself trusts only the injected x-qj-user). |
Content-Type | application/json | Required when there is a JSON body. |
Accept | text/event-stream | Required for streaming endpoints (reason-info, if-continue-ask, summary, ai-pic/summary/stream). |
Image upload uses multipart/form-data; let the HTTP client generate the Content-Type with its boundary.
Response envelope
Every JSON endpoint (including failures) uses one shape:
{
"code": 200,
"message": "success",
"data": {}
}| Field | Type | Description |
|---|---|---|
code | integer | 200 means success; on failure it matches the HTTP status (for example 404, 422). |
message | string | Status text: always "success" on success (normalised by the gateway) and a safe Chinese message on failure. Do not use it for program logic. |
data | any | Business payload; null on failure. |
Treat a call as successful when the HTTP status is 2xx and code == 200. Failure shapes and error codes are in Error Handling.
The envelope has only code, message and data: the gateway never sends success, error_code, error_key, retryable or recommended_action. When an asynchronous task fails, the HTTP status and code are still 200, so you must parse data.status.
message values are returned by the platform in Chinese (for example 宠物档案不存在或无权限); use code for programmatic decisions and treat message as display text.
Field tables in this documentation list paths inside the response data (the outer data. is not repeated): array-item fields use the [] prefix (for example [].session_id), and nested objects keep their levels (for example task.task_id, report_contents[].id).
Streaming responses (SSE)
reason-info, if-continue-ask, summary and ai-pic/summary/stream return text/event-stream.
Response headers (measured through the open-platform gateway):
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache
Transfer-Encoding: chunkedThere is no Content-Length, so read the response as a stream (frame by frame, not after it completes). The service also sets X-Accel-Buffering: no for self-hosted reverse proxies; the gateway normally does not expose it, so disable response buffering in your own proxy (proxy_buffering off) or streamed output is held back until the end.
Frame format: each event is a single data: {...} line and event blocks are separated by a blank line; the event type lives in the JSON type field, and no event: line is used.
| Event type | Description | Terminates the stream |
|---|---|---|
metadata | Stream start, exactly once per stream, carrying gateway_request_id (locally generated error streams may carry source instead) | No |
content | Intermediate text, may repeat; for incremental display only, never to decide completion | No |
done | Normal end, data holds the final result; only this means success | Yes |
error | Failure end, carrying code, error_code, message, retryable, recommended_action | Yes |
done and error are mutually exclusive and every stream ends with one of them. Treat all of these as failures: the first event is not metadata; metadata arrives twice; an unknown event type appears; the connection closes without a terminal event; the data of done cannot be parsed. The concrete shape of data is documented on each endpoint page.
Pagination
List endpoints use page + limit (not cursor pagination, and the parameter is not page_size):
| Parameter | Default | Maximum |
|---|---|---|
page | 1 | — |
limit | 10 | 200 |
The response contains only the array — no total and no page_info. Count results on your side, or use "does the page length equal limit" to detect another page.
Time and field formats
- Timestamps are ISO 8601 strings. Fields without an offset do not share one meaning — always distinguish them:
created_at,updated_at,report_time(business tables): UTC+8 wall-clock time, for example2026-09-16T14:55:31;started_at,finished_at(AI tasks): UTC; in one measured taskcreated_atwas14:56:21whilestarted_atwas06:56:21— eight hours apart;- neither carries a
+08:00suffix, so mixing them shifts every calculation by eight hours.
- IDs are numbers (for example
pet_profile_id: 44) or platform-generated strings (session_id,task_id). weightis a unit-bearing string such as"4.20kg", not a JSON number.- Status and type fields are integers; AI decision fields such as
is_picandcontentare the strings"True"/"False", not booleans.
Sessions, tasks and reports
| Identifier | Purpose |
|---|---|
session_id | Correlates one consultation or recognition flow; returned when the session is created. |
task_id | Polls asynchronous progress and errors: GET /ai-tasks/{task_id}. |
report_id | Retrieves the final report; identical to the AI record ID. |
gateway_request_id | Platform-side trace ID to quote when reporting an issue. |
trace_id | Optional client-generated trace identifier. |
Idempotency and duplicate submissions
The backend protects against conflicts per session. Follow these rules to avoid most 400 responses:
| Case | Rule |
|---|---|
| Report task | Submit once per session (consultation POST /ai-doc/report, recognition POST /ai-pic/sessions/report-tasks). Retry failures with POST /ai-tasks/{task_id}/retry instead of submitting again. |
| Image asset | img_url must be the exact url of an image the current user just uploaded; do not swap images on retry. |
| Recognition type | sub_module_type is fixed at session creation and cannot change within one session_id. |
| Session language | Later requests must use the session language; omitting lang is recommended. |
| User answer | Save each round's answer once; do not repeat POST /session-records/messages on a client retry. |
Conflicts return 400, and the task-level conflict codes are 6001 / 6102 / 6103 / 6106 (see Error Handling).
Recommended timeouts
| Call type | Read timeout | Notes |
|---|---|---|
| Plain JSON (profiles, starter questions, saving messages) | 20–60 s | Handle failures by error code. |
Synchronous AI (keywords, analysis, related-question, if-need-image, pic-result) | 180 s | Model inference takes longer. |
| Streaming (SSE) | 180 s | Success is defined by the done / error terminal event; a timeout is a failure. |
| Image upload | 120 s | Maximum 10 MiB per file. |
| Report task | Poll every 4 s, up to 5 minutes | Measured report generation is about 20–30 s. |
Retry policy
- Retry only network errors, connection timeouts,
5xx, and explicitly retryable errors (SSEerror.retryable: true; for tasks use theretryablecolumn of the error code table). - When a streaming call fails, restart the whole stream; never treat received
contentas the result. - Confirm the previous outcome before retrying a write, so sessions or tasks are not created twice.
- Handle
429with backoff; do not retry in a tight loop.
Server-side use only
API Key and ACCESS_TOKEN are project-level credentials. Never embed them in web pages, mobile packages, public repositories, or logs.