wp_upload_media_from_url: subir contenido multimedia desde una URL

Descarga una imagen pública y la añade a la biblioteca de medios. Tu servidor hace la petición, y por eso esta herramienta está más restringida que cualquier otra del servidor.

Argumentos

Permisos

Allow content writes abierto, y upload_files.

Las cuatro vallas

Como esta herramienta hace que tu servidor obtenga una URL que eligió un asistente, está restringida en cuatro puntos.

1. URL. Solo http y https, puertos 80 o 443, y como máximo 2.048 caracteres. Se rechazan las credenciales incrustadas y los fragmentos. Las URL no válidas devuelven pom_ai_mcp_invalid_url.

2. Resolución del host. Las direcciones IPv4 del nombre de host se resuelven antes de la petición, y se comprueba cada dirección devuelta. Si alguna es privada o reservada, la petición se rechaza con pom_ai_mcp_private_host.

Esa es la importante. Significa que la herramienta no puede apuntar a localhost, a un servicio interno, a un endpoint de metadatos en la nube, ni a un nombre de host público que resuelva a una dirección privada. Un host que no se puede resolver en absoluto es pom_ai_mcp_invalid_host.

La dirección validada se fija para la petición usando el transporte cURL de WordPress. Los servidores sin ese transporte deben usar wp_upload_media con una carga útil de imagen ráster compatible.

3. Sin redirecciones. La URL debe devolver la imagen directamente. Cualquier redirección hace que la respuesta no sea 2xx desde el punto de vista de la herramienta, y falla con pom_ai_mcp_media_download_failed.

4. Tamaño y tipo. La descarga está limitada a 10 MB, y el resultado pasa por la misma doble validación que una subida en base64: primero la extensión del nombre de archivo y después el contenido real.

La regla de las redirecciones afecta a todo el mundo

Una URL que funciona perfectamente en un navegador puede fallar aquí, porque el navegador siguió una redirección que esta herramienta no seguirá.

Casos habituales:

• acortadores de enlaces;
• un CDN o servicio de imágenes que redirige a una URL firmada;
• http que redirige a https;
• una plataforma de alojamiento que redirige a un dominio regional;
• una redirección por barra final o por host canónico.

Cuando una URL falla y parece correcta, casi siempre es por esto. La solución es resolver tú mismo la redirección y pasar la URL final, u obtener los bytes y usar wp_upload_media en su lugar.

El nombre de archivo proviene de la ruta de la URL

El nombre de archivo almacenado se deriva del último segmento de la ruta de la URL, recurriendo a remote-image.jpg cuando no hay ninguno.

Eso tiene una consecuencia: una URL que termina en algo sin una extensión de imagen reconocida falla la comprobación de extensión, incluso cuando la respuesta es un JPEG perfectamente válido. Las URL de entrega de imágenes con parámetros de cadena de consulta y sin extensión de archivo son el ejemplo habitual.

De nuevo, la herramienta de base64 es la respuesta: te permite nombrar el archivo tú mismo.

Usa la prueba en seco

dry_run devuelve la URL que obtendría, sin obtenerla:

Haz una prueba en seco y muéstrame la URL que descargarías.

Su valor es confirmar que el asistente resolvió la URL que querías, antes de que tu servidor haga una petición saliente en su nombre.

Qué devuelve

El adjunto creado en la forma estándar, incluido el nuevo id.

Cuándo usar esto en lugar de base64

Solo cuando realmente tienes una URL pública, directa y sin redirecciones, y no los bytes. En la práctica es más limitado de lo que parece, y wp_upload_media es la opción predeterminada más fiable.

Cómo usarla bien

Haz una prueba en seco para esta URL, luego súbela y muéstrame el ID del adjunto.

Después establece el texto alternativo como un paso aparte: al subir nunca se establece.

Problemas habituales

Relacionado

• wp_upload_media: la ruta más flexible
• wp_update_media
• Qué no expone POM AI MCP