AI Alt Text Builder Documentation
Generate concise, SEO-friendly image alt text in one click — powered by RankPilotAI.
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.
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.
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(). |
| 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 success / failure counts in an admin notice.
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). |
| Default Language | English, German, French, Spanish, Turkish or custom. | |
| Custom Prompt | Optional — override the default prompt template sent to RankPilotAI. |
10. Developer Hooks
| Hook | Type | Purpose |
|---|---|---|
aatb_length_score() | Function | Public helper – reuse for custom scoring. |
aatb_generate_alt | AJAX action | Triggered on each generation request. |
aatb_settings | Option array | Stores all plugin settings; extend to persist custom fields. |
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. |
| Generation button disabled | Save a valid Site Key and ensure 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
Need help? Just email [email protected] with your site URL and a short description of the issue.
We’re here to help — let us know how we can boost your image SEO with AI!