wp_update_media: actualizar los metadatos de medios
Cambia el título, el subtítulo, la descripción o el texto alternativo de un adjunto. No toca el archivo en sí.
Argumentos
| Argumento | Obligatorio | Significado |
|---|---|---|
id |
Sí | El ID del adjunto |
title |
No | El título del adjunto |
caption |
No | El subtítulo |
description |
No | La descripción |
alt |
No | El texto alternativo |
dry_run |
No | Informar sin escribir |
Solo se modifican los campos que introduces.
Permisos
Allow content writes abierto y edit_post sobre el adjunto.
Los cuatro campos hacen trabajos distintos
| Campo | Propósito | Lo ve |
|---|---|---|
alt |
El texto equivalente cuando la imagen no se ve | Los lectores de pantalla y cuando la imagen no carga |
caption |
Texto editorial mostrado junto a la imagen | Todo el mundo |
title |
Una etiqueta administrativa en la biblioteca | Los editores |
description |
Texto más largo, usado por algunos temas en las páginas de adjunto | Varía |
No pongas la misma cadena en los cuatro. Un subtítulo que repite el texto alternativo hace que un usuario de lector de pantalla oiga dos veces la misma frase.
El texto alternativo es el que importa
También es el que un asistente falla de forma más predecible, porque un buen texto alternativo describe el propósito de la imagen en su contexto y el asistente solo puede ver la imagen.
La misma fotografía necesita un texto alternativo distinto en una página de empleo, junto a un testimonio y como cabecera decorativa — donde debería estar vacío.
Un asistente al que se le pide "añadir texto alternativo" nunca producirá un texto alternativo vacío. Vacío en imágenes decorativas es una corrección que solo puede hacer una persona. Consulta Escribe texto alternativo que ayude.
No hay deshacer
Los adjuntos no tienen revisiones. Sobrescribir un texto alternativo que alguien escribió con cuidado lo reemplaza de forma permanente.
Dos consecuencias:
Lee antes de escribir, y conserva los valores antiguos:
Muéstrame el texto alternativo y el subtítulo actuales del medio 1180 y luego actualiza el texto alternativo a «…».
Selecciona imágenes a las que les falten valores, no todo. wp_get_media devuelve los metadatos actuales, de modo que un asistente puede identificar los vacíos:
Lista los medios, dime cuáles tienen el texto alternativo vacío y detente.
Luego actualiza solo esos ID.
Vista previa del adjunto actual
La vista previa incluye los metadatos actuales del adjunto y los cambios solicitados. El ID debe ser un adjunto y el actor debe poder editarlo. Si sus metadatos cambian después de la aprobación, solicita una revisión nueva antes de aplicar la edición.
Los valores se sanean como texto plano
Los cuatro campos pasan por un saneado de texto, de modo que el HTML en un subtítulo o una descripción no sobrevivirá como marcado. Escribe texto plano.
Qué devuelve
El adjunto actualizado en la forma estándar.
Hacer un lote
Las escrituras tienen un límite de 20 por minuto, de modo que una pasada de metadatos sobre una biblioteca grande va acompasada de todos modos. Usa ese ritmo:
Actualiza los cinco primeros, muéstrame los resultados y detente.
Lee cada resultado. Un lote de texto alternativo generado que nadie lee es un lote de descripciones plausibles, algunas de las cuales se equivocan en nombres de productos, números y colores — los detalles que más importan.
Problemas comunes
| Síntoma | Causa |
|---|---|
| La escritura se rechaza | Puerta de escritura de contenido cerrada |
pom_ai_mcp_forbidden |
No hay edit_post sobre el adjunto |
| El HTML del subtítulo desapareció | Los campos se sanean como texto plano |
| Se reemplazó un texto alternativo escrito con cuidado | No existen revisiones; lee antes de escribir |
| La imagen sigue mostrando el texto alternativo antiguo en la página | Caché no purgada |
Relacionado
wp_get_media_item— lee antes de escribirwp_get_media— encuentra los huecos- Generar metadatos de imagen en masa — la propia herramienta de POM AI para el mismo trabajo