How the Valentine Captcha works.

Save online: a short link instead of a long one

Link mode has two drawbacks: a Valentine with many words gets a long link, and every picture has to be on the web already. So there is a second mode. In the link builder you can save the Valentine online and get a short address such as https://d-solve.de/valentine/k7m2p9q4r6t8. Looks, behaviour and parameters are the same. You choose per Valentine which mode to use.

How to switch

1. At the top of the sidebar in the link builder there is a switch: “Only in the link (private, nothing stored)” or “Save online (short link)”. Link mode is preselected, and your browser remembers your choice.
2. In online mode, pick the retention and click “Save online”. You then get the short link to copy and open, and, once, the edit key.
3. After that, changes are saved every 30 seconds; there is also “Save now”, “Change retention”, “Delete Valentine” and “New key”.
4. Upload pictures from the picture editor or the card’s picture list. That works once the Valentine has been saved.
5. Later, reopen a saved Valentine with “Load existing” using the short link (or id) and key. Without the key you can look at it and use it locally as the start of a new one.

If the service cannot be reached (for example on a copy without the backend), the builder says “Online storage is not available here”. Link mode then works as always.

What is stored, and where

• Stored are exactly the parameters of the Valentine as text (the values that would otherwise be in the link) and the uploaded pictures. In addition, per Valentine, a pseudonym of the sender’s address (a hash, not the IP itself), used only for the daily limits. The service keeps no visitor statistics.
• Where: at Cloudflare, the data in a database and the pictures in object storage, operated for d-solve.de.
• Deletion: when the retention ends, the Valentine is no longer served and is deleted with its pictures by a daily clean-up. “Delete Valentine” in the builder deletes at once.
• Limits: pictures, amount of text, new Valentines per day and retention are capped. The current values come from GET /api/limits, explained in the API documentation.
• Whoever has the link sees the Valentine. The short id is random and cannot be guessed, but names, texts and pictures are readable by anyone you give the link to.

The edit key

The edit key (vc_…) is shown exactly once. The server keeps only its hash, so it cannot be recovered. Copy it into a password manager or a note. The builder can remember it in this browser if you tick “Remember in this browser”. If you lose the key you can no longer change or delete the Valentine; it expires after its retention. Never share the key and never put it into a link.

For developers and AI

The builder talks to an open HTTP interface. If you want to create Valentines from a script or an AI assistant, endpoints, limits, error codes and curl examples are in the API documentation (machine-readable: openapi.json).

Get started

Three ways to a finished link, all producing the same kind of link:

1. The link builder: click through a live preview and double-click any text or picture to change it in place.
2. An AI assistant: the builder page has a prompt to copy into ChatGPT, Claude or Gemini. The assistant asks you for names, wording and picture links and hands you the finished link.
3. By hand: append the parameters below to the address yourself.

All parameters

Every parameter is optional. Leave one out, or leave it empty, and the page uses its built-in text in the chosen language. Each example below is a working link. Open it to see the effect.

Join several parameters with &: ?lang=de&to=Sarah&from=Alex&cells=1%2C3%2C5.

Formatting

In title, subtitle, prompt, question and reveal, wrap a phrase in *asterisks* to set it in the italic accent colour, and write \n (or an encoded line break, %0A) for a new line. All other fields are shown exactly as written. HTML is never interpreted, so nobody can smuggle markup into a Valentine.

Encoding

Values must be URL-encoded: space %20, comma %2C, & %26, = %3D, ? %3F, # %23, line break %0A. Umlauts and emoji become UTF-8 escapes (ü → %C3%BC). A picture link is a value too, so its own ://, /, & and = must be encoded. In JavaScript, encodeURIComponent() does all of it. The link builder and the AI prompt take care of this for you.

scale and readouts are split at commas, so their entries can’t contain one. Older links that set prompt and hint separately still work; the two are joined into one line. name, by and message are accepted as aliases for to, from and msg.

Which squares are which

Squares are numbered 1–9, left to right and top to bottom. cells and img1…img9 use the same numbers.

• cells=all: all nine must be selected. This is the joke: every square “contains a heart”.
• cells=any: any selection passes.
• cells=1,3,5: exactly these squares, no more and no fewer. Numbers outside 1–9 are ignored; if none are left, it falls back to all.

Before you send a link, solve your own challenge once. prompt and help should match what cells expects.

Pictures in the grid

A photo on your phone has no address, so it has to be somewhere public first. The one rule: the link must point directly at the image file, start with https:// and work without a login. Test it in a private window. If you see the bare picture and nothing else, it works.

• Wikimedia Commons / Wikipedia: right-click the picture, Copy image address. Free, permanent, reliable.
• Google Drive: share the file with Anyone with the link. The builder rewrites a share link by itself. By hand, use https://drive.google.com/thumbnail?id=FILE_ID&sz=w1000. The often recommended uc?export=view form looks fine in its own tab but stays blank inside another page, because Google sends it with cross-origin-resource-policy: same-site.
• Image hosts and your own site: Imgur (i.imgur.com/…), S3, Cloudinary, or Netlify Drop for instant public URLs.
• Never works: Google Photos and iCloud shares (album pages, not files), anything behind a login, plain http:// (blocked inside an https page).

Pictures inside the link

A picture can also travel in the link as a data:image/webp;base64,… URI. Nothing is uploaded, but each picture adds thousands of characters. Links over roughly 18 000 characters do not open in Safari on iPhone at all: the recipient sees a white page. Use it for one small picture at most, shrunk to about 400×400 first:

# shrink to a 400×400 square, then print a URL-encoded data: URI
magick photo.jpg -resize 400x400^ -gravity center -extent 400x400 -quality 70 square.webp
python3 -c "import base64, urllib.parse; \
  d = base64.b64encode(open('square.webp','rb').read()).decode(); \
  print(urllib.parse.quote('data:image/webp;base64,' + d, safe=''))"

Every parameter in one link

German, both names, custom wording on every screen, three squares that count and three placeholder pictures:

https://d-solve.de/projects/valentine-captcha/?lang=de&to=Sarah&from=Alex&title=du%20hast%20*einen%20Gru%C3%9F*%20bekommen.&subtitle=Bitte%20kurz%20best%C3%A4tigen%2C%20dass%20du%20echt%20bist.&select=Finde%20alle%20Felder%20mit&prompt=einer%20gemeinsamen%20Erinnerung.&help=Nur%20die%20obere%20Reihe.&cells=1%2C2%2C3&img1=https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dbild-1&img2=https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dbild-2&img3=https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dbild-3&question=Auf%20einer%20Skala%20von%20*0%20bis%20ja*%2C%0Awillst%20du%20mein%20Valentinsschatz%20sein%3F&scale=NEIN%2CHMM%2CJA&readouts=absolut%20nicht%2Cna%20gut%2Cja%20tausendmal&reveal=du%20bist%20mein%20*Valentinsschatz.*&msg=F%C3%BCr%20immer%20deine%3F

Before you send it

• Open the link in a private window and check language, names and wording.
• Tick the box, solve your own picture challenge, drag the slider to 100 % and confirm.
• Paste the link into the chat you will send it with. If it is too long there, use a URL shortener.

Host your own copy

The project is a folder of static files: no build step, no backend, no dependencies, and no request to any third party while it runs (fonts are self-hosted). Copy the folder to any static host (Cloudflare Pages, Netlify Drop, GitHub Pages, Vercel, nginx, Caddy, Apache) and it works. The link builder detects where it is hosted and builds links for that copy.

The optional online mode is the one part with a backend: a Cloudflare Worker with a database and picture storage. It lives in the repository under workers/valentine-captcha-api; setup, limits (config.json) and tests are in its README.md. Without it the builder hides the online mode. To switch it off even though a worker exists, set window.VALENTINE_CLOUD = { apiBase: "" } in config.js.

valentine-captcha/
├── index.html          the Valentine page
├── app.js              reads the link, draws the four screens (plain DOM)
├── styles.css          all styles, including @font-face
├── config.js           optional fixed settings for one copy
├── fonts/              Instrument Serif + JetBrains Mono, SIL OFL
├── favicon.svg, og-image.png
├── demo.js, demo/      the example as one query string, and its short address
├── docs/               this page
├── api/                API documentation for the online mode (page for people and AI)
├── llms.txt            complete instructions for AI agents: parameters, API, MCP
└── customize/          the link builder: index.html, editor.js, cloud.js

Serve .js as text/javascript and .woff2 as font/woff2; nearly every server does by default. For a local test run python3 -m http.server 8000 in the folder and open http://localhost:8000/customize/.

Where a value comes from

Every value resolves in this order, and the first non-empty one wins:

URL parameter   →   config.js   →   built-in text of the language

Fixed settings in config.js

For one recipient with a short address, fill in config.js instead of using parameters. Lists are real arrays there and need no encoding:

window.VALENTINE_CONFIG = {
  language: "de",
  to: "Sarah",
  from: "Alex",
  message: "Dinner is at 8.",
  images: ["/photos/us.jpg", null, null, null, null, null, null, null, null],
  selectAllWith: "", challengePrompt: "our cat.", correctCells: [1, 4, 9],
  title: "", subtitle: "", help: "", question: "", reveal: "",
  scale: ["NO", "MAYBE", "YES"], readouts: null,
};

Many recipients, pretty URLs

Keep everything static and render only config.js per address from your own backend, for example with Express:

app.use("/v/:slug", express.static("valentine-captcha"));
app.get("/v/:slug/config.js", async (req, res) => {
  const v = await db.valentine.findBySlug(req.params.slug);
  if (!v) return res.status(404).end();
  res.type("text/javascript").send(
    "window.VALENTINE_CONFIG = " + JSON.stringify({ to: v.to, from: v.from, images: v.images }) + ";"
  );
});

Only this route gives you per-recipient share previews; the static page can’t personalise them, because crawlers don’t run JavaScript.

Another language

All built-in texts live in the STRINGS object in app.js. Copy the en block, translate it, let the new code through in resolveLang(), and add a button for it in customize/index.html and loadFromLink() in customize/editor.js. The fonts only cover the Latin alphabet.

Safety

Every value from the link is escaped before it reaches the page, and *asterisks* and line breaks are turned into markup only after escaping. Anyone who edits app.js should keep that order. A test link that must render literally: ?to=%3Cb%3ESarah%3C%2Fb%3E.

Credits

Pictures in the example, all from Wikimedia Commons: kitten by André Karwath (CC BY-SA 2.5), blobfish by Rachel Caauwe (CC BY-SA 3.0), red panda by Mathias Appel (CC0), naked mole-rat by Trisha M. Shears (public domain), quokka by May Wong (CC BY 2.0), aye-aye by Frank Vassen (CC BY 2.0), marabou stork by Charles J. Sharp (CC BY-SA 4.0), fennec fox by Anass Errihani (CC BY-SA 4.0), corgi puppy by Huoadg5888 (CC0).

Typefaces: Instrument Serif and JetBrains Mono, both under the SIL Open Font License 1.1.