Skip to content

API Conventions ​

Base URL ​

BASE_URLhttps://open-api.habitaxx.com

Business APIs share the prefix /v1/ms-ai-fast:

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

Example:

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

Request headers ​

HeaderValueNotes
AuthorizationBearer <ACCESS_TOKEN>Required for every business endpoint; validated by the open-platform gateway (the service itself trusts only the injected x-qj-user).
Content-Typeapplication/jsonRequired when there is a JSON body.
Accepttext/event-streamRequired 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:

json
{
  "code": 200,
  "message": "success",
  "data": {}
}
FieldTypeDescription
codeinteger200 means success; on failure it matches the HTTP status (for example 404, 422).
messagestringStatus text: always "success" on success (normalised by the gateway) and a safe Chinese message on failure. Do not use it for program logic.
dataanyBusiness 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):

http
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache
Transfer-Encoding: chunked

There 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 typeDescriptionTerminates the stream
metadataStream start, exactly once per stream, carrying gateway_request_id (locally generated error streams may carry source instead)No
contentIntermediate text, may repeat; for incremental display only, never to decide completionNo
doneNormal end, data holds the final result; only this means successYes
errorFailure end, carrying code, error_code, message, retryable, recommended_actionYes

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

ParameterDefaultMaximum
page1—
limit10200

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 example 2026-09-16T14:55:31;
    • started_at, finished_at (AI tasks): UTC; in one measured task created_at was 14:56:21 while started_at was 06:56:21 — eight hours apart;
    • neither carries a +08:00 suffix, 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).
  • weight is a unit-bearing string such as "4.20kg", not a JSON number.
  • Status and type fields are integers; AI decision fields such as is_pic and content are the strings "True" / "False", not booleans.

Sessions, tasks and reports ​

IdentifierPurpose
session_idCorrelates one consultation or recognition flow; returned when the session is created.
task_idPolls asynchronous progress and errors: GET /ai-tasks/{task_id}.
report_idRetrieves the final report; identical to the AI record ID.
gateway_request_idPlatform-side trace ID to quote when reporting an issue.
trace_idOptional client-generated trace identifier.

Idempotency and duplicate submissions ​

The backend protects against conflicts per session. Follow these rules to avoid most 400 responses:

CaseRule
Report taskSubmit 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 assetimg_url must be the exact url of an image the current user just uploaded; do not swap images on retry.
Recognition typesub_module_type is fixed at session creation and cannot change within one session_id.
Session languageLater requests must use the session language; omitting lang is recommended.
User answerSave 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).

Call typeRead timeoutNotes
Plain JSON (profiles, starter questions, saving messages)20–60 sHandle failures by error code.
Synchronous AI (keywords, analysis, related-question, if-need-image, pic-result)180 sModel inference takes longer.
Streaming (SSE)180 sSuccess is defined by the done / error terminal event; a timeout is a failure.
Image upload120 sMaximum 10 MiB per file.
Report taskPoll every 4 s, up to 5 minutesMeasured report generation is about 20–30 s.

Retry policy ​

  • Retry only network errors, connection timeouts, 5xx, and explicitly retryable errors (SSE error.retryable: true; for tasks use the retryable column of the error code table).
  • When a streaming call fails, restart the whole stream; never treat received content as the result.
  • Confirm the previous outcome before retrying a write, so sessions or tasks are not created twice.
  • Handle 429 with 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.

最近更新

Qijie Open Platform · API Documentation