elementor/add-image inserts an Elementor image widget from an attachment ID or a URL.
Which of those two you use has consequences beyond convenience.
At a glance
| Ability | elementor/add-image |
| Toolset | Elementor — toolset/elementor |
| Group | Elementor › Elements & Widgets |
| Requires | Elementor, active on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
Attachment ID or URL
An attachment ID ties the widget to a media library item. Elementor can then serve the right registered size for the context, generate srcset for responsive delivery, and pick up the alt text stored on the attachment.
A URL gets none of that. The image is a fixed reference to a fixed file: one size for every device, no responsive set, and no alt text unless it is set on the widget.
So an attachment ID is the right choice for anything on this site, and a URL is for images genuinely hosted elsewhere.
The size parameter selects among WordPress’s registered sizes, which only means anything with an attachment ID.
Alt text is not a parameter here because it belongs on the attachment, where every use of the image benefits from it. An image used in three places should not need its alt text written three times.
Not idempotent.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
post_id | integer | Yes | The post holding the Elementor document. |
attachment_id | integer | One of these two | A media library attachment ID. |
url | string | One of these two | A direct image URL. |
size | string | No | A registered image size. Only applies with an attachment ID. |
align | string | No | Alignment. |
caption | string | No | A caption shown beneath the image. |
link | object | No | A link wrapping the image. |
parent_id | string | null | No | The element to insert into. Null or omitted inserts at the document root. |
position | integer | No | Index among the parent’s children. Omitted appends at the end. |
What comes back
| Name | Type | What it is |
|---|---|---|
post_id | integer | The post written. |
element_id | string | The ID of the element created or affected. |
element | object | The element as stored. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Add the hero image to that container.
It resolves to one call:
{
"ability": "elementor/add-image",
"parameters": {
"post_id": 412,
"attachment_id": 2201,
"size": "large",
"parent_id": "a1b2c3d"
}
}Worth knowing
- An attachment ID gets responsive sizes and the stored alt text. A URL gets neither.
- Alt text belongs on the attachment, not on each widget.
- The size parameter needs an attachment ID to mean anything.
- Not idempotent.
Related abilities
- Add Elementor Container — a background image instead
- Find Elementor Elements — audit images across a page
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category