A distinct voice, as an API.

Hermit is a personality distilled from thousands of community “takes” on music. Give it a song and it returns a one-line take in that voice; ask it to write and it produces longer prose in the same register. Text in, text out — the model reads a song's title, artist, and the community's own corpus — never any third-party media, lyrics, or audio. One POST, no key to start.

Quickstart

try every door live → /doors — the read, the card, the playlist, the embed, the filing and the wire, with real data and the exact call under each. then /recipes — one hundred ways to put a line to work, each with the call. the rest of the house for developers: connect an assistant · the bot · pricing · credits · a key · the license.

One call. Pass a Spotify track id, get a take back. No authentication for the shared daily read — paste this into a terminal and it works right now:

curl -X POST https://photoprompting.org/api/hermit/interpret \
  -H "Content-Type: application/json" \
  -d '{ "spotifyId": "0bu0to8kgrXDzWklgZ3BuQ" }'

const res = await fetch(
  "https://photoprompting.org/api/hermit/interpret",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ spotifyId: "0bu0to8kgrXDzWklgZ3BuQ" }),
  }
);
const { interpretation, source } = await res.json();
console.log(source, "→", interpretation);

import requests

r = requests.post(
    "https://photoprompting.org/api/hermit/interpret",
    json={"spotifyId": "0bu0to8kgrXDzWklgZ3BuQ"},
)
data = r.json()
print(data["source"], "→", data["interpretation"])

You get back a single line and the tier that produced it:

{
  "interpretation": "reminds me of that warehouse where nobody talked for hours",
  "source": "claude",
  "cached": true
}

POST /api/hermit/interpret

The core endpoint. Provide a song; get a one-line take. No auth required for the cached read.

Any Spotify track works. Unknown spotifyIds are resolved through the official Spotify API and join the catalog automatically on first request (rate-limited; the response carries discovered: true). The catalog doesn't gate the API — the API grows the catalog.

Request body:

Response fields:

A Tier 2 (generated) response in full:

{
  "interpretation": "reminds me of that warehouse where nobody talked for hours",
  "source": "claude",
  "quality": 0.7,
  "cached": false,
  "provenance": {
    "song_id": "dff32426-…",
    "spotify_id": "0bu0to8kgrXDzWklgZ3BuQ",
    "model": "claude-haiku-4-5",
    "exemplar_count": 5
  },
  "model": "claude-haiku-4-5"
}

A Tier 1 (community) response carries the original author's provenance instead:

{
  "interpretation": "this song looks like hawaii",
  "source": "community",
  "quality": 0.5,
  "provenance": {
    "take_id": "14bfce98-…",
    "author": "mclary",
    "votes": 5,
    "quality_score": 5
  },
  "model": "hermit-community-v0"
}

GET /api/hermit/read — the simplest door

Everything /interpret does, reachable from a URL bar. Paste a whole Spotify share link — no JSON, no POST body. Built for Apple Shortcuts, curl, spreadsheet formulas, and every bot framework’s laziest HTTP call. Same tiers, same caching, same limits underneath.

curl "https://photoprompting.org/api/hermit/read?url=https://open.spotify.com/track/75IQVo8hqI1iwVZyvkN2VT&format=text"

The iPhone/Mac shortcut, three actions. Open the Shortcuts app → new shortcut → enable “Show in Share Sheet” (accepts URLs):

Name it “what does the hermit think”. Anonymous quota applies (20 fresh reads a day per reader, from a public allowance of 150); cached and community reads don’t count against it.

GET /api/hermit/card — the read as a picture

The same answer /read gives, drawn on the wall’s index card: the line in serif, the record, the credit, the address. One PNG, for anything that posts images rather than unfurling links — Bluesky, a Discord bot, a newsletter, a script that saves to Photos. Same tiers and limits as /read; pass your key the same way and fresh reads land on your ledger. ?take= draws a filed take as filed, no generation. Bad input comes back as a PNG too (an <img> has no other way to say so): 400 when the link is not a track, 404 when the song has no line yet. The status also rides in an X-Card-Status header.

curl -o card.png "https://photoprompting.org/api/hermit/card?url=https://open.spotify.com/track/75IQVo8hqI1iwVZyvkN2VT&format=square"

GET /api/hermit/playlist — a whole playlist, one line each

Hand it the tracks, get a line per song. Spotify stopped sharing playlist contents with server apps (the name arrives, the tracks don’t — even for public playlists people made), so the door that works today is ?ids=: a comma list of track ids, read by whatever holds the listener’s own Spotify session — Raycast, a browser, a script. A playlist link is still accepted and will start working the day Spotify lets it. Each track is read community-first (a filed take, free); only a miss falls through to the normal read — cached, then fresh. Fresh generations are capped at 6 per call on top of your daily tier, so one link cannot spend the day: tracks past the cap with nothing filed and nothing cached come back line: null, reason: "quota". Reads run four at a time. ?format=card draws the first 12 rows on one 1080×1350 card. Spotify-owned and editorial playlists are not shared with apps anymore (the November 2024 restrictions) — those 404 with a note; playlists people made and left public work.

{
  "name": "…", "total": 38, "shown": 12,
  "tracks": [
    { "id": "75IQVo8hqI1iwVZyvkN2VT", "title": "Show Me How", "artist": "Men I Trust", "art": "https://…",
      "line": "this song reminds me of waiting in a coffee shop that's trying too hard to be cool",
      "source": "community", "take_id": "f9fdc3d9-…", "author": "Matthew Clary", "url": "/s/75IQVo8hqI1iwVZyvkN2VT" }
  ],
  "quota": { "fresh_used": 0, "fresh_cap": 6 }
}

curl "https://photoprompting.org/api/hermit/playlist?ids=75IQVo8hqI1iwVZyvkN2VT,0bu0to8kgrXDzWklgZ3BuQ&format=card" -o playlist.png

POST /api/v1/takes — filing from anywhere

The read goes out; this is the door in. One line about one element of a Spotify song, filed from a bot, a script, a spreadsheet — anything that can send JSON with a key. The same gate the site uses, with walls in front of it. The take comes back with its address on the wall. Header x-api-key is required; there is no anonymous filing.

Unknown song? If Spotify knows the track, the record joins the catalog on the spot and the take files. If Spotify does not, 400 and nothing is written. The same line already on that record answers 200 with the existing take and "deduped": true — nothing is filed twice.

{
  "take": {
    "id": "a832e584-784d-401a-b960-bcbcf88f6315",
    "short": "a832e584",
    "url": "https://photoprompting.org/t/a832e584",
    "text": "this bass line walks home the long way on purpose",
    "element": "sound",
    "song": { "spotify_id": "75IQVo8hqI1iwVZyvkN2VT", "title": "Show Me How", "artist": "Men I Trust" }
  }
}

Limits: 60 filings a day per key · 10 a day per writer (source + external_id) · 30 a day per address · 300 a day across everyone. Each filing also spends one fresh-read unit of the key’s daily quota — the key check and the meter are the same call for now. Reading them back: GET /api/v1/takes?song=<track id or link> — the filed takes on a record, newest first, 50 max, no key needed.

curl -X POST https://photoprompting.org/api/v1/takes \
  -H "x-api-key: YOUR-API-KEY-HERE" -H "content-type: application/json" \
  -d '{"url":"https://open.spotify.com/track/75IQVo8hqI1iwVZyvkN2VT","text":"this bass line walks home the long way on purpose","element":"sound","author":"you"}'

The Discord bot files through this door too — /take link: line: part: in any server it has joined.

oEmbed — paste a take anywhere

A take is one line. It should survive being pasted into someone else’s page — a blog, a forum, a newsletter CMS, Notion. Anything that speaks oEmbed can unfurl a take link into the card without asking us. Every take page carries the discovery tag (<link rel="alternate" type="application/json+oembed">), so consumers find the endpoint on their own.

curl "https://photoprompting.org/api/oembed?url=https://photoprompting.org/t/f9fdc3d9&format=json"

{
  "version": "1.0", "type": "rich",
  "provider_name": "photoprompting", "provider_url": "https://photoprompting.org",
  "title": "this song reminds me of someone going to work in a bad mood",
  "author_name": "Matthew Clary", "author_url": "https://photoprompting.org",
  "html": "<iframe src=\"https://photoprompting.org/embed/take/f9fdc3d9-…?theme=light\" width=\"560\" height=\"280\" style=\"border:0;max-width:100%\" loading=\"lazy\" title=\"…\"></iframe>",
  "width": 560, "height": 280,
  "thumbnail_url": "https://photoprompting.org/api/og/take/f9fdc3d9-…", "thumbnail_width": 1200, "thumbnail_height": 630,
  "cache_age": 86400,
  "song": { "title": "Show Me How", "artist": "Men I Trust", "spotify_id": "75IQVo8hqI1iwVZyvkN2VT" }
}

The card itself lives at https://photoprompting.org/embed/take/<id>?theme=dark|light — a standalone page, no app chrome, framable anywhere: the art, the line, the writer, the record, which element it’s about, and one door back to the wall. <id> is the uuid or the 8-character /t prefix; cached an hour. On any take page the quiet row has embed next to share; tap it and the iframe snippet is on your clipboard.

Song pages — /s/<id>

Every record on the wall has one page: https://photoprompting.org/s/<spotify track id>. Paste a Spotify share link in place of the id and it redirects to the short form. The page is the record as the frame and the takes as what hangs in it — the art (tap it for the 30 seconds), title, artist, the Spotify door; what the house read, if the voice has already read this one, and how many days ago; every line filed on the record, most seen first, each linking to its own /t page; and one button to write yours, which opens the composer on that song. A page view never generates a read and never adds a record — the house only reads inside the API, and the catalog only grows when somebody files. Records with nothing on them yet are followed by search engines but not indexed. The url field on every /playlist track and the footer of every /card point here.

The wire

Every midnight UTC the wall crowns one take; at 13:00 UTC the site posts it — the card as the picture, the line, the writer and the record under it, the /t/ link — to Bluesky, Mastodon and Threads. Nobody presses anything; the same take everyone sees on /today is the one that goes out, and the site keeps a ledger so a day is posted once. Follow it where you already are: @photoprompting.bsky.social · @[email protected] · @photoprompting on Threads. One take a day, human lines only, never an ad.

MCP — hermit as a tool inside your assistant

The short version for anyone: photoprompting.org/connect — pick your assistant, three steps, done.

A remote Model Context Protocol server at https://photoprompting.org/api/mcp. Add it once to Claude, Cursor, Claude Code, or anything else that speaks MCP, and “what does the hermit think of this song” works wherever the conversation already is — no account, no key; the assistant signs in once on one screen. Streamable HTTP, stateless, CORS open. The hermit here is a librarian to the wall, not a writer on it: reads hand back a human line first, credited, and the house voice only when nobody has filed one. No Spotify data goes to the assistant: songs are named as MusicBrainz, the open music encyclopedia, lists them, and cards are handed over as links.

Settings → Connectors → Add custom connector
  name:  photoprompting
  url:   https://photoprompting.org/api/mcp

{
  "mcpServers": {
    "photoprompting": { "url": "https://photoprompting.org/api/mcp" }
  }
}

claude mcp add --transport http photoprompting https://photoprompting.org/api/mcp

Settings → Security and login → Developer mode: on
Settings → Apps (or Connectors) → Create → MCP server URL:
  https://photoprompting.org/api/mcp
  authentication: OAuth  →  sign in on the one screen  →  let it in
then in a chat: + → the photoprompting app → ask about a song

It works by voice. In the Claude app, tap the microphone and ask what the hermit thinks of a song — the assistant calls speak_take and says the line word for word, credit first, no addresses read aloud. Filing by voice reads your line back before it goes on the wall.

Every client signs in once when you add it — one screen, no account, no password: it names the app asking, you can tell the wall what to call you (lines you file carry that name), and you let it in. The pass renews itself for a month; delete the connector to end it sooner. Standard OAuth 2.1 with dynamic registration and PKCE, so it works the same in Claude, Cursor, Claude Code, and anything built on the MCP SDKs.

Bring a key and it rides along: clients that send headers can set Authorization: Bearer <your api key>, which reaches every door as x-api-key — fresh reads land on your ledger and filings carry your key. Without one, reads share the anonymous allowance and filings go through the house’s own key, tagged source: mcp. The machine-readable spec for everything on this page is /openapi.json; the plain-text version for agents is /llms.txt (long form: /llms-full.txt); the discovery manifest is /.well-known/mcp.json.

The two tiers

One endpoint, two quality levels — it automatically uses the highest one available:

The source field in the response tells you which tier answered.

The bundle

A take is shown with its song. The bundle ships both in one payload — the take, the element it comments on (half are about the sound, a quarter about the canvas or art), the 30-second preview, the art, and the doors — so an embed, a bot, or a newsletter template can show them together without understanding the site.

Add "bundle": true to the body (or ?bundle=1) on /api/hermit/interpret. Works on every tier — generated, cached, and community reads (community bundles also carry the take's permanent atom url).

{
  "interpretation": "this song looks like hawaii",
  "source": "community",
  "bundle": {
    "line": "this song looks like hawaii",
    "element": {
      "class": "canvas",
      "stamp": "▞ the canvas",
      "phrase": "the canvas of"
    },
    "evidence": {
      "class": "look-canvas",
      "stamp": "▞ the canvas",
      "deliver": "the take is about the canvas — send the reader through the spotify door; it only plays there"
    },
    "song": {
      "spotify_id": "3AJwUDP919kvQ9QcozQPxg",
      "title": "Yellow",
      "artist": "Coldplay",
      "album_art_url": "https://i.scdn.co/image/…"
    },
    "preview": null,
    "doors": {
      "spotify": "https://open.spotify.com/track/3AJwUDP919kvQ9QcozQPxg",
      "embed": "https://open.spotify.com/embed/track/3AJwUDP919kvQ9QcozQPxg?theme=0",
      "console": "https://photoprompting.org/doors?song=3AJwUDP919kvQ9QcozQPxg",
      "atom": "https://photoprompting.org/t/14bfce98-…"
    }
  }
}

element.class is the part of the song the line is about — one of title · lyrics · canvas · art · sound: the writer's declared element when the take was filed with one, else classified from the text. stamp and phrase are the display forms. evidence.class is the legacy finer grain, one of sound · look-canvas · look-art · memory · words · moment, classified deterministically from the text — no model call, nothing sent anywhere. deliver is the rendering instruction: play the preview under sound-takes, show the art beside picture-takes, send canvas-takes through the Spotify door (the canvas only plays on Spotify — the bundle never carries canvas urls). preview is always null now: play the song through doors.embed, Spotify’s own player. A clip from another service may not sit beside Spotify’s cover art and song details, so the bundle no longer carries one. Bundles are computed on demand and never cached stale.

POST /api/hermit/prose

The same voice, longer form. Ask Hermit to write an about blurb, a vignette, a deadpan review, a launch post — grounded on the identical distilled personality plus real community takes as anchors. A GET to the same URL lists the available forms.

Request body:

curl -X POST https://photoprompting.org/api/hermit/prose \
  -H "Content-Type: application/json" \
  -d '{ "form": "review", "topic": "a 24-hour laundromat at 2am" }'

Response:

{
  "form": "review",
  "topic": "a 24-hour laundromat at 2am",
  "prose": "the fluorescent light is the honest kind…",
  "voice": { "grounded": true, "profile_source": "distilled", "anchor_count": 8 },
  "drafts": 1,
  "model": "claude-sonnet-4-5"
}

voice.grounded is true when the piece was anchored on the live distilled profile (vs. the static persona). Prose is rate-limited and honors the samex-api-key header as interpret.

POST /api/v1/voice — the licensed endpoint

The productized voice: key-required, metered, and every response stamped with provenance (voice version, corpus size) plus the voice license — outputs are yours commercially; the corpus, profile, and voice itself stay ours. Style isn't copyrightable; a corpus, a distilled profile, metered access, and a contract are.

curl -X POST https://photoprompting.org/api/v1/voice \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"an apology to my houseplants","form":"riff","best":true}'

No key yet? Request one — reviewed personally. The doors and /api/hermit/* remain the free taste.

POST /api/hermit/audition — the imitation judge

The public toy: submit one line written as if you were the voice, and the distilled profile judges it — a 0–100 match score, a deadpan verdict delivered in the voice, and “the tell” that gave you away. Scores of 75+ earn a pointed suggestion to visit the license. No key needed; six auditions per ten minutes per IP.

curl -X POST https://photoprompting.org/api/hermit/audition \
  -H "Content-Type: application/json" \
  -d '{"text":"this song sounds like my landlord apologizing"}'

Returns { score, verdict, tell }. Try it interactively in the audition booth on the doors.

GET /api/hermit/voice-profile

The aggregated personality, distilled from a broad random sample of the corpus. Useful for showing “who” is writing — and it's the same profile that steers Tier 2/3 takes and all prose.

{
  "profile": {
    "summary": "a detached night-owl who reads music like overheard conversations…",
    "moves": ["narrates the scene as a fragment of a bigger story", "…"],
    "vocabulary": ["lowercase everything", "food and place metaphors", "…"],
    "avoids": ["superlatives", "music-theory talk", "…"]
  },
  "corpus_size": 534,
  "sample_count": 150,
  "model": "claude-sonnet-4-5",
  "source": "distilled"
}

The embed widget

No code at all. Paste this anywhere on your page and Hermit's take on the track renders inline, auto-sized:

<script src="https://photoprompting.org/embed.js"
        data-pp-embed="0bu0to8kgrXDzWklgZ3BuQ"
        data-theme="dark" async></script>

data-pp-embed accepts a Spotify track id, a Spotify track URL, or a PhotoPrompting song UUID. data-theme is dark (default) or light. Multiple embeds per page are fine. A track outside the catalog renders a “be the first to read it” prompt instead of failing.

Fresh generation & API keys

By default you get the cached take — one generation per song per day, shared, instant, and free ("cached": true in the response). Append ?fresh=1 to force a brand-new generation on demand. Fresh is the metered feature:

Pass your key in the x-api-key header:

curl -X POST "https://photoprompting.org/api/hermit/interpret?fresh=1" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pp_live_…" \
  -d '{ "spotifyId": "0bu0to8kgrXDzWklgZ3BuQ" }'

An invalid key returns 401; an exhausted quota returns 429. See pricing & plans, or get in touch.

Pricing

Cached and community reads are free and unlimited. You only pay for fresh on-demand generations (?fresh=1) — each is a live model call.

Plans and checkout on the pricing page.

Rate limits

Limits are per-IP token buckets; a keyed fresh quota is per-key. Over a limit returns 429; windowed limits include a Retry-After header (seconds).

Errors

Errors are JSON: { "error": "…" }. The status code is the contract:

Machine-readable

For agents and tooling: