DEV Community: DEUS Automations

HTTP 402 is not reserved for future use anymore: I put a 1-cent paywall on a live API for AI agents

DEUS Automations — Sun, 20 Sep 2026 20:25:42 +0000

HTTP 402 has been "reserved for future use" since 1997. The future turned out to be AI agents that hold a wallet, and the spec that woke it up is x402: a payment challenge carried in the response body, settled in stablecoin, with no account, no API key and no signup on either side.

I shipped it on a real endpoint. You can hit it right now — the challenge is public, the paid call costs one cent, and the data behind it is a free CC BY 4.0 dataset. Everything below is a copy-pasteable curl against a live service.

The 30-second version

curl -s "https://piratefly.com/v1/x402/analisi?origine=Stockholm&destinazione=Rome"

You get an HTTP 402 Payment Required with a machine-readable body:

{
  "x402Version": 1,
  "error": "payment required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "resource": "https://piratefly.com/v1/x402/analisi?origine=Stockholm&destinazione=Rome",
    "description": "Booking-timing verdict for one flight route: cheap/normal/expensive vs that route's own price history, best months to fly, how far ahead to book.",
    "mimeType": "application/json",
    "payTo": "0xAC13DFB06F5c2Db996C881367E19387473Cf6480",
    "maxTimeoutSeconds": 60,
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  }]
}

maxAmountRequired: "10000" is 10,000 units of USDC on Base — six decimals, so $0.01. No key to request, no plan to pick, no email. An agent reads accepts, signs an EIP-712 authorization for exactly that amount, retries with an X-PAYMENT header, and gets the JSON.

That is the whole protocol. It fits in a paragraph because it has to: the client is a program that has never seen your docs.

Why 402 and not an API key

Machine buyers break the assumptions API keys are built on.

An API key is a relationship: someone signs up, agrees to terms, puts a card on file, and the key is the durable token of that relationship. That model assumes the buyer will come back, and that the cost of onboarding is amortized over many calls.

An agent buying one answer, once, has none of that. It found your endpoint 40 milliseconds ago, it wants one route analysed, and it will likely never call you again. Onboarding costs more than the sale. Under an API-key model the transaction simply does not happen — not because the buyer won't pay, but because there is no way to pay that fits inside one request.

402 collapses the relationship into the request itself. The price is in the response. The authorization is in the retry. There is no account to create, so there is nothing to abandon.

The other half matters just as much for a small operator: no chargebacks and no merchant identity. Settlement is a stablecoin transfer on Base, verified by a facilitator, final when it lands. You do not need a company, a KYC file, or a payment processor's approval to accept a cent. For anyone shipping from outside the usual jurisdictions, that difference is the difference between having a business model and not having one.

Implementing it: the part that actually bites

The protocol is small. Most of the implementation is about 40 lines of Hono. Here is the shape:

const RESOURCE_PATH = '/v1/x402/analisi';

app.get(RESOURCE_PATH, async (c) => {
  const origine = c.req.query('origine');
  const destinazione = c.req.query('destinazione');
  if (!origine || !destinazione) {
    return c.json({ errore: 'required params: origine, destinazione' }, 400);
  }

  const resourceUrl =
    `${baseUrl}${RESOURCE_PATH}?origine=${encodeURIComponent(origine)}` +
    `&destinazione=${encodeURIComponent(destinazione)}`;
  const paymentRequirements = requisiti(wallet.address, resourceUrl);

  const header = c.req.header('x-payment');
  if (!header) {
    return c.json({ x402Version: 1, error: 'payment required', accepts: [paymentRequirements] }, 402);
  }

  const payload = JSON.parse(Buffer.from(header, 'base64').toString('utf8'));

  const verify = await facilitator('verify', payload, paymentRequirements);
  if (!verify.isValid) {
    return c.json({ x402Version: 1, error: verify.invalidReason, accepts: [paymentRequirements] }, 402);
  }

  const body = await analizza(origine, destinazione);   // the actual work

  const settle = await facilitator('settle', payload, paymentRequirements);
  if (!settle.success) {
    return c.json({ x402Version: 1, error: settle.errorReason, accepts: [paymentRequirements] }, 402);
  }

  return c.json(body);
});

Two things in there cost me real debugging time, and neither is in the spec's happy path.

1. The resource URL must be the URL the buyer actually typed

paymentRequirements.resource is signed over. A strict client compares it against the URL it requested, and rejects the challenge if they differ. That sounds trivial until your service runs behind a reverse proxy.

My API sits behind Traefik with a path-strip rule. Inside the container, Host and X-Forwarded-Host describe the internal origin, not the public one buyers reach. Building resource from request headers produced a URL that was correct from the server's point of view and wrong from every buyer's — and it failed silently, as a payment the client declined to attempt.

So the public base URL is passed in explicitly at mount time, never inferred:

montaX402(app, sorgente, { baseUrl: 'https://piratefly.com' });

If you take one thing from this post: do not derive a signed value from a header a proxy is allowed to rewrite.

2. Verify before you work, settle after

verify is cheap and tells you the authorization is valid. settle is the on-chain move and can fail for reasons that have nothing to do with the buyer's intent. Put the work between them and you get the ordering you want: you never compute for a buyer who can't pay, and you never charge a buyer whose answer you failed to produce. If settle fails after the work is done, you eat the compute — which, for a database read, is the right side to lose on.

What the endpoint actually sells

A price is only honest if there's something behind it. The paid call returns a booking-timing verdict for one route, computed against that route's own observed price history: is today's fare cheap, normal or expensive; which months are actually cheaper; how far ahead to book.

The history is real and public. As of this writing:


price observations	728,194
routes tracked	48,731
routes published (≥5 observations)	24,283
route-months published	37,688
observation window	2026-06-14 → 2026-09-20
median fare	€114

It is mirrored daily to two places, CC BY 4.0, no account:

Hugging Face — DeusHorizon/flight-fare-history
GitHub — DeusAcc/flight-fare-history

import pandas as pd
url = "https://huggingface.co/datasets/DeusHorizon/flight-fare-history/resolve/main/routes.csv"
df = pd.read_csv(url)
print(df.nlargest(5, "observations")[["origin_city", "destination_city", "median_eur", "min_eur"]])

Publishing the data the paid endpoint reads from sounds like giving away the product. It isn't. The CSV is the history; the endpoint is the verdict — current fare percentile against that history, computed on a daily-refreshed table you'd otherwise have to rebuild yourself. Anyone willing to do the work can do it from the free file. Charging a cent is the price of not doing the work.

Free JSON is also available without any payment at GET /v1/analisi (same shape, OpenAPI at /v1/openapi.json), and there's a remote MCP server at https://piratefly.com/mcp if you'd rather let a model call it as a tool.

Is anyone actually paying?

Honest answer: the endpoint is live, registered in the public x402 resource directories, and has not yet earned a cent. I'm writing this at the stage where the mechanism works and the demand is unproven — which is, I think, the only interesting time to write about it, before the survivorship bias sets in.

What I can say with confidence is that the failure mode changed. Before, the reason an agent couldn't buy from me was structural: no signup flow a program can complete, no way to price one call. Now the reason would be that nobody wants the answer. That is a much better problem, and a measurable one.

If you're building something an agent might want to buy — a lookup, a verdict, a computation over data you maintain — the implementation cost is genuinely about an afternoon. The spec is at x402.org, the facilitator does the chain work, and your endpoint changes by one branch at the top.

Hit the 402 yourself:

curl -s "https://piratefly.com/v1/x402/analisi?origine=Stockholm&destinazione=Rome" | jq .accepts[0]

The service this runs on is PirateFly — flight fare history, free API, and the 402 endpoint above.

Happy to answer implementation questions in the comments — especially from anyone who has taken a 402 endpoint further than I have.

A free flight-price API that tells you buy or wait, not just today's fare

DEUS Automations — Tue, 15 Sep 2026 13:06:18 +0000

Every flight comparison site shows you today's cheapest fare. None of them will tell you to wait — it costs them the booking commission.

Piratefly watches flight prices over time and answers the actual question: is this price good, or should you wait? We just opened that logic up as a free JSON API.

The endpoint

GET https://next.piratefly.com/v1/analisi?origine=FCO&destinazione=BCN

Give it an IATA origin and destination, get back today's cheapest fare, where it sits against that route's own price history (percentile), and a buy/wait verdict.

curl "https://next.piratefly.com/v1/analisi?origine=FCO&destinazione=BCN"

Plans

Free — 30 requests/day per IP, no signup, no key.
Pro — $9.99/month — no daily cap. POST /v1/pro/checkout with your email, pay on Stripe, get an X-Api-Key back immediately.

Full machine-readable reference: https://next.piratefly.com/v1/docs
Landing page with the Pro checkout: https://next.piratefly.com/api

We only publish a verdict once a route has at least 8 price observations behind it — below that we say nothing rather than guess. Feedback and route requests welcome.

Your open-source repo's issue queue doesn't have to sit there for months

DEUS Automations — Wed, 09 Sep 2026 04:44:30 +0000

Small and medium open-source repos accumulate bug reports and feature requests that sit open for months because nobody has time to triage them. Every maintainer knows the feeling of opening the Issues tab and seeing 40+ items with zero labels, zero triage, zero idea which ones are quick fixes and which ones are rabbit holes.

GitHub Issue Triage BYOK is a small WordPress plugin that gives you a wp-admin dashboard listing a repository's open GitHub issues, with a one-click "Generate fix proposal" button. Click it and an AI model reads the issue title and body and gives you back a likely root cause, a concrete fix, and a suggested test — you copy, adapt, and act on it yourself.

A few things it deliberately does NOT do:

It never writes to GitHub, comments, labels, or opens pull requests. Read-only, always.
It doesn't ship an API key of its own. BYOK (Bring Your Own Key): you plug in your own GitHub token and your own AI key (any OpenAI-compatible chat completions endpoint works, not just OpenAI).
No subscription for the base functionality: the free version generates up to 20 AI fix proposals per month, which is enough to stay on top of a small/medium repo's queue. A one-time-payment Pro license removes the monthly cap if you need more.

Why WordPress and not a GitHub Action or a CLI tool? Because a lot of maintainers of small plugins/themes/tools already live in wp-admin for their own site, and having the triage dashboard one click away (rather than another terminal tab or CI log to check) is the difference between actually doing triage weekly and letting it pile up.

If you maintain a repo where issues outnumber your available time, it's on the WordPress plugin directory search and here: https://shop.lumnika.com/gh-issue-triage-byok.html

Happy to answer questions about the BYOK approach or how the fix-proposal prompt is built.

We Scanned Random Websites for Missing Alt Text. Even Wikipedia Failed.

DEUS Automations — Sat, 05 Sep 2026 02:47:50 +0000

Alt text isn't optional. Under WCAG 2.1 success criterion 1.1.1 ("Non-text Content"), every
meaningful image needs a text alternative — and it's one of the most commonly cited failures in
automated accessibility audits (WebAIM's Million report has flagged missing alt text as the
single most frequent error on the web for years running).

Finding every offending image by hand is the boring part, so we built a small crawler that walks
a site's public pages and flags every <img> with a missing or empty alt attribute. To sanity
check it, we pointed it at a handful of real, well-known domains instead of a synthetic test
page.

What it found

One of the sites we scanned was wikipedia.org. A single-page scan of the portal landing page —
the one that lets you pick a language — turned up an image with no alt attribute at all: the
Wikipedia wordmark logo itself (Wikipedia-logo-v2.png). One of the most-visited, most-audited
sites on the internet, and its own front door ships a logo image a screen reader has no way to
describe.

That's not a dig at Wikipedia specifically — it's the point. If a site with that much scrutiny can
ship an unlabeled image on its landing page, it happens everywhere, silently, on every site that
doesn't check for it systematically.

Why this keeps happening

A few patterns we see repeatedly when auditing real sites:

Logos and icons get skipped. Teams treat "obviously branding" images as exempt from needing alt text, but a screen reader user still needs to know what's there (or that it's purely decorative and should have alt="", not a missing attribute).
Alt text is added once, at launch, and never re-checked. New pages, new CMS templates, new marketing images ship without it because nothing in the pipeline catches the omission.
"Missing" and "empty" get conflated. A missing alt attribute is a hard WCAG failure. An empty alt="" on a genuinely decorative image is correct. Telling the two apart at scale is exactly the kind of repetitive checking that's easy to skip by hand and easy to automate.

Checking your own site

If you want to see this on your own domain rather than take our word for it, we put a free,
no-signup version of the same scanner online: it crawls up to 10 public pages, lists every image
with missing or empty alt text, and drafts a ready-to-paste alt text for each one using a vision
model.

Try the free scanner →

No login, no email required for the sample scan — paste a domain and see what it finds. The paid
version (CSV + report, up to 300 images) is there if you want the full site covered end to end,
but the free scan alone is enough to tell you whether it's worth doing.

Watching a Solana wallet without running your own RPC node

DEUS Automations — Thu, 03 Sep 2026 00:23:51 +0000

Watching a Solana wallet without running your own RPC node

If you want to know the moment a specific Solana wallet's balance moves — a treasury, a whale you're tracking, your own hot wallet for a security check — the "proper" way people reach for is running a dedicated indexer or paying for a webhook service like Helius. For a single wallet with modest polling needs, that's overkill.

Solana's public RPC (api.mainnet-beta.solana.com) is rate-limited but free, and it's enough to poll a wallet's SOL and SPL token balances on a schedule without an API key at all. Here's the pattern I used, in case you're about to build a similar watcher and don't want to pay for infra you don't need yet.

The loop

Poll every 5 minutes — getBalance for SOL, getTokenAccountsByOwner for SPL tokens, against the public RPC endpoint. No auth, no key.
Diff against last known balance — stored between runs (a simple key-value store is enough; I used n8n's built-in static data, but a Sheet or a Redis key works the same).
Threshold check — only fire an alert if the change exceeds a threshold you set. Without this, you get pinged on every dust transaction and start ignoring the channel within a day — the threshold is what makes the alert actually useful instead of noise.
Alert with context — a Telegram message with the delta and a link straight to the transaction on Solscan, so you don't have to go look it up.

Where the public RPC runs out

At low polling frequency (minutes, not seconds) and a handful of wallets, the public endpoint holds up fine. If you're watching dozens of wallets or need sub-minute latency, you'll hit rate limits and want to swap in a dedicated RPC (Helius, QuickNode, Triton) — the workflow is built so that's a one-field change, not a rewrite, since the RPC URL is a single credential.

If you want the built version

Packaged as an n8n workflow — polling, diffing, thresholding, and the Telegram alert with the Solscan link already wired up:

👉 https://shop.lumnika.com/solana-wallet-watcher.html?utm_source=devto&utm_medium=article&utm_campaign=solana-wallet-watcher

$14.99, one-time, no API key required to get started since it uses the public RPC by default.

Anyone else tracking wallets for security/ops reasons rather than trading? Curious what thresholds people settled on before the alerts stopped being noise.

Syncing a CRM with Odoo without paying for an iPaaS subscription

DEUS Automations — Thu, 03 Sep 2026 00:23:24 +0000

Syncing a CRM with Odoo without paying for an iPaaS subscription

Odoo is great as an ERP, but the moment sales wants to keep using HubSpot or Pipedrive as their CRM, you're stuck with a sync problem: contacts and orders need to exist correctly in both places, in both directions, without double-creating records or silently dropping updates.

The "just use Zapier/Make/Workato" answer works, but at CRM+ERP volume you're often paying $50-300/mo for what is, underneath, a scheduled poll and a webhook. I ended up building this as a plain n8n workflow instead, and wanted to share the pattern since it generalizes to basically any "sync system A with system B" problem, not just Odoo.

The two directions are not symmetric, and that matters

Odoo → CRM: a scheduled poll every 15 minutes, using Odoo's write_date field to pull only records changed since the last run (a delta sync, not a full table scan — this is the difference between a sync that stays fast at 50 records and one that stays fast at 50,000). Each changed res.partner or sale.order gets upserted into the CRM via its REST API.

CRM → Odoo: a webhook, because CRMs push changes in real time and there's no reason to wait 15 minutes for a lead update to land in Odoo. The webhook branches on whether the incoming record is new (create) or existing (update), matched by an external-ID field kept on both sides.

The asymmetry is the part people usually get wrong when they build this the first time: they either poll both directions (adds needless latency on the CRM side) or webhook both directions (Odoo doesn't push webhooks natively without extra modules). Poll the system that doesn't push, webhook the one that does.

Matching records without collisions

Both res.partner (contacts) and sale.order (orders) get an external-ID field synced on both sides at creation time, so updates always match the right record instead of relying on fuzzy matching (name + email, which breaks the moment someone has a typo or a duplicate).

If you want the built version

I packaged this as a 27-node n8n workflow — Odoo delta poll, CRM webhook with create/update branching, external-ID matching for both contacts and orders:

👉 https://shop.lumnika.com/crm-odoo-sync.html?utm_source=devto&utm_medium=article&utm_campaign=crm-odoo-sync

$49, one-time, works with HubSpot, Pipedrive, or any CRM with a REST webhook — you import it into your own n8n instance and point it at your credentials.

If you've built a two-way sync between other systems, I'd like to hear what matching strategy you used instead of external IDs — curious if anyone's had a cleaner approach.

Turning a folder of PDFs into a webhook that returns JSON

DEUS Automations — Thu, 03 Sep 2026 00:23:21 +0000

Turning a folder of PDFs into a webhook that returns JSON (no OCR infra to run)

If you've ever had to pull data out of PDFs at scale — invoices, ID scans, scanned forms, shipping manifests — you know the annoying part isn't the OCR itself, it's everything around it: standing up a service, handling the queueing, storing the output somewhere useful, and doing it all without paying for a $200/mo document-AI SaaS for what's often a low-volume internal tool.

I ended up solving this with a single n8n workflow instead of a custom service, and it turned out simpler than I expected, so here's the shape of it in case you're about to build the same thing from scratch.

The pipeline

Webhook in — POST a PDF URL (or upload) to a single endpoint.
OCR — the file goes to OCR.space, which has a genuinely usable free tier (25k requests/month, no card required). No self-hosted Tesseract, no GPU, no Docker image to maintain.
Text → structure — the raw OCR text gets parsed into a best-effort table: rows, columns, a JSON array, and a CSV export, using a mix of layout heuristics on the OCR bounding boxes.
Log (optional) — every extraction gets appended to a Google Sheet automatically, so you get a free audit trail without adding a database.
Response — the webhook returns plain text + structured JSON + CSV, so any app, script, or Zapier/Make alternative can call it directly.

The part worth calling out: because OCR.space is a hosted API, the whole thing runs with zero infrastructure of your own — n8n is the only thing you need to keep running, and if you already use n8n for other automations, this is just one more workflow, not a new service to babysit.

Where this breaks down

Layout-heavy PDFs (multi-column, dense tables with merged cells) will always need some manual review — no OCR pipeline gets that free. This is aimed at the 80% case: invoices, forms, receipts, single-column reports, where "close enough JSON" saves someone an afternoon of manual data entry.

If you'd rather not build it

I packaged the exact workflow — webhook, OCR.space call, structuring logic, optional Sheets logging — as a ready-to-import n8n template:

👉 https://shop.lumnika.com/pdf-ocr-extractor.html?utm_source=devto&utm_medium=article&utm_campaign=pdf-ocr

$19.99, one-time, JSON file you import into your own n8n instance — no subscription, no vendor lock-in, you can edit every node.

Curious if anyone here has fought with layout-heavy PDF extraction and found a heuristic that actually holds up — table detection is still the weakest link in every pipeline I've tried.

Is Your Shopify or WooCommerce Store an ADA/WCAG Lawsuit Risk? Free 2-Minute Check

DEUS Automations — Tue, 01 Sep 2026 11:34:02 +0000

Every year, ADA (Title III) web-accessibility lawsuits against US retailers keep climbing, and a huge share of them cite the same root cause: product images with no alt text. If you run a Shopify or WooCommerce store, that's usually not a design choice — it's just what happens when a catalog grows to hundreds or thousands of SKUs and nobody goes back to fill in alt attributes.

I wanted to know how exposed a "typical" store actually is, so I built a free scanner and ran it against a handful of real storefronts. Here's what I found, and the tool so you can check your own store in about two minutes.

Why missing alt text is a legal risk, not just an SEO nitpick

Screen readers rely on alt text to describe images to blind and low-vision shoppers. When a product image has no alt, or a generic one like IMG_4021.jpg, a screen reader either skips it or reads the filename — the shopper has no idea what they're looking at, can't tell products apart, and often can't complete checkout.

That's the exact pattern plaintiffs' firms look for before sending a demand letter: it's easy to prove (view source), easy to explain to a judge, and expensive to defend even when the claim doesn't go to trial. Settlements for small-to-mid retailers commonly land in the $5,000–$20,000 range — for something that's a content-population problem, not a code bug.

What the scan actually checks

I built ComplianceSnap to answer one narrow question fast: out of all the product images on your store, how many have no usable alt text?

You paste a store URL, it crawls the product pages, and it reports:

total product images found
how many are missing alt (or have placeholder/filename-only alt)
an estimated risk band based on catalog size and % missing (a 2,000-SKU store at 80% missing is a very different risk profile than a 40-SKU store at 10%)

It's read-only — it doesn't touch your store, theme, or admin, it just reads the public pages the same way a screen reader or a plaintiff's audit tool would.

What I found scanning real stores

Running it against a small sample of public Shopify/WooCommerce stores, the missing-alt rate ranged from under 10% (stores that clearly have an accessibility process) to over 70% (stores where alt text was never part of the product-upload workflow at all). The pattern held regardless of store size — it's a process gap, not a platform limitation. Both Shopify and WooCommerce support alt text natively; almost nobody fills it in by default.

If your scan comes back bad

The scan itself is free and doesn't require an account. If you want the missing alt text actually written (AI-generated, per image, reviewed before you publish), that's a paid step — the free scan is just there so you know whether it's worth doing before you spend anything.

Try it here: https://shop.lumnika.com/compliancesnap/?utm_source=devto&utm_medium=article&utm_campaign=ada-alt-text

Curious what other devs/store owners have seen on this — did anyone here actually get an ADA demand letter over image alt text, or is it mostly theoretical risk?

Why Most "AI Resume Builders" Produce PDFs That Fail ATS Parsers

DEUS Automations — Sat, 29 Aug 2026 15:56:15 +0000

If you've ever run your own resume through an ATS (Applicant Tracking System) parser and watched
your job title or bullet points come out garbled, you've hit a problem that has nothing to do with
your content and everything to do with how the PDF was built.

The root cause: PDF is a layout format, not a text format

A PDF doesn't store "a paragraph followed by another paragraph." It stores absolute-positioned
glyphs on a page. Most polished-looking resume templates get that layout from HTML+CSS rendered
through a headless browser (Puppeteer/Chromium), which is great for visual fidelity and terrible
for text order: multi-column layouts, sidebars, and floated elements often get flattened in
reading order that has nothing to do with visual order. An ATS parser reads the underlying text
stream top-to-bottom, left-to-right in insertion order — so a two-column template can silently
interleave your work history with your skills list, or drop your most recent job title into the
middle of a bullet point.

What actually fixes it

Two things matter more than template beauty:

Build the PDF with a low-level drawing API, not a browser. Libraries like pdfkit let you place text in the exact order you write it in code — single-column templates render sidebar accents as decoration (colored rectangles, icons) that never enter the text stream, so the parser only ever sees the real content, in the real order.
Always keep a resume-only fallback path. If you're generating resume content with an LLM (turning raw notes into structured bullet points, for example), the model call will eventually fail or time out. A parser that falls back to a deterministic, rule-based structuring of the same raw input — instead of failing the whole request — means the user still gets a correct, ATS-safe PDF even when the AI provider has a bad day.

A concrete example

I ended up building this into CV Forge, a small AI resume generator: raw notes
go in, an LLM (OpenAI-compatible, tested against Groq's Llama 3.3 70B) turns them into a structured
CV JSON, and pdfkit renders it with a single-column-first "Compact" template designed to stay
ATS-safe, alongside two more visual templates for when you're sending directly to a human. If the
AI call fails, a local parser produces the same structured JSON so the PDF still comes out
correctly formatted.

The lesson generalizes past resumes: any time you're generating a PDF that a machine will read
back, decide before picking a rendering approach whether text-stream order matters as much as
visual layout. If it does, skip the headless browser and reach for a library that lets you control
the text stream directly.

How to generate WCAG-compliant ALT text for WordPress images without sending them to a vendor's black-box API

DEUS Automations — Sat, 29 Aug 2026 12:55:27 +0000

If you've ever tried to fix accessibility on an old WordPress site, you know the drill: hundreds of images in the Media Library, most with empty alt attributes, and a WCAG 2.1 audit (or a client demanding one) breathing down your neck. Writing alt text by hand for 400 images is not a fun Tuesday. Every "AI alt text" SaaS I looked at wanted a monthly subscription, routed my images through their own servers, and gave me zero control over which model actually looked at the picture.

This post is about the plugin I built to fix that for my own sites, and the handful of implementation details that turned out to matter more than expected.

The actual problem

WCAG 2.1 Success Criterion 1.1.1 requires non-text content to have a text alternative. In WordPress terms: every attachment post of MIME type image should have _wp_attachment_image_alt set to something meaningful, not "IMG_4821.jpg" and not empty.

Doing this with a vision-capable LLM is trivial in principle — send the image, ask for a short description, save it as the alt attribute. The part that's not trivial, if you don't want another recurring SaaS bill and don't want to hand a third party your whole media library, is: whose API key, which model, and where does the image actually go.

Design decision: BYOK, not a hosted service

The plugin (Alt Text BYOK) doesn't call any server of mine. It calls whatever OpenAI-compatible chat/completions endpoint you configure, with your own API key. That's the entire trust model: your images go from your WordPress install directly to the provider you already chose (OpenAI, or any of the growing list of OpenAI-compatible vision endpoints), and nowhere else.

The settings are deliberately just four fields:

function atbyok_default_settings() {
    return array(
        'api_base'           => 'https://api.openai.com/v1',
        'api_key'            => '',
        'model'              => 'gpt-4o-mini',
        'language'           => 'English',
        'overwrite_existing' => '0',
        'license_key'        => '',
    );
}

api_base is the detail that matters most for portability: it's not hardcoded to OpenAI. Point it at any provider that speaks the same chat/completions shape with image content parts, and it works. That includes several free-tier vision models if you want to run the whole thing at zero cost.

The actual API call

Nothing exotic — a single chat/completions request with a multimodal content array (text instruction + image_url):

function atbyok_call_vision_api( $image_url, $settings ) {
    $endpoint = trailingslashit( $settings['api_base'] ) . 'chat/completions';
    $prompt   = sprintf(
        'Describe this image in %s as a concise, descriptive ALT text for web accessibility. ' .
        'Maximum 125 characters. Do not start with "image of" or "picture of". ' .
        'Reply with the ALT text only, no quotes, no extra commentary.',
        $settings['language']
    );

    $body = array(
        'model'      => $settings['model'],
        'messages'   => array(
            array(
                'role'    => 'user',
                'content' => array(
                    array( 'type' => 'text', 'text' => $prompt ),
                    array(
                        'type'      => 'image_url',
                        'image_url' => array( 'url' => $image_url ),
                    ),
                ),
            ),
        ),
        'max_tokens' => 60,
    );

    $response = wp_remote_post( $endpoint, array(
        'timeout' => 30,
        'headers' => array(
            'Authorization' => 'Bearer ' . $settings['api_key'],
            'Content-Type'  => 'application/json',
        ),
        'body'    => wp_json_encode( $body ),
    ) );
    // ... error handling, then trim/sanitize the returned text
}

Two prompt details earned their place after actually looking at model output on real sites:

"Do not start with 'image of' or 'picture of'" — screen readers already announce the element as an image; a generated alt text that starts with "Image of a dog running" is redundant and is explicitly called out as an anti-pattern in WCAG guidance. Without this instruction, GPT-4o-mini defaults to that phrasing constantly.
A hard character cap in the prompt, plus a second cap after the fact (mb_substr( $alt, 0, 160 )) — models don't reliably respect "maximum 125 characters" as an instruction, so the code truncates again server-side rather than trusting the model's arithmetic.

Finding the images that actually need it

The query that drives the bulk-fix screen is a plain WP_Query against attachments missing the meta key entirely — not empty string, missing, which is a different meta_query compare (NOT EXISTS vs =):

function atbyok_attachments_missing_alt( $limit = 50 ) {
    $q = new WP_Query( array(
        'post_type'      => 'attachment',
        'post_status'    => 'inherit',
        'post_mime_type' => 'image',
        'posts_per_page' => $limit,
        'meta_query'     => array(
            array(
                'key'     => '_wp_attachment_image_alt',
                'compare' => 'NOT EXISTS',
            ),
        ),
    ) );
    return $q->posts;
}

post_status => inherit is the detail that's easy to get wrong: attachments don't use the normal publish/draft statuses, they inherit their parent post's status (or inherit on their own when unattached). Query for publish here instead and you silently miss every unattached media-library image — which, in practice on most sites, is most of them.

Generating one at a time, on purpose

The admin UI processes images one AJAX call per image instead of batching them server-side into one big request. That's not an accident — a bulk endpoint that loops over 300 images inside a single PHP request runs straight into max_execution_time on any shared host, and a failure partway through gives you no idea which images actually got done. One request per image, driven by JS, means progress is visible and a timeout on image #214 doesn't lose the 213 that already succeeded.

The free-tier limit is deliberate, not a paywall trick

WordPress.org doesn't allow selling anything inside a plugin listed there, so the free version ships with a genuine cap — 30 generations/month, tracked with a month-keyed option that resets itself:

function atbyok_usage_get() {
    $data = get_option( 'atbyok_usage', array() );
    $ym   = gmdate( 'Y-m' );
    if ( ! is_array( $data ) || ( $data['ym'] ?? '' ) !== $ym ) {
        return array( 'ym' => $ym, 'count' => 0 );
    }
    return $data;
}

Using the current year-month as the array key instead of a scheduled cron job to reset the counter means there's no maintenance task that can silently stop firing — the counter just naturally starts over the first time atbyok_usage_get() runs in a new month.

Takeaways if you're building something similar

If you're integrating a vision model for a task with a strict output format (short, no boilerplate prefix, character limit), don't trust the prompt alone — enforce the hard constraints in code after the response comes back.
meta_query on attachments: always double check NOT EXISTS vs = '' vs plain absence — WordPress doesn't guarantee the meta row exists at all for older uploads.
Attachment post_status is not what you'd guess; query inherit, not publish, if you want all media library items regardless of whether they're attached to a published post.
For any bulk operation on a shared-hosting WordPress site, prefer many small requests over one big one. max_execution_time will find you eventually.

I'm the author of Alt Text BYOK, a WordPress plugin that does exactly what's described above — bring your own API key, images never touch a third-party server of mine, free tier included.