Sylvester ML API

Migrating from v1 to v2

Request

v1 v2
POST /invocations POST /v2/predict (latest model), or POST /v2/models/bc-v1/predict (pinned)
POST /invocations/bc-v1 POST /v2/models/bc-v1/predict
{"media_type": "image", "media_data": {"image": "<b64>"}} {"image": "<b64>"}
?threshold=0.3 (query parameter) "threshold": 0.3 (body field, must be a JSON number in 0–1)
No data: prefix allowed data:image/...;base64, prefix allowed
Lenient base64 (invalid characters silently ignored) Strict standard base64 (invalid characters → 400)
— Optional X-Request-ID header

Response fields

v1 v2 Notes
success, message HTTP status and detection 200 means processed. Errors use 4xx/5xx with error.code.
mood_class: 1 / prediction: "Unhappy" prediction.label: "discomfort"
mood_class: 0 / prediction: "Happy" prediction.label: "comfort"
mood_class: -1 / "Unknown" prediction: null plus a detection state, or an HTTP error
probability prediction.score Meaning changed: v2 is always the discomfort probability (how v1 probability works)
threshold prediction.threshold
cat_detected detection == "detected" v2 adds "low_confidence"
cat_quality cat.detection_confidence v2 also returns it for low_confidence
additional_data.bounding_box_cat[0].x1 / y1 / x2 / y2 cat.bounding_box.x_min / y_min / x_max / y_max Single object instead of a list
additional_data.input_dimensions ("WxH") image.width, image.height (integers)
additional_data.detected_cat_dimensions — Compute as x_max − x_min by y_max − y_min
additional_data.model ("BC-V1") model.id ("bc-v1")
inference_metadata.version model.version
additional_data.extraction_time, inference_time, size_unit, time_unit, version, inference_metadata.build_number — Removed
— request_id New

Outcome mapping

Situation v1 v2
Prediction made 200, success: true 200, detection: "detected"
Low-quality cat 200, success: false, "Cat image quality is too low" 200, detection: "low_confidence" with cat
No cat 200, success: false, "No cats detected" 200, detection: "not_detected"
Undecodable image 200, success: false 400 invalid_image
Invalid request body 422 (framework format) 422 invalid_request (v2 format)
Bad API key 401 {"detail": ...} 401 v2 error format
Server error 500 plain text / 200 success: false 500 internal_error

Migration checklist

  • Point requests at /v2/predict (or pin /v2/models/bc-v1/predict).
  • Send {"image": ..., "threshold": ...} and move threshold from the query string into the body as a number.
  • Make sure images are standard base64 (not URL-safe) and 8-bit.
  • Branch on HTTP status first, then on detection.
  • Replace probability logic with prediction.score (the discomfort probability).
  • Map bounding box fields to x_min / y_min / x_max / y_max.
  • Handle low_confidence, for example by asking for a clearer photo.
  • Log request_id and optionally send your own X-Request-ID.
  • Make your JSON parsing ignore unknown keys.