wp_update_media: update media metadata

Changes an attachment's title, caption, description or alternative text. It does not touch the file itself.

Arguments

Only the fields you pass are changed.

Permissions

Allow content writes open, and edit_post on the attachment.

The four fields do different jobs

Do not put the same string in all four. A caption repeating the alt text means a screen-reader user hears the same sentence twice.

Alt text is the one that matters

It is also the one an assistant gets wrong most predictably, because good alt text describes the image's purpose in context and the assistant can only see the image.

The same photograph needs different alt text on a careers page, beside a testimonial, and as a decorative header — where it should be empty.

An assistant asked to "add alt text" will never produce empty alt text. Clearing it on decorative images is a correction only a human can make. See Write alternative text that helps.

There is no undo

Attachments do not have revisions. Overwriting alt text that someone wrote carefully replaces it permanently.

Two consequences:

Read before writing, and keep the old values:

Show me the current alt text and caption for media 1180, then update the alt text to "…".

Select images that are missing values, not everything. wp_get_media returns the current metadata, so an assistant can identify the empty ones:

List the media, tell me which have empty alt text, and stop.

Then update only those IDs.

The dry run reports the request, not a comparison

Unlike the post update dry run, this one echoes the changes you asked for — it does not show a before-and-after.

So the dry run confirms the arguments were parsed as intended; it does not show you what you are about to overwrite. For that, read the item first.

Values are sanitised as plain text

All four fields go through text sanitisation, so HTML in a caption or description will not survive as markup. Write plain text.

What it returns

The updated attachment in the standard shape.

Doing a batch

Writes are capped at 20 per minute, so a metadata pass over a large library is paced regardless. Use that pacing:

Update the first five, show me the results, then stop.

Read every result. A batch of generated alt text that nobody reads is a batch of plausible descriptions, some of which are wrong about product names, numbers and colours — the specifics that matter most.

Common problems

Related

• wp_get_media_item — read before writing
• wp_get_media — find the gaps
• Generate image metadata in bulk — POM AI's own tool for the same job