---
title: "The OpenVibe.Vision API"
canonical: "https://openvibe.vision/developers"
updated: null
---

# The OpenVibe.Vision API

HTML: [The OpenVibe.Vision API](https://openvibe.vision/developers)

Developers

# The Vision API

JSON under `/api/v1`, with `application/problem+json` errors. A person is the `vision_at` session cookie or a Network user token as a Bearer. A service token needs the capability on the route; Design's Arena calls the UI check with `vision.ui.check`.

## Ask, read, compare

- `POST /api/v1/ask (alias /api/v1/describe)`: One image and a question: `{ task, question, mode, image_url }`, a multipart `image`, or an `image` data URL. Local OCR answers a read question first, otherwise OpenVibe.AI. Capability: `vision.image.ask`.
- `POST /api/v1/ocr`: The local Tesseract reader. `fallback=1` asks AI only when no text is found and the caller is signed in or holds `vision.text.read`.
- `POST /api/v1/compare`: The same image through local OCR and one to three AI hints (`models`). Returns each engine's answer, provider, model, cost and latency. Capability: `vision.model.compare`.
- `POST /api/v1/ui-check`: HTML, URL or screenshot with `viewport`. Returns `findings`: overflow, cut\_off, contrast, overlap and layering. Capability: `vision.ui.check`.
- `POST /api/v1/alt`: Pics, Media and Chat send an image for short editable alt text. Capability: `vision.alt.write`.
- `POST /api/v1/index; GET or POST /api/v1/find`: Media and Search index an owner image and find it by words or image. Requires the owner user token. Capability: `vision.media.find`.
- `POST /api/v1/receipt`: Food sends a receipt image; Tesseract reads store, items and total first. Capability: `vision.receipt.read`.
- `POST /api/v1/product`: Deals sends a product image for description, CLIP vector and configured offer candidates. Capability: `vision.product.match`.
- `POST /api/v1/watch`: Cam sends an owner-provided still and watched classes. Requires the owner user token. Capability: `vision.camera.watch`.
- `POST /api/v1/moments`: Live or Media sends timestamped frames for scenes and candidate moments. Requires the owner user token. Capability: `vision.video.moments`.
- `GET /api/v1/answers/:id`: One saved answer, for its owner or a service holding the route capability.
- `GET /api/v1/ui-checks/:id`: One saved UI check, for its owner or a service holding `vision.ui.check`.
- `GET /api/v1/models`: The AI route's offered provider:model hints and the local engine. No subject data.
- `GET /api/v1/benchmarks?task=&limit=`: Aggregate compare samples: task, engine, provider, model, samples, mean latency and mean cost. No subject data.

## Faces, by consent

- `POST /api/v1/faces/detect`: Anyone. YuNet boxes and a count; no template, identity or cross-frame tracking.
- `POST /api/v1/faces/blur`: Anyone. The same YuNet boxes drive an image/png redaction. Both open routes are rate-limited.
- `GET /api/v1/faces/consents/text`: The four signed texts and their versions. A person signs one purpose with `signed_name` and `text_version` at `POST /api/v1/faces/consents/:feature`; `DELETE` revokes and erases.
- `POST /api/v1/faces/enrol/:feature`: A person, after that purpose's consent: exactly one face into an AES-GCM encrypted SFace template.
- `POST /api/v1/faces/verify`: A person. Returns `{ score, match, threshold, liveness: "not_checked" }` against their own template, never an identity. A match alone unlocks nothing.
- `POST /api/v1/faces/media`: A person with find or library consent. Stores an encrypted Vision upload; `GET /api/v1/faces/media/:id` is owner-only.
- `POST /api/v1/faces/find`: A person with self-search consent. Matches only their own template in their own Vision uploads and returns private links.
- `POST /api/v1/faces/cast/match`: Live with `vision.face.cast.match` and a signed `channel_id` claim. Reads only that channel's adult, consenting roster.
- `GET /api/v1/faces/cast/tags`: A person's own cast tags; revoking a grant deletes them.
- `POST /api/v1/faces/library/cluster`: A person with library consent in an allowed region. Private clusters; unknown faces stay unlabelled.
- `GET /api/v1/faces/library/groups`: A person's own groups. No subject or public index.
- `POST /api/v1/faces/library/correct`: A person's own group correction: `exclude`, `merge` or `split`.

[Manage choices](/people) · [Retention and privacy](/people/privacy)

## Capabilities and grants

Vision calls OpenVibe.AI with `ai.run.create`, audience `openvibe.ai` and namespace `ai.*`. The twenty Vision capability manifests cover image questions, text, comparison, UI checks, network tools and consent-scoped face operations. A service token needs the capability named on its route; a person manages only their own face consent. Vision also offers eleven tools on `/mcp`, with Network token discovery at `/.well-known/oauth-protected-resource`.

~~~~
POST /api/v1/ui-check
Authorization: Bearer <Network service token for openvibe.vision>
Content-Type: application/json

{ "html": "<!doctype html>…", "viewport": { "w": 390, "h": 844 } }
~~~~

## What leaves this host

The local OCR engine, UI check and all face tools run on this host. Only an ask, compare or OCR fallback sends the normalised image to OpenVibe.AI; face images and templates never go there. General answers store no image bytes; opt-in face uploads are encrypted and private. AI may describe people, including how they look; it never names a stranger or uses a face as identity.

AI on this host: configured. Model hints: from AI's routes at request time.

## Search

v1 has no public objects: answers and UI checks belong to the caller and are not indexed, so Vision writes no Search document and has no outbox. The v2 Arena's public leaderboards are where public records will begin.