Common APIs
These APIs are shared by Smart Consultation and Image Recognition. All paths are relative to:
https://open-api.habitaxx.com/v1/ms-ai-fastExcept for image upload, JSON endpoints use Authorization: Bearer <ACCESS_TOKEN> and Content-Type: application/json.
The Runtime also reads the user-context header x-qj-user and uses it to scope sessions, media assets, and reports. The service does not authenticate this header and does not parse Authorization.
When calling the Runtime directly, also send:
x-qj-user: <USER_UUID>The service itself does not validate Authorization; the user identity comes entirely from x-qj-user, which the open-platform gateway injects after validating the bearer token. External developers send Authorization per the gateway contract and must never forge or modify x-qj-user; a direct backend call without that header is rejected.
Detailed Report Fields & UI Mapping
For complete field definitions and UI block mapping (reviews, body map highlights, 3-stage treatments, vet orders), please refer to Report Fields & UI Mapping.
List available languages
/localesRequest URL:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/localesResponse example
{
"code": 200,
"message": "success",
"data": ["zh-CN", "zh-Hant-HK", "en-US"]
}data is the list of language codes enabled in the target environment. Use one of these values when creating a session.
The response message values below are the actual backend strings returned by the current service; they are not translated by this English page.
Upload an image
/oss/imagesRequest URL:
POST https://open-api.habitaxx.com/v1/ms-ai-fast/oss/imagesForm data
Send multipart/form-data with a required field named file.
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Image file; supports jpg, jpeg, png, webp, and gif; maximum 10 MiB. |
Response example
{
"code": 200,
"message": "success",
"data": {
"media_type": "image",
"file_name": "server-generated-name.jpg",
"object_key": "test/ai-doc/server-generated-name.jpg",
"content_type": "image/jpeg",
"size_bytes": 245810,
"etag": "<ETAG>",
"url": "<UPLOAD_RESPONSE_DATA_URL>"
}
}Use the exact url value in later img_url or image fields. Do not use a third-party URL, a reconstructed OSS URL, another user's asset, or a URL with a query string or fragment.
Saving the user answer has its own page: Save the user's answer.
List session messages
/session-records/sessions/{session_id}/messagessession_id is a path parameter. page, limit, and the other filters are query parameters.
Request URL:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/session-records/sessions/<SESSION_ID>/messages?page=1&limit=20&include_hidden=false&exclude_stage_8=trueQuery parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | integer | No | 1 | Page number, minimum 1. |
limit | integer | No | 20 | Page size, maximum 200. |
module_type | integer | No | - | Filter by module. |
include_hidden | boolean | No | false | Include hidden messages. |
exclude_stage_8 | boolean | No | true | Exclude stage-8 messages. |
Response example
{
"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": "No food change recently.",
"content_type": 1,
"stage": null,
"parent_session": null,
"image": null,
"evaluation": null,
"extra_json": null,
"is_hidden": 0
}
]
}Response fields
The response data is an array of messages in ascending time order; the table lists the item fields.
| Field | Type | Description |
|---|---|---|
[].id | integer | Message ID. |
[].session_id | string | Session ID. |
[].role | string | user, assistant, or system. |
[].content | string | Message text or a JSON string. |
[].content_type | integer | 1 text, 2 image, 3 JSON. |
[].module_type | integer | 1 consultation, 5 image recognition. |
[].stage | integer/null | Business stage. |
[].parent_session | string/null | Parent session ID. |
[].image | string/null | Image URL for image messages. |
[].extra_json | object/null | Extended payload. |
[].is_hidden | integer | Whether the message is hidden: 0 no, 1 yes. |
[].evaluation | object/null | Evaluation payload. |
[].created_at / [].updated_at | datetime | Creation and update time. |
[].user_uuid | string | Platform-internal user identifier; do not use externally. |
The response contains only code, message and data — no total and no page_info; to detect another page, compare the number of returned items with limit.
Query an asynchronous task
/ai-tasks/{task_id}task_id is a path parameter, not a query parameter. This endpoint has no request body.
Request URL:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/ai-tasks/<TASK_ID>Response fields
| Field | Type | Description |
|---|---|---|
task_id | string | Task ID. |
task_type | string | Task type. |
status | string | pending, processing, retrying, succeeded, failed, or canceled. |
progress | integer | Progress value. |
result_payload_json | object/null | Public result summary. |
error_code | integer/null | Public numeric error code; only present when the task failed, null otherwise. |
started_at / finished_at | datetime/null | Start and finish times. |
created_at / updated_at | datetime/null | Creation and update times. |
The task object no longer returns error_key, error_message, retryable, or recommended_action; check the task-level error code table for retryability.
Response example
{
"code": 200,
"message": "success",
"data": {
"task_id": "<TASK_ID>",
"task_type": "ai_doc_report_generate",
"status": "succeeded",
"progress": 100,
"result_payload_json": {"report_type": 1},
"error_code": null,
"started_at": "2026-09-14T10:10:01+08:00",
"finished_at": "2026-09-14T10:10:08+08:00",
"created_at": "2026-09-14T10:10:00+08:00",
"updated_at": "2026-09-14T10:10:08+08:00"
}
}pending, processing, and retrying are non-terminal. succeeded, failed, and canceled are terminal; stop polling only at a terminal status.
When a task fails, the HTTP status and code are still 200: detect failure from data.status (failed / canceled only), then read the cause from data.error_code; see task-level error codes.
Retry a failed task
/ai-tasks/{task_id}/retryWhen a task is failed, call this endpoint to submit the same task again. Check the task-level error code table first: retry only codes that are marked retryable. There is no request body; task_id is a path parameter.
Request URL:
POST https://open-api.habitaxx.com/v1/ms-ai-fast/ai-tasks/<TASK_ID>/retryRequest headers:
Authorization: Bearer <ACCESS_TOKEN>Response example
{
"code": 200,
"message": "success",
"data": {
"task_id": "<TASK_ID>",
"task_type": "ai_doc_report_generate",
"status": "pending",
"progress": 0,
"result_payload_json": null,
"error_code": null,
"started_at": null,
"finished_at": null,
"created_at": "2026-09-14T10:10:00+08:00",
"updated_at": "2026-09-14T10:30:12+08:00"
}
}The response fields are identical to Query an asynchronous task: after a successful retry the status goes back to pending, so keep polling with the query endpoint.
When retrying is allowed:
| Task status | Retryable | Notes |
|---|---|---|
failed with a retryable code | Yes | Call this endpoint to submit the task again (see the retryable column in the error code table). |
failed with a non-retryable code | No | A retry cannot succeed; fix the input or inform the user according to the code. |
processing / retrying | No | The task is still running; keep polling. |
succeeded | Not needed | Read the report directly. |
Retrieve a complete report
/medical-recordProvide exactly one of report_id and session_id.
Request URL:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-record?session_id=<SESSION_ID>or:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-record?report_id=10001Response example
{
"code": 200,
"message": "success",
"data": {
"report_id": 10001,
"session_id": "<SESSION_ID>",
"pet_profile_id": 44,
"module_type": 1,
"report_status": 2,
"summary": "Based on the current information, continue monitoring the vomiting frequency.",
"report_url": null,
"report": {"content": "Complete consultation report"},
"report_info": {
"title": "Smart Consultation Report",
"content": "Complete consultation report",
"report_url": null,
"img_url": null
},
"report_contents": []
}
}Common response fields
| Field | Type | Description |
|---|---|---|
report_id | integer | Report ID. |
session_id | string | Business session ID. |
pet_profile_id | integer/null | Pet-profile ID. |
module_type / sub_module_type | integer/null | AI module and image-recognition subtype. |
report_status | integer | 0 not started, 1 processing, 2 succeeded, 3 failed, 4 canceled, 5 image rejected. |
summary | string/null | Result summary. |
report | object/string/null | Final aggregated report. |
report_info | object/null | Report presentation information. |
report_info.title | string | Report card title. |
report_info.content | string | Report card content. |
report_info.report_url | string/null | Report file URL. |
report_info.img_url | string/null | Image URL used by the report. |
report_contents | object[] | Report fragments. |
report_contents[].id | integer | Fragment ID. |
report_contents[].medical_record_id | integer | Owning AI record ID. |
report_contents[].report_index | integer | Fragment index matching the report_type used when creating the report task (measured 1, 2, 3, 4, 5, 7 — not consecutive; sort by index, not array position). Fragment meanings are listed in Create a consultation report task. |
report_contents[].content | string | Fragment content, usually a JSON string. |
report_contents[].content_hash | string | Content hash. |
report_contents[].gateway_request_id | string/null | Gateway request ID that produced the fragment. |
report_contents[].created_at / updated_at | datetime | Creation and update time. |
id | integer | Record ID; identical to report_id. |
pet_info | object/null | Pet snapshot (id, name, avatar). |
lang | string | Session language. |
stage | string/null | Consultation stage snapshot (measured: 1 for the message created with the session, 2 when saving a user answer). |
status | integer | Business status (measured: 1 right after session creation, 2 once the report is done); use report_status to decide whether the report is complete. |
report_type | string/null | Report version string (measured v1). Not the same field as the numeric report_type (1/2/3/4/7) used when creating a report task. |
report_url | string/null | Report URL. |
report_time | datetime/null | Time the report was generated. |
is_paid | integer | Whether the record is paid: 0 no, 1 yes. |
trace_id | string/null | Trace ID. |
created_at / updated_at | datetime | Creation and update time. |
image_recognition_status | integer | Deprecated; mirrors report_status. |
is_del / user_uuid | integer / string | Platform-internal fields; do not use externally. |
List business records
/medical-recordsList the current user's AI business records (consultation, image recognition and so on) with page-based pagination. Use module_type=5 to list image-recognition history.
Request URL:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-records?page=1&limit=20&module_type=5Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number, default 1. |
limit | integer | No | Page size, default 10, maximum 200. |
module_type | integer | No | Module type; 1 for consultation, 5 for image recognition. |
sub_module_type | integer | No | Image-recognition subtype, 1 through 8. |
pet_profile_id | integer | No | Filter by pet profile. |
status | integer | No | Business status (measured: 1 right after session creation, 2 once the report is done); use report_status to decide whether the report is complete. |
report_status | integer | No | Report status: 0 not started, 1 processing, 2 succeeded, 3 failed, 4 canceled, 5 image rejected. |
Response example
{
"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": "Image recognition 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"
}
]
}Response fields
The response data is an array of business records; the table lists the item fields.
| Field | Type | Description |
|---|---|---|
[].session_id | string | Session ID. |
[].pet_profile_id | integer/null | Pet-profile ID. |
[].module_type | integer | Module type: 1 consultation, 5 image recognition. |
[].sub_module_type | integer/null | Image-recognition subtype. |
[].status | integer | Business status (measured: 1 after session creation, 2 once the report is done); report_status is authoritative. |
[].report_status | integer | Report status, same values as above. |
[].lang | string | Session language. |
[].summary | string/null | Consultation or recognition summary. |
[].report_time | datetime/null | Time the report was generated. |
[].id | integer | Record ID; identical to the report ID. |
[].report_type | string/null | Report version string (measured v1). |
[].report_url | string/null | Report URL. |
[].stage | string/null | Consultation stage snapshot (measured: 1 session creation, 2 saving an answer). |
[].is_paid | integer | Whether the record is paid: 0 no, 1 yes. |
[].trace_id | string/null | Trace ID. |
[].created_at / [].updated_at | datetime | Creation and update time. |
[].image_recognition_status | integer | Deprecated; mirrors report_status. |
[].is_del / [].user_uuid | integer / string | Platform-internal fields; do not use externally. |
Get business record details
/medical-records/{record_id}Read one business record and its report fragments by record ID. record_id is the report ID (report_id).
Request URL:
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-records/10001Response example
{
"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": "Image recognition 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": "Report fragment content"
}
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
record | object | Business record; field meanings are the same as in List business records. |
report_contents | object[] | Report fragments. |
Which report endpoint should I use?
| Need | Endpoint |
|---|---|
| Complete report, session ID known | GET /medical-record?session_id=... |
| Complete report, report ID known | GET /medical-record?report_id=... |
| History list filtered by type or profile | GET /medical-records?module_type=5&... |
| Record details and fragments, record ID known | GET /medical-records/{record_id} |