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.
https://open-api.habitaxx.com/v1/ms-ai-fastStart 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
- Exchange the project API Key for an
ACCESS_TOKENas described in Authentication, and sendAuthorization: Bearer <ACCESS_TOKEN>with every business request.
Runtime note: the service also requires the
x-qj-userheader. When using the public gateway, the gateway should validateAuthorizationand inject this header. Do not forge it in an external client. Direct backend callers must sendx-qj-user: <USER_UUID>as documented in the API overview.
- 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. - Use only the documented
/v1/ms-ai-fast/...gateway paths for AI requests. Do not append undocumented path segments; unpublished addresses return404 Not Found. - For
module_type: 1, both the numericpet_profile_idand the initial complaintcontentare required. Get the ID from the Pet Profiles endpoints.
Recommended integration path
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.
| Step | Endpoint | Request | Response field used next | Next step |
|---|---|---|---|---|
| — | Round rules | Steps 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. |
| 1 | GET /ai-doc/pre-question (optional) | Query: pet_profile_id, lang | Starter-question list | Create a session, or create one directly. |
| 2 | POST /session-records/sessions | JSON: module_type, pet_profile_id, content, lang | session_id in the data object of the complete success response | Use this session ID for later consultation calls. |
| 3 | POST /ai-doc/keywords | JSON: session_id, pet_profile_id, content | Structured keyword result | Request reasoning or condition analysis. |
| 4 | POST /ai-doc/reason-info (SSE) | JSON: session_id, pet_profile_id | Final JSON in type=done | Request condition analysis. |
| 5 | POST /ai-doc/analysis | JSON: session_id, pet_profile_id | Condition-analysis result | Request related questions. |
| 6 | POST /ai-doc/related-question | JSON: session_id, pet_profile_id | Related-question list | Show questions and collect the user's answer. |
| 7 | POST /session-records/messages | JSON: session_id, role, content | Message-save result | Rounds 1-2: next round; round 3: continuation check; round 4: image check. |
| 8 | POST /ai-doc/if-continue-ask (SSE) called once, after round 3 | JSON: session_id, pet_profile_id | content in the business-result object of the complete type=done event: True or False | True: start round 4; False: decide whether an image is needed. |
| 9 | POST /ai-doc/if-need-image | JSON: session_id, pet_profile_id | is_pic and pic_explain in the business-result object of the complete success response | True: upload an image; False: generate the summary. |
| 10 | POST /oss/images (when needed) | multipart field: file | url in the data object of the complete upload success response | Put the same URL in img_url for image supplementation. |
| 11 | POST /ai-doc/pic-result (when needed) | JSON: session_id, pet_profile_id, img_url | Supplemental image result | Generate the consultation summary. |
| 12 | POST /ai-doc/summary (SSE) | JSON: session_id, pet_profile_id | Final summary in type=done | Submit the report task. |
| 13 | POST /ai-doc/report | JSON: session_id, report_type | task.task_id in the data object of the complete success response | Query task status. |
| 14 | GET /ai-tasks/{task_id} | Path: task_id | status in the data object of the complete success response | Retrieve the complete report when status is succeeded. |
| 15 | GET /medical-record | Query: session_id | Complete medical record | End of the flow. |
Endpoint groups
| Group | Endpoints | Purpose |
|---|---|---|
| Session preparation | GET /ai-doc/pre-question, POST /session-records/sessions | Load starter questions and create a consultation session. |
| Question analysis | POST /ai-doc/keywords, POST /ai-doc/reason-info, POST /ai-doc/analysis, POST /ai-doc/related-question | Convert user input into analysis and follow-up questions. |
| Flow decisions | POST /session-records/messages, POST /ai-doc/if-continue-ask, POST /ai-doc/if-need-image | Save an answer, decide whether to ask again, and decide whether an image is needed. |
| Image supplement | POST /oss/images, POST /ai-doc/pic-result | Upload a consultation image and obtain its synchronous supplemental analysis. |
| Summary and report | POST /ai-doc/summary, POST /ai-doc/report, GET /ai-tasks/{task_id}, GET /medical-record | Stream 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
contentprogressively, but do not advance the workflow from it. - Proceed only after the
type=doneevent. 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 withoutdoneorerroras 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:
| Order | Endpoint or field | Requirement |
|---|---|---|
| 1 | POST /oss/images | Upload the image with multipart/form-data. |
| 2 | Upload response field url | Use the platform URL returned by the service. |
| 3 | Request field img_url of POST /ai-doc/pic-result | Send 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.