Upload and assign a featured image

Two ways to get an image into the media library, then one step to attach it. The upload tools are deliberately constrained, so knowing the limits saves a confusing failure.

The two upload tools

Both are write tools and need Allow content writes open, plus upload_files on the acting user.

The constraints on URL uploads

wp_upload_media_from_url is the more restricted of the two, because it makes your server fetch something:

• Private and reserved addresses are refused. A URL resolving to an internal IP is rejected, so the tool cannot be pointed at your own network.
• Redirects are not followed. The URL must return the image directly. A shortener, a CDN redirect or an http to https redirect all fail.
• 10 MB maximum.
• Only JPEG, PNG, GIF, WebP and AVIF are accepted.
• The response must be successful — no 404, no error page.

The redirect rule catches people most often. A URL that works in a browser may still fail here, because the browser followed a redirect the tool will not.

The base64 route

wp_upload_media takes the image data directly, which avoids all the URL constraints. It accepts a plain base64 string or a data:image/…;base64, payload, and requires a filename.

Use it when the image comes from the assistant itself, or when the source URL redirects.

Upload, then read back

Upload this image from URL, then show me the resulting attachment ID, filename and dimensions.

The response gives you the attachment ID. Everything afterwards refers to it.

Read it back with wp_get_media_item and confirm the dimensions are what you expected — a downscaled or unexpectedly small image is easier to catch now than after it is placed on a page.

Write the alternative text yourself

Uploading does not create alternative text. wp_update_media sets the title, alt text, caption and description.

Set the alt text for media 1180 to "Technician inspecting a circuit board".

Alt text should convey the image's purpose in context rather than describe its contents, and decorative images should have empty alt text. An assistant asked to "add alt text" produces a description of what it thinks the image shows, so review it. See Write alternative text that helps.

Assign it

As a featured image:

Set media 1180 as the featured image for post 412.

wp_set_featured_image takes the post and the attachment.

Inside content: the image is referenced in the post or page content like any other attachment. For builder pages, read the shortcode schema first so the image is placed with valid markup — see Build POM builder content.

Check it rendered

Open the page. Confirm the image appears, at a sensible size, with the crop you expected. WordPress generates its registered sizes from the upload, so a small original cannot produce a large rendering.

Then purge the cache if the site uses one.

Generated images

If the assistant generated the image, everything in Review generated and edited images applies before it goes on a public page: artefacts, text inside the image, recognisable people, trademarks, and honesty about products.

Note that POM AI's own image generation is a separate feature in the WordPress administration and is not exposed over MCP. An image arriving through MCP came from the client, not from POM AI. See What POM AI MCP does not expose.

Deleting media

wp_delete_media removes an attachment. Unlike posts, media deletion is not recoverable from the trash, and any page referencing the file shows a broken image afterwards.

Before deleting, establish where it is used. If you cannot, do not delete it.

Common problems

Related

• Media tools
• Image tools for POM AI's own image features