# Vision

Six image-analysis primitives behind one API surface: label detection, content moderation, face detection, face comparison, celebrity recognition, and PPE (protective-equipment) detection. Backed by **AWS Rekognition**; each call is priced flat and metered per image — no ML pipeline to stand up, no monthly minimum.

```bash
curl -X POST https://api.relaystation.ai/v1/vision/detect-labels \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: labels-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inline": "<base64 image>" }, "maxLabels": 20 }'
```

Or on the lodestone path — no account, a signed x402 payment instead of an API key:

```bash
curl -X POST https://api.relaystation.ai/v1/vision/detect-labels \
  -H 'X-Payment: <base64 EIP-3009 authorization>' \
  -H 'Idempotency-Key: labels-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inline": "<base64 image>" }, "maxLabels": 20 }'
```

## Inputs — the cputools file convention

Every op takes its image as a **`file`** input source (`compare-faces` takes two — `sourceFile` and `targetFile`):

```json
{ "inline": "<base64-encoded image>" }   // for images ≤ 4 MiB
{ "inputKey": "<scratch object key>" }     // for larger images
```

Image bytes are capped at **5 MB** (operator-tunable `vision.max_image_bytes` — Rekognition's own image-bytes cap); over the cap returns a `422` before any charge. For a large image, mint a presigned upload with `POST /v1/cputools/upload-url` and pass `{"inputKey":"..."}` — see [Passing & receiving files](/docs/receiving-outputs).

## detect-labels — objects and scenes

`POST /v1/vision/detect-labels`. Optional `maxLabels` (1–100) and `minConfidence` (0–100). Returns `{ labels: [{ Name, Confidence, Instances, Parents }] }`.

## moderate — unsafe content

`POST /v1/vision/moderate`. Optional `minConfidence` (0–100). Returns `{ labels: [{ Name, ParentName, Confidence }] }` — an **empty array means the image is clean**.

```bash
curl -X POST https://api.relaystation.ai/v1/vision/moderate \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: mod-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inline": "<base64 image>" } }'
```

## detect-faces — faces and attributes

`POST /v1/vision/detect-faces`. Optional `attributes` (`DEFAULT` | `ALL` — `ALL` adds age range, emotions, and the full attribute set). Returns `{ faces: [...] }`.

## compare-faces — match two faces

`POST /v1/vision/compare-faces` takes **two images** — a `sourceFile` (the reference face) and a `targetFile` (the image to search). Optional `similarityThreshold` (0–100). Returns `{ matches: [{ Similarity, Face }], unmatchedFaces }`.

```bash
curl -X POST https://api.relaystation.ai/v1/vision/compare-faces \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: compare-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "sourceFile": { "inline": "<base64 ref>" }, "targetFile": { "inline": "<base64 target>" }, "similarityThreshold": 90 }'
```

## detect-celebrities — celebrity recognition

`POST /v1/vision/detect-celebrities`. Returns `{ celebrities: [...], unrecognizedFaces: [...] }`.

## detect-ppe — protective equipment

`POST /v1/vision/detect-ppe`. Optional `requiredEquipment` (any of `FACE_COVER`, `HAND_COVER`, `HEAD_COVER`) and `minConfidence` (0–100). Returns `{ persons: [...], summary: {...} }` — per-person equipment coverage plus a roll-up summary.

## Billing

Each op is a **flat per-call charge**: `detect-labels`, `moderate`, `detect-faces`, `detect-celebrities`, and `detect-ppe` bill **per image**; `compare-faces` bills **per comparison**. The charge stands whether the analysis finds anything or comes back empty — what you buy is the analysis run. Priced per call; see [Pricing](/pricing) for the current rates, or send an unauthenticated `POST` to read the exact price from the `402` challenge. Every billable call needs an `Idempotency-Key`; a same-key retry returns the cached result without re-charging.

## MCP tools

Callable over MCP at `https://api.relaystation.ai/mcp`: `detect_labels`, `moderate_image`, `detect_faces`, `compare_faces`, `detect_celebrities`, and `detect_ppe`. Same auth, same prices as the HTTP routes.

## Next

[Passing & receiving files](/docs/receiving-outputs) · [ID verification](/docs/idverify) · [Quickstart](/docs/quickstart) · [x402 wire format](/docs/x402) · [API reference](/api-reference)