Skip to content

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 ​

text
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_typeCapabilityArchitectureUI Components & Schema Notes
1Breed RecognitionBreed SystemIncludes result.prob[] probability progress bars and two-tier pet-care guidelines.
2Emotion/FaceFace SystemIncludes result.emotion badge, facial micro-signals, and interaction suggestions.
3DentalBody ConditionDental, 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.
4FecesBody ConditionSame as above (Shared body condition schema)
5VomitBody ConditionSame as above (Shared body condition schema)
6SkinBody ConditionSame as above (Shared body condition schema)
7Ear CanalBody ConditionSame as above (Shared body condition schema)
8EyesBody ConditionSame as above (Shared body condition schema)

API Catalog & Step-by-Step List ​

StepEndpointMethodTypePurpose & Timing
1/session-records/sessionsPOSTJSONRequired. Initialize session (module_type = 5), bind sub_module_type and pet_profile_id.
2/oss/imagesPOSTJSONUpload image, get secure URL.
3/ai-pic/summary/streamPOSTSSEStream image recognition and summary.
4/ai-pic/sessions/report-tasksPOSTJSONSubmit full structured report task, get task_id.
5/ai-tasks/{task_id}GETJSONPoll task status until succeeded.
6/medical-records/{record_id}GETJSONRetrieve structured report. For schema breakdown, see Recognition Report Fields & UI Mapping.

Core Context Passing Chain ​

text
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.

json
{
  "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 fieldValue
fileThe 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:

  1. On the single metadata event, record the trace information.
  2. For each event whose type is content, read that event JSON's content field and render it progressively; never use intermediate text to decide the business outcome.
  3. After receiving the complete terminal event whose type is done, read its data object as the structured recognition result; only then is the recognition complete.
  4. An error event, or a connection that closes without either done or error, means the stream failed. Retry with limited attempts only when error.retryable is true or 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.

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

SituationPublicly visible responseCorrect handling
sub_module_type differs from the session when streamingSSE 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 taskHTTP 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 languagePet-profile readImage-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 lang and inherit the session language;
  • if lang is sent, it must be exactly the value used to create the session;
  • a different language returns HTTP 400 (message: 请求语言与会话语言不一致; internal identifier SESSION_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: trueLimited retryRetry with the same request parameters.
No SSE terminal event receivedLimited retryTreat the stream as failed and restart it; do not treat stray content chunks as the final result.
MEDIA_URL_NOT_ALLOWED / MEDIA_URL_INVALID
HTTP 400, message 媒体URL不是当前服务登记的OSS地址 (when streaming, this can also arrive as an SSE error event)
No direct retryUpload again and use the exact url from the response.
AI_PIC_SUB_MODULE_MISMATCH
SSE error event, error_code 6103
No direct retryUse the type fixed by the session, or create a new session.
TASK_IDEMPOTENCY_CONFLICT
HTTP 4xx (only message is visible)
No direct retryDo not swap the image in the old session; create a new session.
Report task failedCheck the error firstRecord task_id, session_id and error_code; retry only when the code is retryable.
最近更新

Qijie Open Platform · API Documentation