Skip to content

Models and Validation

Request validation

Section titled “Request validation”
  • QueryRequest (RootModel[dict[str, Any]]): requires query
  • FaceSearchRequest (RootModel[dict[str, Any]]): requires non-empty image_base64

Validation runs before network I/O.

Response models

Section titled “Response models”

Defined in src/odins_eye/models.py:

  • StatusMessage
  • EsResponse
  • QueryResponse
  • CreditResponse
  • UserInfo
  • UserProfileResponse
  • VersionResponse

All models allow extra fields for forward compatibility.

Union adapters

Section titled “Union adapters”
  • StatusOrEsAdapter
  • StatusOrQueryAdapter
  • StatusOrCreditAdapter

These support endpoints that may return either success payloads or status-only payloads.

Face search payload encoding

Section titled “Face search payload encoding”

_encode_image_b64 behavior:

  • Expands user paths (Path(image_path).expanduser())
  • Validates the file exists (is_file())
  • Reads bytes and encodes Base64 ASCII
  • Raises ValueError if file is missing

Both sync and async face_search methods inject image_base64 after cloning payload (dict(payload or {})).