Recipe: prepare WordPress media before authoring

Use this recipe when images already exist as files, base64 data, or public URLs and need durable Media Library records.

Plan the media needed for [PAGE OR POST] by role. Search the Media Library for
an existing suitable attachment before uploading a duplicate. For each new
asset, verify its source, file type, size, and rights; upload it with
wp_upload_media; then set an accurate title, alternative text, caption, and
description as appropriate. Report each attachment ID, URL, dimensions, and
metadata. Do not place it in content or set it as featured media until I
confirm the intended role.

Remote imports must be public raster-image URLs and are rejected when they redirect, resolve to a private host, exceed 10 MB, or fail content validation. Base64 uploads also need a declared filename whose extension agrees with the detected image.

Alternative text should explain the image’s purpose in its final context. Decorative images may need empty alt text; captions and descriptions are not substitutes.

After the assets are approved, read the target shortcode schema to learn whether it expects an attachment ID or URL. Featured media is handled by its own tool.

Related guides: media authoring resource, upload media, and update media metadata.