wp_upload_media: subir medios en Base64

Sube una imagen enviada directamente como una carga útil en base64. Es la más flexible de las dos herramientas de subida, porque no tiene restricciones de red.

Argumentos

Permisos

Allow content writes abierto, y la capacidad upload_files.

Ámbitos: mcp:read, mcp:write, wp:content:read, wp:content:write.

La carga útil

Acepta una cadena base64 simple, o un URI de datos del tipo data:image/png;base64,… — el prefijo se elimina automáticamente, de modo que un cliente puede enviar el que tenga.

El tamaño máximo decodificado es de 10 MB. Base64 se infla aproximadamente un tercio, por lo que una imagen de 10 MB llega como unos 13 MB de carga útil.

La extensión en filename es determinante

La validación se produce dos veces, y la primera comprobación es sobre el nombre de archivo:

1. La extensión debe ser jpg, jpeg, png, gif, webp o avif. Cualquier otra cosa se rechaza con pom_ai_mcp_media_extension_denied antes de que el archivo siquiera se examine.
2. El contenido real se inspecciona después de que los bytes se escriban en disco. Una discrepancia se rechaza con pom_ai_mcp_media_mime_denied.

Así que un PNG llamado photo.txt falla la primera comprobación, y un PDF llamado photo.png falla la segunda. Ambas cosas son deliberadas.

Dale al nombre de archivo la extensión que coincida con los datos reales.

Usa el ensayo

dry_run devuelve el nombre de archivo saneado y el recuento de bytes decodificado sin subir:

Usa un ensayo y dime el nombre de archivo y el tamaño que crearías.

Este es el ensayo más útil del grupo de medios. Decodifica la carga útil, por lo que detecta una cadena base64 truncada o mal formada como un tamaño que no parece correcto — antes de que la subida falle por un motivo más difícil de leer.

Los nombres de archivo se sanean

filename se pasa por el saneador de nombres de archivo de WordPress, de modo que los espacios y los caracteres inusuales se normalizan. El nombre almacenado puede diferir del que enviaste; la respuesta te indica lo que se creó.

WordPress también deduplica: subir photo.jpg dos veces produce photo.jpg y photo-1.jpg en lugar de una sobrescritura.

Cuándo preferir esta opción sobre la herramienta de URL

Siempre, a menos que tengas específicamente una URL pública y ningún byte:

• la imagen fue generada por el asistente;
• la URL de origen redirige, lo que wp_upload_media_from_url no seguirá;
• el origen está detrás de autenticación;
• el origen está en una red privada, lo que la herramienta de URL rechaza.

Qué devuelve

El adjunto creado con la forma estándar: id, title, url, mime_type, alt, caption, description y date.

Conserva el id. Establecer el texto alternativo, asignar una imagen destacada y colocar la imagen hacen referencia a él.

Qué no hace

• No establece el texto alternativo. Subir crea un adjunto con el texto alternativo vacío. Establécelo con wp_update_media.
• No asigna una imagen destacada. post_id adjunta la subida a una entrada en el sentido de biblioteca, lo cual no es lo mismo que convertirla en la imagen destacada. Consulta wp_set_featured_image.
• No redimensiona. WordPress genera sus tamaños registrados a partir de lo que envías, de modo que un original pequeño sigue siendo pequeño.

Cómo usarla bien

Sube esta imagen como \"workshop-interior.jpg\" y luego muéstrame el ID del adjunto y la URL.

Después, como pasos separados:

Establece el texto alternativo como \"…\".

Establécelo como la imagen destacada de la entrada 412.

Problemas comunes

Relacionado

• wp_upload_media_from_url
• wp_update_media
• Subir y asignar una imagen destacada