wp_set_featured_image: set a featured image

Assigns an attachment as a post's featured image, or removes the one it has.

Arguments

Omitting media_id removes the featured image

That is the whole removal mechanism — there is no separate tool and no explicit "remove" flag. Calling with only post_id deletes the post's featured image and returns a thumbnail_id of 0.

It is worth stating plainly because it is easy to trigger by accident. A client that builds the arguments and drops media_id — because a lookup returned nothing, or a variable was empty — removes the image rather than failing.

If you are assigning, confirm the response's thumbnail_id is the ID you expected and not 0.

The capability is on the post, not the image

Allow content writes open, and edit_post on the target post.

There is no capability check against the attachment. A user who can edit a post can assign any attachment in the library to it, including one they did not upload.

That is consistent with how WordPress itself behaves, and it means the acting user's reach over posts is what governs this tool.

The tool does not validate the attachment

media_id is used as given. Nothing checks that:

• the ID is an attachment rather than a post;
• the attachment is an image;
• the file still exists on disk.

So a wrong ID produces a silently wrong or broken featured image rather than an error. Read the attachment first:

Read media 1180 and show me its title and URL, then set it as the featured image for post 412.

The post type must support thumbnails

If the target post type does not declare thumbnail support, the assignment is stored but nothing displays it.

Check with wp_get_post_types, whose supports list answers this directly.

What it returns

The post_id and the resulting thumbnail_id. Reading that back is the confirmation — 0 means the image was removed.

The dry run reports the same two values without writing, which is a cheap way to confirm the arguments were built as intended.

Size still matters

Assigning an image does not resize it. WordPress renders the featured image at whatever size the theme asks for, generated from the original — so a small original produces a soft or undersized hero.

The tools report no dimensions, so open the attachment's url and look before assigning it to a prominent slot. See wp_get_media_item.

After assigning

• Open the post on the front end and check the image appears at the right crop.
• Check any archive or listing page, which often uses a different generated size.
• Purge the cache.

Using it well

Set media 1180 as the featured image for post 412, then read the post back.

To remove:

Remove the featured image from post 412.

For several posts, name the pairs explicitly rather than describing a rule:

Set 1180 on post 412, and 1181 on post 415. Nothing else.

Common problems

Related

• wp_get_media_item — confirm the attachment first
• wp_upload_media
• Upload and assign a featured image