Quick Start
This guide prepares the minimum integration state: an authenticated request and a successfully created Smart Consultation session. Creating a session is only the start of the consultation; generating a summary and report also requires the analysis, follow-up, SSE, and report-polling steps.
https://open-api.habitaxx.com1. Prepare credentials
| Name | Placeholder | Description |
|---|---|---|
| API Key | qj_live_your_api_key | Sent in the x-api-key header |
| Project number | prj_your_project_no | Public number shown on the project page |
| Business user ID | your_user_001 | Stable identifier managed by your system |
| Runtime pet profile ID | 44 | A numeric pet-profile ID available to this business user. 44 is a placeholder only; do not copy it into a real request. |
Prepare a usable pet-profile ID first
Both Smart Consultation and Image Recognition require a numeric pet_profile_id. Create or list one with the Pet Profiles endpoints: Create a pet profile or List pet profiles.
pet_profile_id is a number (for example 44), not a string identifier, and it is used by the pet-profile, Smart Consultation and Image Recognition endpoints alike.
2. Get an Access Token
/v1/auth/tokencurl --location 'https://open-api.habitaxx.com/v1/auth/token' \
--header 'x-api-key: qj_live_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"project_no": "prj_your_project_no",
"user_id": "your_user_001"
}'{
"code": 200,
"message": "success",
"data": {
"access_token": "eyJ...replace_with_access_token",
"token_type": "Bearer",
"expires_in": 86400
}
}Store access_token in an environment variable:
export ACCESS_TOKEN='eyJ...replace_with_access_token'3. List available languages for this environment
lang is not an arbitrary language code. List the active languages in the target environment first, then use one value from that response when creating the session.
/v1/ms-ai-fast/localescurl --location 'https://open-api.habitaxx.com/v1/ms-ai-fast/locales' \
--header "Authorization: Bearer ${ACCESS_TOKEN}"data is the active-language list. The values depend on environment configuration; this is a shape-only example:
{
"code": 200,
"message": "success",
"data": ["zh-CN", "zh-Hant-HK", "en-US"]
}The next request uses en-US. If it is absent from your real response, replace it with a returned value such as zh-CN or zh-Hant-HK.
4. Create a consultation session
/v1/ms-ai-fast/session-records/sessionscurl --location 'https://open-api.habitaxx.com/v1/ms-ai-fast/session-records/sessions' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--data '{
"module_type": 1,
"pet_profile_id": 44,
"content": "My cat has been vomiting since this morning.",
"lang": "en-US"
}'Keep the returned session_id; it is required by later consultation, message, and report requests. The submitted content is saved at initial_message.content. Keep the session ID in the current user's context; never reuse it for another user.
{
"code": 200,
"message": "success",
"data": {
"session_id": "doc_<SESSION_ID>",
"medical_record_id": 10001,
"medical_record": {},
"initial_message": {
"session_id": "doc_<SESSION_ID>",
"role": "user",
"content": "My cat has been vomiting since this morning.",
"content_type": 1
}
}
}Creating a session does not complete a consultation
This request creates the session and saves its first complaint only. Follow the complete workflow—keywords, reason-info, analysis, related-question, and correct SSE done handling—to continue the consultation and generate a report.
Next steps
- Complete a multi-turn consultation: Smart Consultation
- Run breed and health image analysis: Image Recognition
- Test requests in the browser: Swagger UI