Skip to content

Smart Consultation ​

Smart Consultation is a session-based pet-health workflow: capture the presenting complaint, extract keywords, render reasoning, analyze the condition, ask follow-up questions, add an image when needed, stream a summary, then generate a report.

Gateway capability prefixhttps://open-api.habitaxx.com/v1/ms-ai-fast

Start with the workflow

Smart Consultation is not a single request. Implement the full workflow first, then use the API overview for request fields, response examples, SSE consumption, and task polling.

Integration prerequisites ​

  1. Exchange the project API Key for an ACCESS_TOKEN as described in Authentication, and send Authorization: Bearer <ACCESS_TOKEN> with every business request.

Runtime note: the service also requires the x-qj-user header. When using the public gateway, the gateway should validate Authorization and inject this header. Do not forge it in an external client. Direct backend callers must send x-qj-user: <USER_UUID> as documented in the API overview.

  1. Keep each end user's token context, session_id, uploaded image URL, and report IDs separate. A session and an image asset cannot be reused across users.
  2. Use only the documented /v1/ms-ai-fast/... gateway paths for AI requests. Do not append undocumented path segments; unpublished addresses return 404 Not Found.
  3. For module_type: 1, both the numeric pet_profile_id and the initial complaint content are required. Get the ID from the Pet Profiles endpoints.

The table lists only the call order and the response fields used by later calls. See the API overview for each endpoint's complete request, response example, and field table.

StepEndpointRequestResponse field used nextNext step
—Round rulesSteps 3-7 form one round; the backend does not enforce rounds — 3-4 rounds is a common choice—Before the agreed round count, go straight to the next round without checking continuation.
1GET /ai-doc/pre-question (optional)Query: pet_profile_id, langStarter-question listCreate a session, or create one directly.
2POST /session-records/sessionsJSON: module_type, pet_profile_id, content, langsession_id in the data object of the complete success responseUse this session ID for later consultation calls.
3POST /ai-doc/keywordsJSON: session_id, pet_profile_id, contentStructured keyword resultRequest reasoning or condition analysis.
4POST /ai-doc/reason-info (SSE)JSON: session_id, pet_profile_idFinal JSON in type=doneRequest condition analysis.
5POST /ai-doc/analysisJSON: session_id, pet_profile_idCondition-analysis resultRequest related questions.
6POST /ai-doc/related-questionJSON: session_id, pet_profile_idRelated-question listShow questions and collect the user's answer.
7POST /session-records/messagesJSON: session_id, role, contentMessage-save resultRounds 1-2: next round; round 3: continuation check; round 4: image check.
8POST /ai-doc/if-continue-ask (SSE) called once, after round 3JSON: session_id, pet_profile_idcontent in the business-result object of the complete type=done event: True or FalseTrue: start round 4; False: decide whether an image is needed.
9POST /ai-doc/if-need-imageJSON: session_id, pet_profile_idis_pic and pic_explain in the business-result object of the complete success responseTrue: upload an image; False: generate the summary.
10POST /oss/images (when needed)multipart field: fileurl in the data object of the complete upload success responsePut the same URL in img_url for image supplementation.
11POST /ai-doc/pic-result (when needed)JSON: session_id, pet_profile_id, img_urlSupplemental image resultGenerate the consultation summary.
12POST /ai-doc/summary (SSE)JSON: session_id, pet_profile_idFinal summary in type=doneSubmit the report task.
13POST /ai-doc/reportJSON: session_id, report_typetask.task_id in the data object of the complete success responseQuery task status.
14GET /ai-tasks/{task_id}Path: task_idstatus in the data object of the complete success responseRetrieve the complete report when status is succeeded.
15GET /medical-recordQuery: session_idComplete medical recordEnd of the flow.

Endpoint groups ​

GroupEndpointsPurpose
Session preparationGET /ai-doc/pre-question, POST /session-records/sessionsLoad starter questions and create a consultation session.
Question analysisPOST /ai-doc/keywords, POST /ai-doc/reason-info, POST /ai-doc/analysis, POST /ai-doc/related-questionConvert user input into analysis and follow-up questions.
Flow decisionsPOST /session-records/messages, POST /ai-doc/if-continue-ask, POST /ai-doc/if-need-imageSave an answer, decide whether to ask again, and decide whether an image is needed.
Image supplementPOST /oss/images, POST /ai-doc/pic-resultUpload a consultation image and obtain its synchronous supplemental analysis.
Summary and reportPOST /ai-doc/summary, POST /ai-doc/report, GET /ai-tasks/{task_id}, GET /medical-recordStream the summary, generate the report asynchronously, and retrieve the complete record.

For the full gateway URLs see the API overview.

Key integration rules ​

content creates initial_message ​

content is the request body field for the initial complaint. For Smart Consultation it is required, and the service saves it as the first user message. initial_message is the response object for that saved message; the submitted text is in initial_message.content. It is not a second request field.

SSE completes only at a terminal event ​

reason-info, if-continue-ask, and summary return text/event-stream. Each stream starts with metadata, may contain multiple content events, and ends with exactly one terminal event: done or error.

  • Render content progressively, but do not advance the workflow from it.
  • Proceed only after the type=done event. The final JSON data and its fields are defined in each endpoint's response example and field table.
  • Treat error, malformed events, or a closed connection without done or error as failure.
  • Retry only retryable errors or transport failures, with bounded backoff.

The complete event contract and branch handling are in the full workflow.

Consultation images must be registered platform assets ​

POST /ai-doc/pic-result does not accept arbitrary web URLs. Use the following field mapping:

OrderEndpoint or fieldRequirement
1POST /oss/imagesUpload the image with multipart/form-data.
2Upload response field urlUse the platform URL returned by the service.
3Request field img_url of POST /ai-doc/pic-resultSend the exact URL from step 2 without modification.

The URL must belong to the current user, be ready, be an image, have the diagnosis-input purpose, and exactly match the service's canonical OSS URL. Third-party URLs, reconstructed OSS addresses, URLs with query strings, and another user's assets are rejected.

Submit one report task per normal flow ​

report_type accepts 1, 2, 3, 4, or 7, with a default of 1. Submit POST /ai-doc/report once after the summary completes; do not submit one task for every type. Poll task.task_id, then retrieve the complete report through GET /medical-record?session_id=<SESSION_ID>. If the task reaches failed, inspect its error and use the published retry behavior deliberately rather than issuing unconditional duplicate submissions.

最近更新

Qijie Open Platform · API Documentation