AI Alt Text Builder Documentation
Generate concise, SEO-friendly image alt text in one click — powered by RankPilotAI.
Contents
1. Plugin Overview
AI Alt Text Builder adds a Generate with AI button to the WordPress Media Library (bulk actions & attachment edit screen). When pressed, it calls RankPilotAI, analyses the image and writes an alt-text that scores a perfect 100/100 whenever it stays ≤ 125 characters.
Also in Media Library: a colour-coded Alt Score column and a dropdown filter (With Alt Text / Without Alt Text) to quickly find images that need attention.
2. Minimum Requirements
| Version | |
|---|---|
| WordPress | 6.0 or later |
| PHP | 8.0 or later |
| RankPilotAI Site Token | Generate inside the plugin’s Site Key tab |
3. Installation
- Download the ZIP from your RankPilotAI account.
- Upload → Activate via Plugins ▸ Add New ▸ Upload.
- After activation you’re redirected to Settings ▸ AI Alt Text Builder.
Tip: On first activation the plugin creates a placeholder Site Key for convenience; replace it with your real Site Key from RankPilotAI before generating.
4. Quick-Start
4.1 Add your Site Key
Open the Site Key tab, paste the token and click Save. A green success notice confirms server-side validation.
4.2 Choose your GPT model & language
On Alt-Text Settings tab select GPT model and default language. GPT-4 Turbo is always available; GPT-4o unlocks on paid plans.
5. How Generation Works
| Step | What happens |
|---|---|
| UI click | Button dispatches admin-ajax.php request with action aatb_generate_alt. |
| Server handler | ajax() validates nonce & perms, then calls generate_via_rankpilot(). |
| Token guard | Checks remaining tokens against selected model cost (Turbo = 1, 4o = 3). If insufficient, returns “Not enough tokens for the selected model”. |
| RankPilotAI API | Image URL, current alt, model & language sent to /alt-text; JSON alt_text returned. |
| Meta update | String saved to _wp_attachment_image_alt and score to _aatb_score. |
| UI refresh | JS inserts alt-text and paints the score badge. |
6. Alt-Length Score
The helper function aatb_length_score() evaluates final alt-text:
| Length | Score |
|---|---|
| 0 chars | 0 |
| ≤ 125 | 100 |
| ≤ 150 | 80 |
| ≤ 175 | 60 |
| ≤ 200 | 20 |
| > 200 | 0 |
Scores appear as colour-coded badges in Media Library list view and on the attachment page.
7. Bulk Generation
Select multiple images in Media ▸ Library ▸ List view → Bulk Actions → Generate with AI Alt Text Builder. The plugin queues each ID, processes sequentially and displays live progress (processed / success / failed) with a Cancel button. On completion, success/failure counts appear in admin notices.
Under the hood, bulk runs call the /alt-batch endpoint. Default batch size is 6 per tick (developers can change via aatb_bulk_chunk filter).
Quick Filters: Use the Media Library dropdown AI Alt Text Builder → With Alt Text or Without Alt Text to focus your work.
8. Token Usage & Plans
Every successful generation consumes 1 token (GPT-4 Turbo) or 3 tokens (GPT-4o). Remaining tokens and membership tier (Free, Starter, Pro…) are auto-detected from the Site Key and determine which models appear in the dropdown.
9. Settings Reference
| Tab | Option | Description |
|---|---|---|
| Site Key | Site Token | Unique identifier linking your site to RankPilotAI. |
| Alt-Text Settings | GPT Model | gpt-4-turbo (economical) or gpt-4o (premium). |
| Alt-Text Language | English, German, French, Spanish, Turkish or custom. |
Greyed-out options indicate a plan upgrade is required.
10. Developer Hooks
| Hook / Helper | Type | Purpose |
|---|---|---|
wp_ajax_aatb_generate_alt | AJAX action | Triggered on single-image generation. |
wp_ajax_aatb_bulk_step / wp_ajax_aatb_bulk_cancel | AJAX actions | Bulk job scheduler and cancel handler. |
aatb_bulk_chunk | Filter | Change bulk chunk size (default 6 per tick). |
aish_http_args, aish_http_retry_codes, aish_http_retries, aish_http_result | Filters | Customize HTTP request args, retry codes/count and inspect results. |
aatb_length_score() / aatb_calc_score() | Functions | Public helpers to compute the length-based Alt Score. |
aatb_is_placeholder_alt() | Function | Detects placeholder-like alt text strings. |
11. Troubleshooting
| Symptom | Resolution |
|---|---|
| 403: bad_nonce / refresh | The nonce expired. Reload and try again — JS already retries automatically. |
| “No tokens left” | Top-up tokens or upgrade plan; error bubbles from API. |
| “Not enough tokens for the selected model” | Your remaining balance is lower than the chosen model’s cost. Switch to GPT-4 Turbo or buy tokens. |
| Generation button disabled | Save a valid Site Key and ensure the user has upload_files capability. |
12. Changelog (highlights)
- 2.1.0 – Multi-language support; GPT-4o option; improved prompt.
- 2.0.0 – Bulk generation & token dashboard.
- 1.x – Initial public release.
13. Support
Docs & FAQs: rankpilotai.com/docs
Email: [email protected]
Slack: #rankpilotai-support
Feel free to reach out—our team will be happy to help you boost your on-page SEO with AI!