wp_set_featured_image: establece una imagen destacada
Asigna un adjunto como imagen destacada de una entrada, o elimina la que ya tiene.
Argumentos
| Argumento | Obligatorio | Significado |
|---|---|---|
post_id |
Sí | La entrada o página que se va a modificar |
media_id |
No | El adjunto que se va a asignar; omítelo para eliminar |
dry_run |
No | Informa sin escribir |
Omitir media_id elimina la imagen destacada
Ese es todo el mecanismo de eliminación: no hay una herramienta independiente ni un indicador explícito de «eliminar». Llamar solo con post_id elimina la imagen destacada de la entrada y devuelve un thumbnail_id de 0.
Conviene dejarlo claro porque es fácil activarlo por accidente. Un cliente que construye los argumentos y omite media_id —porque una consulta no devolvió nada o una variable estaba vacía— elimina la imagen en lugar de fallar.
Si vas a asignar, confirma que el thumbnail_id de la respuesta es el ID que esperabas y no 0.
Permisos y validación del destino
Se requieren la puerta de escritura de contenido y el permiso para editar la entrada de destino. El destino debe ser un tipo de contenido compatible. Un media_id distinto de cero debe identificar un adjunto de imagen legible en este sitio; una entrada normal, un adjunto que no es una imagen o un ID negativo se rechazan antes de la aprobación. La disponibilidad del archivo y el recorte renderizado aún necesitan verificación visual.
El tipo de entrada debe admitir miniaturas
Si el tipo de entrada de destino no declara compatibilidad con thumbnail, la asignación se guarda pero nada la muestra.
Compruébalo con wp_get_post_types, cuya lista supports responde a esto directamente.
Qué devuelve
El post_id y el thumbnail_id resultante. Leerlo de nuevo es la confirmación: 0 significa que la imagen fue eliminada.
La vista previa informa de la miniatura actual y del reemplazo solicitado sin escribir, lo cual es una forma barata de confirmar que los argumentos se construyeron como se pretendía.
El tamaño sigue importando
Asignar una imagen no la redimensiona. WordPress renderiza la imagen destacada al tamaño que pida el tema, generado a partir del original, de modo que un original pequeño produce una imagen principal suave o de tamaño insuficiente.
Las herramientas no informan de dimensiones, así que abre el url del adjunto y míralo antes de asignarlo a un espacio destacado. Consulta wp_get_media_item.
Después de asignar
- Abre la entrada en el front end y comprueba que la imagen aparece con el recorte correcto.
- Revisa cualquier página de archivo o listado, que a menudo usa un tamaño generado distinto.
- Purga la caché.
Cómo usarlo bien
Establece el medio 1180 como imagen destacada de la entrada 412 y después vuelve a leer la entrada.
Para eliminar:
Elimina la imagen destacada de la entrada 412.
Para varias entradas, indica los pares explícitamente en lugar de describir una regla:
Establece 1180 en la entrada 412 y 1181 en la entrada 415. Nada más.
Problemas frecuentes
| Síntoma | Causa |
|---|---|
| Se rechaza la escritura | Puerta de escritura de contenido cerrada |
pom_ai_mcp_forbidden |
No hay edit_post en la entrada de destino |
| Se eliminó la imagen destacada | media_id se omitió o estaba vacío |
| No se muestra nada | El tipo de entrada no admite thumbnail, o el tema no lo muestra |
| Una imagen rota | El registro del adjunto existe pero el archivo no |
| La imagen se ve suave | El original es más pequeño que el tamaño de visualización |
Relacionado
wp_get_media_item— confirma primero el adjuntowp_upload_media- Subir y asignar una imagen destacada