Black Friday 2025
Save 30% on all RankPilotAI WordPress plugins with coupon BLACK30.
00
Days
09
Hours
00
Minutes
00
Seconds
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 and the attachment edit screen). When pressed, it calls RankPilotAI, analyses the image and writes an alt text that scores 100 out of 100 whenever it stays at or below 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 and activate via Plugins ▸ Add New ▸ Upload.
- After activation you are 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 model, language and prompt
On the Alt-Text Settings tab select a GPT model, choose the default language and (optionally) write a Custom Prompt. Available models: GPT-4o-mini (always available), GPT-4.1 (Starter and higher) and GPT-4o (Creator and Expert). Your custom prompt is appended to the built-in instructions and takes priority over general rules; the 125-character limit always applies.
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 and permissions, then calls generate_via_rankpilot(). |
| Token guard | Checks remaining tokens against the selected model cost: mini = 1, 4.1 = 3, 4o = 5. If insufficient, the user sees Not enough tokens for the selected model. |
| RankPilotAI API | Image URL, current alt, model, language and prompt are sent to /alt-text; the API returns JSON with alt_text. |
| Meta update | String saved to _wp_attachment_image_alt and score to _aatb_score. |
| UI refresh | JS inserts the 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 and 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 this via the 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 tokens based on the selected model: GPT-4o-mini uses 1 token, GPT-4.1 uses 3 tokens and GPT-4o uses 5 tokens. Remaining tokens and membership tier are auto-detected from your Site Key and determine which models appear enabled in the dropdown. Plan gating: Free → mini only; Starter → mini and 4.1; Creator and Expert → mini, 4.1 and 4o.
9. Settings Reference
| Tab | Option | Description |
|---|---|---|
| Site Key | Site Token | Unique identifier linking your site to RankPilotAI. |
| Alt-Text Settings | GPT Model | gpt-4o-mini (economical), gpt-4.1 (balanced) or gpt-4o (premium). Disabled options indicate a plan upgrade is required. |
| Alt-Text Language | English, German, French, Spanish, Turkish or a custom locale using the Other / Custom input. | |
| Custom Prompt | Optional brand or style guidance appended to the built-in prompt; your note overrides general rules but the 125-character limit always applies. Input is truncated at 1,500 characters for safety. |
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 your plan; the error bubbles from the API. |
| Not enough tokens for the selected model | Your remaining balance is lower than the chosen model cost. Switch to a cheaper model or buy tokens. |
| Generation button disabled | Save a valid Site Key and ensure the user has upload_files capability. |
12. Changelog (highlights)
- 2.2.0 – Added Balanced model (GPT-4.1) and Custom Prompt field; updated token costs.
- 2.1.0 – Multi-language support; GPT-4o option; improved prompt.
- 2.0.0 – Bulk generation and token dashboard.
- 1.x – Initial public release.
13. Support
Docs and 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.