AI Content Tools (pro, off by default)

Generate SEO meta descriptions and image alt text from the WordPress post editor, using Claude or OpenAI. Entirely WordPress-side — no Next.js env vars, no changes to your frontend deployment.

Setup

Headless Core → Settings → AI Content Tools (requires a valid pro license):

1. Choose a provider: Claude (Anthropic) or OpenAI.
2. Paste the matching API key (only the selected provider's key is used — you don't need both).

Once a key is set, a "AI Content Tools (Pro)" panel appears in the document settings sidebar of the post/page editor.

What it does

Generate SEO Description

Sends the post title + content to the configured provider, asks for a concise (under 155 character) meta description, and writes the result into the post's Excerpt field — the same field this theme's frontend already uses as the meta description source (getContentByUri() / buildMetadata() on the Next.js side, see GraphQL Reference). No new custom field is introduced.

Generate Featured Image Alt Text

Sends the post's featured image to the provider's vision endpoint, asks for a concise (under 125 character) alt text, and saves it via WordPress core's own REST API (POST /wp/v2/media/{id}) — the same endpoint the Media Library's "Alternative Text" field uses. Targets the featured image only; per-image alt text for images embedded inside the post body isn't covered in v1.

How requests are authorized

Both generateSeoDescription and generateImageAltText are GraphQL mutations on the same public WPGraphQL endpoint as everything else in this theme — but unlike submitContactForm/subscribeNewsletter (which are meant to be public), these two require both:

1. A valid pro license (headlesscore_get_license_status()['valid'])
2. current_user_can('edit_posts') for the request's authenticated user

The license check alone isn't enough — it only proves the site has a valid license, not that the caller is an authorized editor. Without the capability check, any anonymous visitor hitting the public GraphQL endpoint directly could call these mutations repeatedly and burn your Claude/OpenAI API credits for free. The editor sidebar JS sends credentials: "same-origin" so the WordPress auth cookie is included, which is what makes the capability check pass for a logged-in editor.

Provider details

	Claude	OpenAI
Model	claude-3-5-haiku-latest	gpt-4o-mini
API	Messages API	Chat Completions
Image input	Fetched + base64-encoded server-side (PHP wp_remote_get)	Passed as a plain URL directly
Timeout	30s (wp_remote_post blocking call)	30s

Both calls are blocking wp_remote_post() requests — a departure from this codebase's other outbound HTTP calls (the contact-form and revalidation webhooks are fire-and-forget, 'blocking' => false), because these need the response body. If a provider is slow, the request can take up to the 30s timeout; this is acceptable for short text generation but worth knowing if you see editor requests hang briefly.

Deferred (not in v1)

• Bulk/batch generation — e.g. "generate alt text for every image missing one." v1 is one-at-a-time, editor-triggered.
• Response caching/deduplication — repeated calls for the same content re-hit the provider and re-bill you. Not solved here; a known cost concern if you regenerate often.
• Anything beyond SEO description + alt text — no full content generation, no other AI features. Deliberate boundary, not a placeholder for "coming soon."
• Streaming responses — plain blocking request/response only.
• In-body image alt text — only the featured image is covered, not images embedded within Gutenberg blocks in the post content.