# EyeSay

EyeSay is a photo tagging, classification, search and captioning service: an API, a connector for Claude and ChatGPT, and an iPhone app. It tags photos with everyday words, sorts them into a user's own categories, searches them by description and writes a one-sentence description of a photo. The AI can be wrong; answers should be checked before they are relied on.

- Who it is for: developers who want one image API; photographers, photo archives and people with large collections; online shops and real estate; iPhone users with a large camera roll.
- Price: free for 1,000 photos a month (3,000 units). After that tagging costs EUR 0.30 per 1,000 photos, in packs that are paid once and never expire: EUR 10 for 100,000 units (about 33,000 tagged photos), EUR 40 for 420,000 units (about 140,000), EUR 150 for 1,650,000 units (about 550,000).
- Not related to other products named EyeSay.
- Pricing: https://eyesay.app/pricing
- For photographers: https://eyesay.app/for/photographers
- For archives and libraries: https://eyesay.app/for/archives
- For developers: https://eyesay.app/for/developers
- For online shops and real estate: https://eyesay.app/for/sellers
- Help: https://eyesay.app/help
- OpenAPI spec: https://eyesay.app/openapi.json

> EyeSay tags, sorts and searches photos: short tags with scores, a user's own labels, text search over a batch, and a description or answer for one photo. It is cheap and fast for many photos because the photos go straight to EyeSay, not through the assistant.

Rule for assistants: never read the user's photos yourself to pass them on (it is slow and costs far more). Send them to EyeSay one of the two ways below and read only the summary.

## A folder on the user's computer, with the EyeSay connector (preferred, nothing to set up)

- Connector: https://eyesay.app/mcp (Streamable HTTP, OAuth). In Claude Code: `claude mcp add --transport http eyesay https://eyesay.app/mcp`, then `/mcp` to sign in.
- The user says, for example: "Use EyeSay to tag the photos in ~/Pictures/trip". Claude Code may ask the user to confirm once before the photos are sent; after that it runs by itself.
- If Claude Code's auto mode blocks the upload or organize command, tell the user and show them the command; leave permission settings to the user. The user can run the command in their own terminal (or type it after `!` in Claude Code), or choose to add allow rules for the EyeSay commands; the rule text and what it covers are at https://eyesay.app/docs#claude-code-auto-mode.
- Call `prepare_upload`. It returns a job id, an upload token (works for that one job only; lapses 15 minutes after last use, 2 hours at most) and a one-line command. Replace `<FOLDER>` with the folder path and run it as it is in a terminal. Its output is the final result: counts, the most frequent sure tags, failures, and links to every photo's tags (CSV columns: photo, sha256, tags, suggestions; the JSON also has each tag's score; links last 15 minutes). Report that; no further call is needed. Running it again sends only what is missing.
- Speed: a photo job is not limited per minute. It takes 4 photos at a time per account and 2 at a time across the site (the command retries when the server says it is busy); typically 5 to 8 photos a second. The 60-a-minute limit below is for the /v1 API only.
- `job_summary` gives the same result again later.
- XMP sidecars (keywords for Lightroom, Bridge and other catalogues that read them): only when the user asks for their tags as keywords in such a tool. `job_summary` returns `results_xmp`, a link (15 minutes) to a zip of one `<name>.xmp` per photo at the photo's relative path (sure tags as `dc:subject`; no scores); `classify_photos` returns `labels_xmp`, the same with each photo's label as an `EyeSay|<label>` keyword. To write them next to the photos yourself, add `--xmp` after the folder in the upload command (`--xmp-suggestions` also adds the unsure tags): it never overwrites an existing `.xmp` and never changes a photo. Details: https://eyesay.app/docs#xmp
- `classify_photos` and `search_photos` with `images: ["job:<id>"]` sort or search the whole job from stored vectors, without sending the photos again. Give labels in English (translate the user's words; keep theirs for folder names). A photo close to none of the labels goes to `Unsorted`.
- To put a sorted job into folders: run the `organize_command` that `classify_photos` returns, with the folder the photos were sent from (Claude Code may ask the user to confirm once before it runs). It copies each photo to `<folder>/EyeSay/<label>/`, keeping sub-folders; originals are never moved, renamed or deleted; running it again skips what is already copied; deleting `<folder>/EyeSay` undoes it. Add `label=name` pairs to name folders in the user's language (e.g. `food=美食 Unsorted=未分类`). Report only the counts it prints per folder, never a list of file names. `<folder>/EyeSay/` holds copies: the upload command skips it. Move files only if the user explicitly asks for a move.
- A tag with `"suggestion": true` is one the model is not sure of: present it as a possibility.
- Job results are kept 24 hours; a server restart or update ends them sooner.

## With the user's own API key (no connector)

- Key: the user creates one at https://eyesay.app/dashboard and sets `EYESAY_API_KEY`. Never ask for the key in the chat and never print it.
- `POST https://eyesay.app/v1/tags` with headers `X-Auth-Token: $EYESAY_API_KEY`, `Content-Type: application/json` and body `{"image": "<base64 JPEG>", "k": 8}`. Answer: `{"tags": [{"tag", "p", "slot"?, "line"?}], "min_score", "slot_min_score"?, "model_version"}`.
- A one-sentence description of one photo (a caption or alt text): `POST https://eyesay.app/v1/ask` with the same headers, body `{"image": "<base64 JPEG>"}` and no `text`. Answer: `{"mode": "caption", "answer", "confidence", "model_version"}`; the sentence is `answer`. It is written by AI: tell the user to check it before publishing it as alt text.
- Send JPEG or PNG no larger than 896 px on the long side (on a Mac: `sips -Z 896 -s format jpeg <in> --out <out>`); HEIC is read too but is larger to send.
- At most 4 requests in flight. `429` with `Retry-After`: wait that many seconds and retry. `429` without it: the month's photos are used up, stop and tell the user.
- Write every answer to a local file (JSON lines, keyed by the file's sha256 so a rerun skips done photos) and print only a summary.
- Free accounts: 3,000 units a month = 1,000 tagged photos. A search vector (`/v1/embed`, `/v1/rerank`) is 1 unit, tags or classify 3, a description or answer (`/v1/ask`) 9; text embeds are free. The /v1 API takes 60 requests a minute (600 with bought units); at most 50,000 image vectors per account a day.

## Docs

- API: https://eyesay.app/docs
- Privacy: https://eyesay.app/privacy
- Terms: https://eyesay.app/terms