MarshalMind

Overview

This documentation covers only FaceMarshal endpoints: Detect, Compare, and Recognize. Request examples are provided.

Face Detect

Detect faces in an image and return face boxes + metadata.

POST/api/face/detect

Request

Field	Type	Required	Notes
image	file (multipart/form-data)	Yes	Field name must be image
select_faces	string	No	"all" \| "largest" \| "single"
match_threshold	string	No	"low" \| "normal" \| "high"

Credential-safe docs

This page intentionally does not show API keys, secrets, internal URLs, or company credentials.

cURL example

curl -X POST "https://YOUR_DOMAIN.com/api/face/detect" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -F "image=@/path/to/image.jpg" \
  -F "select_faces=all" \
  -F "match_threshold=normal"

Response example

{
  "faces": [
    {
      "bbox": [120, 80, 220, 220],
      "confidence": 0.98
    }
  ]
}

Error example

{
  "error": "Missing image file",
  "detail": "Send multipart/form-data with field name 'image'"
}

Face Compare

Compare faces between two images and return similarity / match results.

POST/api/face/compare

Request

Field	Type	Required	Notes
test_image	file (multipart/form-data)	Yes	Field name must be test_image
reference_image	file (multipart/form-data)	Yes	Field name must be reference_image
select_faces	string	No	"all" \| "largest" \| "single"
match_threshold	string	No	"low" \| "normal" \| "high"

Credential-safe docs

This page intentionally does not show API keys, secrets, internal URLs, or company credentials.

cURL example

curl -X POST "https://YOUR_DOMAIN.com/api/face/compare" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -F "test_image=@/path/to/test.jpg" \
  -F "reference_image=@/path/to/reference.jpg" \
  -F "select_faces=all" \
  -F "match_threshold=normal"

Response example

{
  "matches": [
    {
      "test_face_index": 0,
      "reference_face_index": 0,
      "score": 0.87,
      "is_match": true
    }
  ]
}

Error example

{
  "error": "Both test_image and reference_image are required"
}

Face Recognize

Recognize people in an image using a specified album (face collection).

POST/api/face/recognize

Request

Field	Type	Required	Notes
image	file (multipart/form-data)	Yes	Field name must be image
album_id	string	Yes	Album identifier (required)
select_faces	string	No	"all" \| "largest" \| "single"
match_threshold	string	No	"low" \| "normal" \| "high"

Credential-safe docs

This page intentionally does not show API keys, secrets, internal URLs, or company credentials.

cURL example

curl -X POST "https://YOUR_DOMAIN.com/api/face/recognize" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -F "image=@/path/to/image.jpg" \
  -F "album_id=<ALBUM_ID>" \
  -F "select_faces=all" \
  -F "match_threshold=normal"

Response example

{
  "matches": [
    {
      "face_index": 0,
      "person": "John Doe",
      "score": 0.91,
      "bbox": [110, 70, 230, 240]
    }
  ],
  "unknown_faces": [
    {
      "face_index": 1,
      "bbox": [310, 90, 420, 250]
    }
  ]
}

Error example

{
  "error": "album_id is required for recognize"
}