wp_get_media_item: obtener un elemento multimedia
Lee un único adjunto por su ID.
Argumentos
| Argumento | Obligatorio | Significado |
|---|---|---|
id |
Sí | El ID del adjunto |
Permisos
mcp:read y wp:content:read, con upload_files.
Qué devuelve
id, title, url, mime_type, alt, caption, description y date.
La misma estructura que devuelve un listado — esta herramienta existe para obtener un elemento por su ID y no para devolver más detalle que el listado.
El url es el campo útil
Como la respuesta no incluye dimensiones ni tamaño de archivo, el url es la forma en que realmente inspeccionas la imagen. Ábrelo.
Esto importa sobre todo después de una subida: confirmar que una imagen ha llegado no es lo mismo que confirmar que se puede usar al tamaño que necesitas. Una imagen de 400 píxeles de ancho subida para una portada a todo lo ancho es una subida correcta y un resultado equivocado.
Solo lee adjuntos
Un ID que no es un adjunto devuelve pom_ai_mcp_media_not_found, el mismo error que un ID inexistente. Pasar por error un ID de entrada produce "not found" en lugar de algo más claro.
Confirma antes de asignar o eliminar
Dos operaciones toman un ID multimedia y actúan en otro lugar, y ambas se benefician de leer primero el elemento:
Antes de establecer una imagen destacada, confirma que el adjunto es el que quieres:
Lee el medio 1180 y muéstrame su título y su URL; después establécelo como la imagen destacada de la entrada 412.
Antes de eliminar, confirma qué estás eliminando — la eliminación de medios no es recuperable desde la papelera como ocurre con una entrada. Consulta wp_delete_media.
Volver a leer después de una actualización
wp_update_media devuelve el registro actualizado, pero merece la pena leerlo de forma independiente después, cuando varios campos han cambiado, porque muestra el resultado guardado en lugar de lo que se solicitó.
Actualiza el texto alternativo y después vuelve a leer el medio 1180.
El texto alternativo es el campo que hay que mirar
El campo alt es donde vive la accesibilidad, y está vacío mucho más a menudo de lo que la gente espera — WordPress no lo exige, y las imágenes subidas en bloque rara vez lo tienen.
Un alt vacío en una imagen decorativa es correcto. Un alt vacío en una informativa es una carencia real de accesibilidad. La herramienta no puede decirte cuál es cuál; consulta Escribe un texto alternativo que ayude.
Cómo usarla bien
Lee el medio 1180 y muéstrame todos los campos.
Muéstrame el texto alternativo y el pie de foto actuales del medio 1180 antes de cambiarlos.
Ese segundo patrón te da los valores antiguos, que son tu único deshacer para un cambio de metadatos — los adjuntos no tienen revisiones.
Problemas comunes
| Síntoma | Causa |
|---|---|
pom_ai_mcp_media_not_found |
ID incorrecto, o el ID no es un adjunto |
pom_ai_mcp_forbidden |
El usuario que actúa carece de upload_files |
| No hay dimensiones en la respuesta | No forman parte de la estructura; abre el url |
| La URL da 404 | El archivo no está en el disco aunque el registro exista |
Ese último caso conviene conocerlo: WordPress puede conservar un registro de adjunto cuyo archivo se ha eliminado del directorio de subidas. El registro se lee bien y la imagen está rota en todos los lugares donde aparece.