OpenAI Integration

jekcms uses OpenAI (GPT-4 class models) for three built-in features:

1. Inline content assist — "continue writing", "make this shorter", "rewrite formally" buttons in the editor
2. Bulk generation — Feed the AI a list of topics and let it draft posts in the background
3. Alt-text & excerpt automation — Auto-generate accessible alt text for images and SEO-friendly excerpts

You can also use Gemini as a free alternative for most of the same features. If both keys are set, you can pick which model handles each feature.

Getting an API key

1. Go to [platform.openai.com](https://platform.openai.com) and sign in
2. API keys → Create new secret key
3. Copy the key (you won't see it again)
4. Add billing info — the free trial only covers a few thousand tokens

Adding the key to jekcms

1. Admin → Settings → API Keys
2. Paste the key into OpenAI API key
3. Save

The key is encrypted at rest (AES-256, site-specific fingerprint). Anyone with read access to your database alone can't decrypt it — they'd need the encryption key which lives in your config.php.

Picking a model

Under Settings → AI → Model preferences:

• gpt-4o-mini — Default. Cheap (~$0.15/M input tokens), fast, plenty smart for most blog content.
• gpt-4o — Smarter but 10× the cost. Use for complex rewrites or technical explanations.
• o3-mini — Reasoning-heavy. Best for anything needing multi-step logic. Slower, costs between the two above.

You can override per-feature — e.g., use gpt-4o-mini for alt text (it's a trivial task) but gpt-4o for bulk long-form generation.

Content assist buttons in the editor

With an OpenAI key saved, the post editor sidebar shows an AI Assist panel with:

• Continue writing — From the cursor position, generates the next 1–3 paragraphs
• Improve — Rewrites the selected text keeping meaning but fixing grammar/flow
• Shorten — Compresses without losing key information
• Expand — Adds detail and examples
• Rewrite formally / casually — Tone shifts
• Explain this — Turns a technical passage into a plain-language explanation

Every button call streams results token by token — you'll see the text appear as the model generates it. You can cancel mid-stream.

Bulk content generation

Admin → Content → Bulk Queue → New batch

1. Upload a CSV or paste a list of topics (one per line)
2. Pick a template — e.g., "How-to article, 800 words, 3 H2 sections, FAQ at end"
3. Set limits — max tokens per post, total budget cap, posts per minute
4. Start

The queue runs in the background (cron worker). You can monitor progress in real time — each item shows pending → generating → done and you can preview each generated post before it moves to Drafts.

Important: budget caps

Always set a hard budget cap — e.g., $10 per batch. Without it, a malformed template loop could burn through $100s of credits while you sleep.

Alt text automation

When you upload an image, jekcms can automatically generate an alt text using vision models:

• Admin → Settings → AI → Image alt-text → toggle Auto-generate on upload
• Or manually: go to Media → select image → Generate alt text

The model sees the image and writes a description suitable for screen readers. You can override the auto-generated text by editing the media row.

Cost monitoring

Admin → AI → Usage shows:

• Token usage per feature (assist / bulk / alt-text) per day
• Estimated cost based on current OpenAI pricing
• Top 10 posts by AI tokens consumed
• Alert threshold — emails you when monthly spend crosses a limit

Troubleshooting

"Rate limit exceeded." OpenAI tiers new accounts with low per-minute caps. Either wait for the cooldown (shown in the error message) or upgrade your OpenAI account tier.

"Invalid API key." The key was rotated, revoked, or pasted with trailing whitespace. Re-paste from the OpenAI dashboard, being careful not to include surrounding quotes.

Bulk queue stuck at "generating". Check Automation → Scheduled tasks — the ai_bulk_worker task should run every minute. If it's not running, your host doesn't have cron configured. The bootstrap-side fallback (~2% of web requests drive one queue item) will still make progress, just slower.

Generated content is low quality. Adjust your template — include example outputs, add style constraints, specify reading level. OpenAI follows instructions; better instructions = better output.