pom://site/media-authoring-guide: place generated media safely

This Markdown resource covers the handoff between image generation, the WordPress Media Library, and POM builder markup. It is useful when an AI client can create an image but still needs a durable WordPress attachment.

Plan by image role

Decide first whether the asset is a hero, section image, card thumbnail, background, gallery item, or featured image. The role determines aspect ratio, crop tolerance, alternative text, and whether a shortcode expects an attachment ID or URL.

Supported sequence

1. Generate or obtain the image in the client.
2. Upload it with wp_upload_media using either base64 data or a supported public image URL.
3. Add a meaningful title, alternative text, caption, or description with wp_update_media where the content requires it.
4. Read the target shortcode schema.
5. Put the returned attachment ID or URL in the exact documented attribute.
6. Set the featured image separately with wp_set_featured_image when needed.
7. Validate the complete builder content and then save.

Remote imports accept public HTTP or HTTPS raster images within the media tool’s size limit. Redirects, private or local hosts, unsafe addresses, non-image payloads, and oversized downloads are rejected. Base64 uploads are still checked against the declared extension and the detected file type.

Editorial checks

The upload response proves that WordPress created an attachment; it does not prove the image is accurate, licensed, accessible, or well cropped at every breakpoint. Preview the real page, confirm alternative text describes function rather than appearance alone, and avoid embedding sensitive source images in client prompts.

Related guides: prepare media recipe, media upload tool, and create a page with generated media.