Skip to content

Common APIs ​

These APIs are shared by Smart Consultation and Image Recognition. All paths are relative to:

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

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

http
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 ​

GET/locales

Request URL:

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

Response example ​

json
{
  "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 ​

POST/oss/images

Request URL:

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

Form data ​

Send multipart/form-data with a required field named file.

FieldTypeRequiredDescription
filefileYesImage file; supports jpg, jpeg, png, webp, and gif; maximum 10 MiB.

Response example ​

json
{
  "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 ​

GET/session-records/sessions/{session_id}/messages

session_id is a path parameter. page, limit, and the other filters are query parameters.

Request URL:

text
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=true

Query parameters ​

ParameterTypeRequiredDefaultDescription
pageintegerNo1Page number, minimum 1.
limitintegerNo20Page size, maximum 200.
module_typeintegerNo-Filter by module.
include_hiddenbooleanNofalseInclude hidden messages.
exclude_stage_8booleanNotrueExclude stage-8 messages.

Response example ​

json
{
  "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.

FieldTypeDescription
[].idintegerMessage ID.
[].session_idstringSession ID.
[].rolestringuser, assistant, or system.
[].contentstringMessage text or a JSON string.
[].content_typeinteger1 text, 2 image, 3 JSON.
[].module_typeinteger1 consultation, 5 image recognition.
[].stageinteger/nullBusiness stage.
[].parent_sessionstring/nullParent session ID.
[].imagestring/nullImage URL for image messages.
[].extra_jsonobject/nullExtended payload.
[].is_hiddenintegerWhether the message is hidden: 0 no, 1 yes.
[].evaluationobject/nullEvaluation payload.
[].created_at / [].updated_atdatetimeCreation and update time.
[].user_uuidstringPlatform-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 ​

GET/ai-tasks/{task_id}

task_id is a path parameter, not a query parameter. This endpoint has no request body.

Request URL:

text
GET https://open-api.habitaxx.com/v1/ms-ai-fast/ai-tasks/<TASK_ID>

Response fields ​

FieldTypeDescription
task_idstringTask ID.
task_typestringTask type.
statusstringpending, processing, retrying, succeeded, failed, or canceled.
progressintegerProgress value.
result_payload_jsonobject/nullPublic result summary.
error_codeinteger/nullPublic numeric error code; only present when the task failed, null otherwise.
started_at / finished_atdatetime/nullStart and finish times.
created_at / updated_atdatetime/nullCreation 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 ​

json
{
  "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 ​

POST/ai-tasks/{task_id}/retry

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

text
POST https://open-api.habitaxx.com/v1/ms-ai-fast/ai-tasks/<TASK_ID>/retry

Request headers:

http
Authorization: Bearer <ACCESS_TOKEN>

Response example ​

json
{
  "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 statusRetryableNotes
failed with a retryable codeYesCall this endpoint to submit the task again (see the retryable column in the error code table).
failed with a non-retryable codeNoA retry cannot succeed; fix the input or inform the user according to the code.
processing / retryingNoThe task is still running; keep polling.
succeededNot neededRead the report directly.

Retrieve a complete report ​

GET/medical-record

Provide exactly one of report_id and session_id.

Request URL:

text
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-record?session_id=<SESSION_ID>

or:

text
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-record?report_id=10001

Response example ​

json
{
  "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 ​

FieldTypeDescription
report_idintegerReport ID.
session_idstringBusiness session ID.
pet_profile_idinteger/nullPet-profile ID.
module_type / sub_module_typeinteger/nullAI module and image-recognition subtype.
report_statusinteger0 not started, 1 processing, 2 succeeded, 3 failed, 4 canceled, 5 image rejected.
summarystring/nullResult summary.
reportobject/string/nullFinal aggregated report.
report_infoobject/nullReport presentation information.
report_info.titlestringReport card title.
report_info.contentstringReport card content.
report_info.report_urlstring/nullReport file URL.
report_info.img_urlstring/nullImage URL used by the report.
report_contentsobject[]Report fragments.
report_contents[].idintegerFragment ID.
report_contents[].medical_record_idintegerOwning AI record ID.
report_contents[].report_indexintegerFragment 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[].contentstringFragment content, usually a JSON string.
report_contents[].content_hashstringContent hash.
report_contents[].gateway_request_idstring/nullGateway request ID that produced the fragment.
report_contents[].created_at / updated_atdatetimeCreation and update time.
idintegerRecord ID; identical to report_id.
pet_infoobject/nullPet snapshot (id, name, avatar).
langstringSession language.
stagestring/nullConsultation stage snapshot (measured: 1 for the message created with the session, 2 when saving a user answer).
statusintegerBusiness status (measured: 1 right after session creation, 2 once the report is done); use report_status to decide whether the report is complete.
report_typestring/nullReport 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_urlstring/nullReport URL.
report_timedatetime/nullTime the report was generated.
is_paidintegerWhether the record is paid: 0 no, 1 yes.
trace_idstring/nullTrace ID.
created_at / updated_atdatetimeCreation and update time.
image_recognition_statusintegerDeprecated; mirrors report_status.
is_del / user_uuidinteger / stringPlatform-internal fields; do not use externally.

List business records ​

GET/medical-records

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

text
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-records?page=1&limit=20&module_type=5

Query parameters ​

ParameterTypeRequiredDescription
pageintegerNoPage number, default 1.
limitintegerNoPage size, default 10, maximum 200.
module_typeintegerNoModule type; 1 for consultation, 5 for image recognition.
sub_module_typeintegerNoImage-recognition subtype, 1 through 8.
pet_profile_idintegerNoFilter by pet profile.
statusintegerNoBusiness status (measured: 1 right after session creation, 2 once the report is done); use report_status to decide whether the report is complete.
report_statusintegerNoReport status: 0 not started, 1 processing, 2 succeeded, 3 failed, 4 canceled, 5 image rejected.

Response example ​

json
{
  "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.

FieldTypeDescription
[].session_idstringSession ID.
[].pet_profile_idinteger/nullPet-profile ID.
[].module_typeintegerModule type: 1 consultation, 5 image recognition.
[].sub_module_typeinteger/nullImage-recognition subtype.
[].statusintegerBusiness status (measured: 1 after session creation, 2 once the report is done); report_status is authoritative.
[].report_statusintegerReport status, same values as above.
[].langstringSession language.
[].summarystring/nullConsultation or recognition summary.
[].report_timedatetime/nullTime the report was generated.
[].idintegerRecord ID; identical to the report ID.
[].report_typestring/nullReport version string (measured v1).
[].report_urlstring/nullReport URL.
[].stagestring/nullConsultation stage snapshot (measured: 1 session creation, 2 saving an answer).
[].is_paidintegerWhether the record is paid: 0 no, 1 yes.
[].trace_idstring/nullTrace ID.
[].created_at / [].updated_atdatetimeCreation and update time.
[].image_recognition_statusintegerDeprecated; mirrors report_status.
[].is_del / [].user_uuidinteger / stringPlatform-internal fields; do not use externally.

Get business record details ​

GET/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:

text
GET https://open-api.habitaxx.com/v1/ms-ai-fast/medical-records/10001

Response example ​

json
{
  "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 ​

FieldTypeDescription
recordobjectBusiness record; field meanings are the same as in List business records.
report_contentsobject[]Report fragments.

Which report endpoint should I use?

NeedEndpoint
Complete report, session ID knownGET /medical-record?session_id=...
Complete report, report ID knownGET /medical-record?report_id=...
History list filtered by type or profileGET /medical-records?module_type=5&...
Record details and fragments, record ID knownGET /medical-records/{record_id}
最近更新

Qijie Open Platform · API Documentation