Brainiall vision API examples

Two dependency-free Node.js 22 BYOK canaries for the current Brainiall REST contracts:

1. receipt OCR via POST https://api.brainiall.com/v1/document/extract with JSON {image, doc_type: "receipt"}; and
2. smart cutout via POST https://api.brainiall.com/v1/image/remove-background/base64 with JSON {image, format: "png"}.

Brainiall is the API provider. This repository is a bounded compatibility and quality example, not a provider-neutral implementation, partnership, endorsement, production integration, customer, sale, or proof of demand.

Safe offline run

No install is required:

npm test
npm run example:receipt
npm run example:cutout

These commands use only synthetic fixtures and make no network request. The examples print validation summaries, never source base64, full OCR content, or returned PNG bytes.

Deliberately gated live canaries

A live call is hosted and metered under the caller's own Brainiall account. Use only an image you have the right and consent to process:

BRAINIALL_API_KEY='set-outside-source-control' \
  node examples/receipt-ocr.mjs \
  --live --rightsAndConsent=true --input=/absolute/path/to/receipt.png \
  --require-confidence --ground-truth=/absolute/path/to/ground-truth.json

BRAINIALL_API_KEY='set-outside-source-control' \
  node examples/smart-cutout.mjs \
  --live --rightsAndConsent=true --input=/absolute/path/to/product.png

Both gates are mandatory. There is exactly one HTTPS request and no retry. The receipt command validates and prints only counts/scores/arithmetic. The cutout command validates the returned PNG in memory and prints only dimensions/alpha counts. It intentionally does not write the source, raw response, OCR text, or returned image. Redirects are rejected.

Optional receipt flags:

• --require-confidence requires overall and per-item confidence at or above --min-confidence=0.80 (default).
• --require-coordinates requires a safe normalized [x1,y1,x2,y2] box for every item. Missing or unsafe boxes are rejected.
• --ground-truth=... computes exact field/value precision, recall, and F1; --min-f1=0.95 is the default kill gate.

The current public product pages describe pay-as-you-go pricing and may offer free starting credits. Pricing and credits can change. Free credits, fixture passes, API calls, installs, issue comments, and accepted code are not revenue. Revenue exists only after buyer-linked cash is received, settled, and reconciled.

What validation proves

Receipt validation requires a structured merchant, currency, non-empty line items, unit price, quantity, line total, and total. It uses integer minor units and rational quantity math: every line and subtotal - discount + tax + tip + fees = total must close exactly. With ground truth, field/value F1 compares normalized values and item positions; it does not compare or print raw OCR text.

Smart-cutout validation verifies the PNG signature, chunk CRCs, bounded dimensions, DEFLATE stream, scanline filters, and an 8-bit grayscale-alpha or RGBA image containing both a fully transparent pixel and a foreground pixel. Unsupported PNG modes fail closed. A host integration must use an exclusive create operation (wx) if it chooses to persist output; this repository does not persist it.

Integration boundaries

• Split My Bill adapter limits
• OmniKit adapter limits
• Security and privacy

Public product documentation is the endpoint source of truth:

• https://www.brainiall.com/en/apis/document-ocr
• https://www.brainiall.com/en/apis/background-removal

The examples do not implement SLA, queues, retries, offline OCR, coordinate generation, local background removal, browser key storage, billing UI, or provider selection.