Subir y asignar una imagen destacada

Dos formas de llevar una imagen a la biblioteca de medios y, después, un paso para adjuntarla. Las herramientas de subida están limitadas a propósito, así que conocer los límites evita un fallo confuso.

Las dos herramientas de subida

Herramienta Recibe
wp_upload_media_from_url Una URL pública de imagen, descargada por tu servidor
wp_upload_media Una carga útil en base64 más un nombre de archivo

Ambas son herramientas de escritura y necesitan que Allow content writes esté abierto, además de upload_files en el usuario que actúa.

Las limitaciones de las subidas por URL

wp_upload_media_from_url es la más restringida de las dos, porque hace que tu servidor vaya a buscar algo:

  • Se rechazan las direcciones privadas y reservadas. Una URL que resuelva a una IP interna se rechaza, de modo que la herramienta no puede apuntar a tu propia red.
  • No se siguen las redirecciones. La URL debe devolver la imagen directamente. Un acortador, una redirección de CDN o una de http a https fallan todas.
  • Máximo de 10 MB.
  • Solo se aceptan JPEG, PNG, GIF, WebP y AVIF.
  • La respuesta debe ser correcta — ni un 404 ni una página de error.

La regla de las redirecciones es la que más a menudo sorprende a la gente. Una URL que funciona en un navegador puede fallar aquí, porque el navegador siguió una redirección que la herramienta no seguirá.

La vía del base64

wp_upload_media recibe los datos de la imagen directamente, lo que evita todas las limitaciones de la URL. Acepta una cadena base64 simple o una carga útil data:image/…;base64,, y requiere un nombre de archivo.

Úsala cuando la imagen provenga del propio asistente, o cuando la URL de origen redirija.

Sube y luego vuelve a leer

Sube esta imagen desde URL y luego muéstrame el ID del adjunto resultante, el nombre de archivo y las dimensiones.

La respuesta te da el ID del adjunto. Todo lo que venga después hace referencia a él.

Vuelve a leerlo con wp_get_media_item y confirma que las dimensiones son las que esperabas — es más fácil detectar una imagen reducida o inesperadamente pequeña ahora que después de colocarla en una página.

Escribe tú mismo el texto alternativo

La subida no crea texto alternativo. wp_update_media establece el título, el texto alternativo, la leyenda y la descripción.

Establece el texto alternativo del medio 1180 como "Técnico inspeccionando una placa de circuitos".

El texto alternativo debe transmitir el propósito de la imagen en su contexto en lugar de describir su contenido, y las imágenes decorativas deben tener un texto alternativo vacío. Un asistente al que se le pide "añadir texto alternativo" produce una descripción de lo que cree que muestra la imagen, así que revísalo. Consulta Escribe un texto alternativo que ayude.

Asígnala

Como imagen destacada:

Establece el medio 1180 como imagen destacada de la entrada 412.

wp_set_featured_image recibe la entrada y el adjunto.

Dentro del contenido: la imagen se referencia en el contenido de la entrada o la página como cualquier otro adjunto. Para las páginas del constructor, lee primero el esquema del shortcode para que la imagen se coloque con un marcado válido — consulta Construye contenido del constructor de POM.

Comprueba que se ha renderizado

Abre la página. Confirma que la imagen aparece, con un tamaño razonable y con el recorte que esperabas. WordPress genera sus tamaños registrados a partir de la subida, de modo que un original pequeño no puede producir un renderizado grande.

Después purga la caché si el sitio usa una.

Imágenes generadas

Si el asistente generó la imagen, todo lo indicado en Revisa las imágenes generadas y editadas se aplica antes de que llegue a una página pública: artefactos, texto dentro de la imagen, personas reconocibles, marcas registradas y honestidad sobre los productos.

Ten en cuenta que la generación de imágenes propia de POM AI es una función aparte en la administración de WordPress y no está expuesta a través de MCP. Una imagen que llega a través de MCP procede del cliente, no de POM AI. Consulta Lo que POM AI MCP no expone.

Eliminar medios

wp_delete_media elimina un adjunto. A diferencia de las entradas, la eliminación de medios no es recuperable desde la papelera, y cualquier página que referencie el archivo muestra una imagen rota después.

Antes de eliminar, averigua dónde se usa. Si no puedes, no lo elimines.

Problemas comunes

Síntoma Causa
pom_ai_mcp_private_host La URL resuelve a una dirección privada o reservada
pom_ai_mcp_media_download_failed La URL redirigió o devolvió un error
pom_ai_mcp_media_too_large Más de 10 MB
pom_ai_mcp_media_mime_denied No es uno de los tipos de imagen aceptados
La subida se rechaza por completo La puerta de escritura de contenido está cerrada, o el usuario carece de upload_files
La imagen se ve mal en la página La resolución de origen, o los tamaños registrados del tema
Una imagen rota después de la eliminación El adjunto todavía estaba en uso
Crear contenido validado del constructor POM
Anterior
Organizar términos de taxonomía
Siguiente