How predictions work

image ──► 1. Decode ──► 2. Detect cat ──► 3. Classify ──► response
                           │                  │
                           │                  └─ only when detection == "detected"
                           └─ picks the single most confident cat

Detection

A cat detector looks for cats in the image. If there are several, it uses the one it is most confident about. The outcome is reported in detection:

detection Detector confidence for the best cat cat prediction What to do
detected ≥ 0.69 present present Use the prediction.
low_confidence 0.5 – < 0.69 present (best candidate) null Ask the user for a clearer, closer photo. You can use cat.bounding_box to show where the candidate was found.
not_detected no cat at ≥ 0.5 null null Tell the user no cat was found.

All three outcomes are successful requests (HTTP 200). Check detection before reading prediction.

Classification: score, threshold, label

When a cat is detected, the classifier looks at the cropped cat and produces:

  • score: the probability (0.0–1.0) that the cat shows discomfort.
  • threshold: the cut-off used for this request.
  • label: "discomfort" when score > threshold (strictly greater), otherwise "comfort".

Choosing a threshold

  • If you omit threshold, the model's trained default is used. That is currently 0.3 for bc-v1, but it can change when the model is retrained. Always read prediction.threshold from the response rather than assuming a value.
  • Lower threshold → more cats flagged as discomfort (fewer missed cases, more false alarms). Suits triage and screening.
  • Higher threshold → fewer flags (more certain flags, more missed cases).
  • Because score is returned, you can also apply your own threshold on your side without calling the API again.

Bounding box coordinates

cat.bounding_box is in pixels of the image as it was decoded:

  • The origin (0, 0) is the top-left corner. x increases to the right and y increases downward.
  • x_min, y_min are the top-left corner of the box. x_max, y_max are the right and bottom edges.
  • Values are integers. image.width and image.height give the frame they refer to.

To draw the box on a differently sized preview, scale it:

const scaleX = previewWidth / result.image.width;
const scaleY = previewHeight / result.image.height;
const box = result.cat.bounding_box;
drawRect(box.x_min * scaleX, box.y_min * scaleY,
         (box.x_max - box.x_min) * scaleX, (box.y_max - box.y_min) * scaleY);

⚠️ Photo orientation (EXIF): the API does not apply EXIF orientation tags. Phone cameras often store images sideways with a "rotate" tag. If you send such a file, coordinates refer to the unrotated pixels. Rotate images upright before sending them (see Image best practices).

Request IDs

Every response from the v2 predict endpoints includes a request ID in the X-Request-ID response header and in the request_id field of the body. This applies to successes and errors, including 401s. (Errors from the hosting platform, such as 503 or 504, and requests to paths that don't exist have no request ID.)

  • You can supply your own ID by sending an X-Request-ID request header. It must be 1–128 characters of letters, digits, ., _, :, or -.
  • If you don't send one, or yours doesn't match those rules, the API generates one (format req_<32 hex characters>). An invalid ID never causes a request to fail.
  • Log the request ID and include it when contacting support.

Scan IDs

Each successful (HTTP 200) prediction is recorded by Sylvester and returned with a scan_id. This includes low_confidence and not_detected results. Store it alongside your own record of the request: it identifies the prediction in Sylvester's usage records and in support requests. Error responses have no scan_id and are not recorded.