Pet Image Recognition Integration Guide & API Reference
This page is the authoritative reference overview for Pet Image Recognition. It summarizes the primary sequence, sub_module_type mapping to report architectures, step-by-step API catalog, and data context passing chain. For detailed schemas and code snippets, see the individual endpoint pages in the sidebar.
Main Workflow & Timing Sequence
POST /ms-ai-fast/session-records/sessions (create session; send module_type=5 and sub_module_type in the body)
↓
POST /oss/images (upload pet photo, obtain temporary secure url)
↓
POST /ms-ai-fast/ai-pic/summary/stream (SSE, stream initial recognition analysis summary)
↓
POST /ms-ai-fast/ai-pic/sessions/report-tasks (submit async report task)
↓
GET /ai-tasks/{task_id} (poll async task progress until succeeded)
↓
GET /ms-ai-fast/medical-records/{record_id} (retrieve final structured recognition report)sub_module_type Mapping to Report Architectures
sub_module_type | Capability | Architecture | UI Components & Schema Notes |
|---|---|---|---|
1 | Breed Recognition | Breed System | Includes result.prob[] probability progress bars and two-tier pet-care guidelines. |
2 | Emotion/Face | Face System | Includes result.emotion badge, facial micro-signals, and interaction suggestions. |
3 | Dental | Body Condition | Dental, feces, vomit, skin, ear, and eye share the exact same schema: Overall health banner, Normal/Abnormal tabs, risk levels, 4-dimension pathology cards, and medicine recommendations. |
4 | Feces | Body Condition | Same as above (Shared body condition schema) |
5 | Vomit | Body Condition | Same as above (Shared body condition schema) |
6 | Skin | Body Condition | Same as above (Shared body condition schema) |
7 | Ear Canal | Body Condition | Same as above (Shared body condition schema) |
8 | Eyes | Body Condition | Same as above (Shared body condition schema) |
API Catalog & Step-by-Step List
| Step | Endpoint | Method | Type | Purpose & Timing |
|---|---|---|---|---|
| 1 | /session-records/sessions | POST | JSON | Required. Initialize session (module_type = 5), bind sub_module_type and pet_profile_id. |
| 2 | /oss/images | POST | JSON | Upload image, get secure URL. |
| 3 | /ai-pic/summary/stream | POST | SSE | Stream image recognition and summary. |
| 4 | /ai-pic/sessions/report-tasks | POST | JSON | Submit full structured report task, get task_id. |
| 5 | /ai-tasks/{task_id} | GET | JSON | Poll task status until succeeded. |
| 6 | /medical-records/{record_id} | GET | JSON | Retrieve structured report. For schema breakdown, see Recognition Report Fields & UI Mapping. |
Core Context Passing Chain
Step 1 Create Session
└── session_id ──────────────┬──> Step 3: session_id in summary stream
└──> Step 4: session_id in report task
Step 2 Upload Image
└── url ─────────────────────────> Step 3 & Step 4: img_url
Step 4 Submit Report Task
└── task.task_id ────────────────> Step 5: Poll task /ai-tasks/{task_id}
Step 5 Task Completion
└── Polled to succeeded ─────────> Step 6: GET /medical-records/{record_id}Step-by-Step Integration Notes
Step 1: create the recognition session
Pick one sub_module_type before creating the session. The value is stored in the session and cannot be changed afterwards; send the numeric value only, never the capability name.
{
"module_type": 5,
"sub_module_type": 7,
"pet_profile_id": 44,
"lang": "zh-CN"
}module_type is always 5; pet_profile_id is the numeric ID obtained from the Pet Profiles endpoints. Keep session_id from response data.
Step 2: upload the image
Upload with multipart/form-data:
| Form field | Value |
|---|---|
file | The image file itself; jpg, jpeg, png, webp or gif, up to 10 MiB. |
Read the url field inside the complete upload success response's data object and persist it. Every later img_url must reuse that exact string: not an image webpage URL, a temporary signed URL, a hand-built OSS URL, or an asset uploaded by another user.
Step 3: stream recognition and generate the summary
One call performs both recognition and summarisation. Consume the events as follows:
- On the single
metadataevent, record the trace information. - For each event whose
typeiscontent, read that event JSON'scontentfield and render it progressively; never use intermediate text to decide the business outcome. - After receiving the complete terminal event whose
typeisdone, read itsdataobject as the structured recognition result; only then is the recognition complete. - An
errorevent, or a connection that closes without eitherdoneorerror, means the stream failed. Retry with limited attempts only whenerror.retryableistrueor for network-level errors.
Step 4: publish the report task in parallel and read the report
The report task can be submitted while the recognition stream is still running; you do not have to wait for the streamed text to finish.
{
"session_id": "<SESSION_ID>",
"img_url": "<UPLOAD_RESPONSE_DATA_URL>"
}Take task.task_id from the complete success response's data object and poll GET /ai-tasks/{task_id} at a fixed 4-second interval with a 5-minute ceiling; stop as soon as the status is succeeded, failed, or canceled.
After the report task succeeds, read the report details and fragments with GET /medical-records/{record_id}, or list past recognition records with GET /medical-records?module_type=5.
Handle the two results separately
The recognition stream and the report task are independent: a failed summary stream does not mean the report task failed, and a successful report task does not mean the client received a complete done event. Track both outcomes separately and mark the recognition as complete only after receiving SSE done.
To retry a failed report task, call POST /ai-tasks/{task_id}/retry with the task_id returned by the failed task instead of creating a second report task for the same session.
Immutable Session Constraints
The platform binds a session to the pet profile, the sub_module_type, the language and the first image asset used.
| Situation | Publicly visible response | Correct handling |
|---|---|---|
sub_module_type differs from the session when streaming | SSE error event: code AI_PIC_SUB_MODULE_MISMATCH, error_code 6103, retryable false, recommended_action restart_session (HTTP status stays 200) | Use the type fixed by the session, or create a new session for the other type. |
| Image or profile changed in the same session before submitting a report task | HTTP 4xx with a message about the session/resource conflict (internal identifier TASK_IDEMPOTENCY_CONFLICT; the numeric code 6001 only appears in task objects and SSE error events) | Do not swap the image inside a session; create a new session. |
Neither error should be retried directly. The values in the first row come from a measured live SSE error event.
lang versus locale
Pet-profile endpoints use the query parameter ?locale=... to control the displayed breed name; image recognition uses the request body field lang to fix the AI session language. Both take BCP 47 values, but they are not interchangeable.
| Client UI language | Pet-profile read | Image-recognition session creation |
|---|---|---|
| Simplified Chinese | ?locale=zh-CN | "lang": "zh-CN" |
| Traditional Chinese (Hong Kong) | ?locale=zh-Hant-HK | "lang": "zh-Hant-HK" |
| US English | ?locale=en-US | "lang": "en-US" |
Once a session exists:
- later AI requests should omit
langand inherit the session language; - if
langis sent, it must be exactly the value used to create the session; - a different language returns HTTP
400(message:请求语言与会话语言不一致; internal identifierSESSION_LOCALE_MISMATCH); the platform never falls back silently and never switches language inside a session.
Failure Handling
Where these identifiers are visible
The names below are server-side reason identifiers: for streaming endpoints they appear in the SSE error event's code field (the same event also carries the public numeric error_code); a plain HTTP 4xx/5xx returns only {code, message, data} — neither the identifier nor a numeric code — so decide from the HTTP status and message; for a failed asynchronous task the numeric code is in the task object's data.error_code.
| Trigger (internal identifier / publicly visible response) | Retry? | Correct action |
|---|---|---|
Network timeout, or SSE retryable: true | Limited retry | Retry with the same request parameters. |
| No SSE terminal event received | Limited retry | Treat the stream as failed and restart it; do not treat stray content chunks as the final result. |
MEDIA_URL_NOT_ALLOWED / MEDIA_URL_INVALIDHTTP 400, message 媒体URL不是当前服务登记的OSS地址 (when streaming, this can also arrive as an SSE error event) | No direct retry | Upload again and use the exact url from the response. |
AI_PIC_SUB_MODULE_MISMATCHSSE error event, error_code 6103 | No direct retry | Use the type fixed by the session, or create a new session. |
TASK_IDEMPOTENCY_CONFLICTHTTP 4xx (only message is visible) | No direct retry | Do not swap the image in the old session; create a new session. |
Report task failed | Check the error first | Record task_id, session_id and error_code; retry only when the code is retryable. |