Skip to main content
CID222 Docs

Image analysis

Extract text from an image with OCR, detect PII and unsafe content in it, and get a redacted copy of the image back.

  • Version: 0.4
  • Role: admin_user, normal_user
  • Type: reference

Run OCR over an image, scan the extracted text with the full detection pipeline, and receive a redacted copy of the image when a detection calls for masking.

Warning

Every /image-analysis route is guarded by the JWT guard alone. A gateway API key (cid_key_…) cannot call these endpoints — it authenticates only /chat/*, /models and /api/v1/guardrails/detect.

Analyse an image

POST /image-analysis/analyze

The request is JSON with a base64 payload, not multipart. There is no file-upload field on this endpoint.

ParameterTypeRequiredDescription
imageBase64stringYesBase64-encoded image without the data:image/… prefix. Maximum 10 MB decoded
redactPiibooleanNoRedact detected PII in the image. Default true
confidenceThresholdnumberNoMinimum detection confidence, 0–1. Default 0.5
languagestringNoOCR language hint, for example en or tr. Default auto
ocrEnginestringNopaddleocr or tesseract. Default paddleocr
sessionIdstringNoLog the detections against this session

The size limit is checked on the encoded string as length × 3 / 4, so a request whose decoded image exceeds 10 MB is rejected by validation with Image size exceeds maximum allowed size of 10MB before any OCR runs. Base64 inflates a payload by about a third, so a 10 MB image arrives as roughly 13.3 MB of JSON.

curl -X POST https://<appliance-fqdn>/image-analysis/analyze \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "iVBORw0KGgoAAAANSUhEUg...",
    "language": "en"
  }'

Response

{
  "success": true,
  "action": "mask",
  "extractedText": "Name: John Smith\nSSN: 123-45-6789",
  "piiDetections": [
    { "type": "PERSON_NAME", "value": "[PERSON_NAME]", "action": "mask", "confidence": 0.95 },
    { "type": "SSN", "value": "[SSN]", "action": "mask", "confidence": 0.95 }
  ],
  "safetyDetections": [],
  "summary": { "piiCount": 2, "safetyIssueCount": 0 },
  "wasRedacted": true,
  "redactedImageBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "processingTimeMs": 1320
}
FieldTypeDescription
successbooleanWhether the analysis completed
actionstringallow, mask, reject or flag
extractedTextstringThe OCR output the detectors ran over
piiDetectionsarray{type, value, confidence, action, boundingBoxes?}
safetyDetectionsarray{type, confidence, action}
summaryobject{piiCount, safetyIssueCount}
wasRedactedbooleanWhether a redacted image was produced
redactedImageBase64stringPresent only when wasRedacted is true
processingTimeMsnumberWall time for the whole call
actionReason, rejectionReasonstringWhy the action was chosen, when there is one to give
documentTypeobject{type, confidence, signals} from the rule-based document classifier
mrzDetectedbooleanWhether a passport machine-readable zone was parsed
ocrFailedbooleanSet when OCR produced nothing usable

Redaction is selective and follows the action each filter decided: entities set to mask are painted out of the image, entities set to flag are recorded but left visible, and a reject blocks the whole image. extractedText and the detection arrays are always returned; redactedImageBase64 appears only when something was actually masked.

Note

The image path runs two detectors the text path does not: an ICAO 9303 MRZ parser (source: "mrz") and an identity-document layout extractor (source: "identity_layout"). An image classified as an identity document skips jailbreak detection.

List OCR engines

GET /image-analysis/ocr-engines

Returns the OCR engines the deployment can use and their language support. No request body.

Compare OCR engines

POST /image-analysis/compare-ocr

Runs one image through several engines so you can compare extraction quality.

ParameterTypeRequiredDescription
imageBase64stringYesBase64-encoded image, same 10 MB limit
languagestringNoLanguage hint. Default auto
enginesstring[]NoEngines to compare. Default: all available
confidenceThresholdnumberNo0–1. Default 0.5

Last updated on

On this page

Download PDF