Stock Images

EMCP Tools searches three stock photo providers: Unsplash, Pexels and Pixabay. Each needs its own free API key, and you need at least one before search-images or add-stock-image can run.

Adding your API keys

1. Open EMCP Tools → Connection and choose the 3rd-party services section.
2. In the Stock images card, paste a key into the Unsplash, Pexels or Pixabay field. Each field has a Get a key link to the provider’s developer page.
3. Choose Save changes in the save bar at the bottom of the screen. Keys are stored encrypted, and a saved key is never shown again: the field reads “Saved. Type to replace it.” Use Clear to remove one.

You can also define the keys in wp-config.php with EMCP_TOOLS_UNSPLASH_ACCESS_KEY, EMCP_TOOLS_PEXELS_API_KEY or EMCP_TOOLS_PIXABAY_API_KEY. A constant wins over the saved value, and its field shows “Set in wp-config.php”.

When no provider is passed, the tools use the first provider with a key, in the order Unsplash, Pexels, Pixabay.

emcp-tools/search-images

Searches a stock provider by keyword. Registers with or without Elementor.

Input:

• query (required): search terms
• provider: unsplash, pexels or pixabay; omit to use the first connected one
• page: page number, default 1
• page_size: results per page, default 5
• aspect_ratio: wide (landscape), tall (portrait) or square

Returns: { provider, result_count, page, page_count, results }, where each result has id, title, url, thumbnail, width, height, creator, creator_url, license, license_url, attribution, source and foreign_landing_url.

Capability: edit_posts.

emcp-tools/sideload-image

Downloads an external image URL into the WordPress Media Library as an attachment. Pass the exact url from a search result; a constructed or edited URL usually fails. Private, reserved and loopback hosts are refused, and every redirect is checked again. Registers with or without Elementor.

Input:

• url (required): external image URL
• title: optional, defaults to the filename
• alt_text: optional, accessibility text
• caption: optional
• attribution: optional, stored as the attachment caption
• convert_webp: default true; set false to skip WebP conversion when it times out on shared hosting

Returns: { attachment_id, url, title }.

Capability: upload_files.

emcp-tools/add-stock-image

The composite tool: searches a provider, sideloads the chosen result, and adds an image widget to an Elementor page. One call instead of three. It registers only while Elementor is the builder selected on EMCP Tools → Page Builders.

Input:

• post_id, parent_id, query (all required)
• provider: optional, as for search-images
• index: which search result to use, default 0 (best match)
• position: child index, -1 to append (default)
• aspect_ratio: wide (default), tall, square or any
• image_size: thumbnail, medium, medium_large, large or full (default)
• align, caption, alt_text, link_to (none, file, custom), convert_webp

Returns: { attachment_id, image_url, element_id, original_url, attribution, provider }.

Capability: edit_posts + upload_files + ownership check.

emcp-tools/list-media

Lists and searches images already in the Media Library, so an agent can use the site’s own photos before reaching for stock ones. No API key needed.

Input (all optional): search (matches title, alt text, caption and description), mime_type (default image; any for every type), page, per_page (1 to 100, default 20), orderby (date or title), order (desc or asc).

Returns: { result_count, page, page_count, total, results }, each result with id, title, url, thumbnail_url, alt, mime_type, width, height, filesize and date.

Capability: edit_posts. Read-only. For full detail on one attachment, editing and deleting, see Media Library.

Where the switches are

All four tools are enabled by default. Their switches are in the Stock & Media Images section of the WordPress tab on EMCP Tools → Tools, together with the Media Library tools.

Why three tools instead of one

add-stock-image is the convenient path for the AI when it just needs “an image for this hero section.” But sometimes you want the search results without inserting anything (let the AI pick from a list), or you want to sideload a specific external image URL the user provided. The three separate tools cover all three workflows without compromising any of them.

Attribution

Each provider has its own license terms, and results carry the photographer’s name and an attribution string. add-stock-image uses the attribution as the default caption unless you pass caption. If the page is somewhere attribution matters, ask the AI to keep a small credit next to the image.

Tip

Wide search queries return better images than narrow ones. “Bakery interior” beats “warm artisan French boulangerie storefront with wooden door at sunset”.