Intents del SDK de Node: comandos de CLI para tareas comunes
El SDK de Node ahora incluye comandos Intent: comandos de CLI de alto nivel para tareas comunes de Transloadit. Estos comandos facilitan mucho el uso de Transloadit para trabajos puntuales, sin tener que escribir primero manualmente el JSON de Assembly Instructions.
Los siguientes ejemplos usan el nombre actual del paquete @transloadit/node.
El binario de la CLI sigue llamándose transloadit; el antiguo paquete de npm
transloadit se mantiene como alias de compatibilidad. Consulta la
documentación del SDK de Node para obtener información sobre la instalación y la autenticación.
La idea de dotar a nuestro SDK de Node de algunas funciones prácticas para la línea de comandos surgió de un problema concreto que teníamos. Cuando creamos integraciones duraderas, las Instructions en JSON y los Templates reutilizables son exactamente la abstracción adecuada. Son expresivos, estables y muy apropiados para flujos de trabajo personalizados de varios pasos. Sin embargo, para trabajos rápidos desde la línea de comandos, pueden sentirse como una carga adicional.
En mi trabajo cotidiano como parte del equipo cofundador, me di cuenta de que no recurría a Transloadit cuando quería convertir rápidamente un archivo Markdown a PDF, aunque contamos con un servicio muy competente precisamente para eso.
Así que empecé a preguntarme qué debería poder hacer una integración para que yo recurriera a ella. Anoté los comandos que quería usar y, a partir de ahí, fui retrocediendo hasta llegar a una implementación. Lo llamamos Intents.
Intents está disponible en la CLI de nuestro SDK de Node como una capa adicional de abstracción de alto nivel sobre nuestros componentes fundamentales, como Robots, Assemblies y Builtin Templates.
Mientras que antes la CLI te daba acceso directo a estos componentes fundamentales, la nueva capa Intents no
se organiza en torno a nuestros mecanismos internos, sino en torno a tu caso de uso puntual, con comandos fáciles de deducir como
markdown pdf, markdown docx, image remove-background, image generate y image describe.
Ejecuta trabajos puntuales desde la CLI
Si tus credenciales TRANSLOADIT_KEY y TRANSLOADIT_SECRET están disponibles en el shell, en un archivo
.env local o en ~/.transloadit/credentials, ahora puedes ejecutar:
npx -y @transloadit/node markdown pdf --input ./README.md --print-urls
Y obtener una tabla como esta, con la URL temporal real de tu resultado en la última columna:
STEP NAME URL
convert README.pdf https://example.com/README.pdf
Esto significa que puedes usar Transloadit como una herramienta de CLI práctica para trabajos rápidos, en lugar de usarlo exclusivamente como una integración de backend incorporada.
Usa comandos de alto nivel en lugar de JSON para tareas comunes
Intents abarca flujos de trabajo comunes con nombres de comandos breves y predecibles. Estos son algunos ejemplos:
npx -y @transloadit/node image remove-background --input ./photo.jpg --print-urls
npx -y @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.png
npx -y @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json
npx -y @transloadit/node markdown docx --input ./plan.md --output plan.docx
O ¿qué te parece la generación de imágenes guiada por una entrada?
npx -y @transloadit/node image generate \
--input ./person1.jpg \
--input ./person2.jpg \
--input ./background.jpg \
--prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" \
--output scene.png
Para consultar la referencia completa, revisa la referencia de comandos Intent en GitHub o la documentación del SDK de Node.
La practicidad como principio de diseño más importante
Intents procura establecer valores predeterminados útiles. En el momento de esta actualización,
image generate usa de forma predeterminada google/nano-banana-2;
puedes seleccionar explícitamente una alternativa compatible con --model.
Ejecuta npx -y @transloadit/node image generate --help para consultar las opciones del comando instalado,
en lugar de considerar este artículo un catálogo permanente de modelos.
Los modelos predeterminados pueden cambiar entre versiones. Para una integración reproducible, fija la versión del SDK en las dependencias de tu proyecto y elige un modelo de forma deliberada; luego valida sus resultados para tu caso de uso.
Para obtener una ubicación de salida predecible, especifica --output. Si lo
omites, la CLI deduce una ruta a partir del comando y sus entradas; la referencia de comandos Intent
documenta los detalles. Usa --print-urls por sí solo cuando quieras obtener URL
temporales de los resultados sin descargar los archivos localmente.
Para facilitar la lectura, en esta publicación uso la forma larga --output, pero, naturalmente, también hay alias rápidos
como -o.
Usa Intents para trabajos rápidos y JSON para flujos de trabajo personalizados
Intents no reemplaza el modelo de bajo nivel de Transloadit. Las Instructions en JSON siguen siendo la abstracción adecuada a largo plazo para pipelines de medios integrados. Te permiten crear flujos adaptados a tu caso de uso y están diseñadas para guardarse como Templates y reutilizarse muchas veces en producción mediante nuestros SDK.
Pero si eres un guerrero de la línea de comandos (o quizá tu agente lo sea) y necesitas procesar rápidamente algunos archivos multimedia, esto podría ser justo lo que buscas.
Y recuerda que, incluso si tus necesidades de CLI superan las capacidades de Intents, nuestra CLI sigue siendo compatible con
npx -y @transloadit/node assemblies create, por lo que puedes pasar a crear tus propios pipelines de medios
cuando quieras.
Pruébalo
Para el uso interactivo, empieza con npx -y @transloadit/node auth login y sigue las
instrucciones de configuración del SDK de Node. Para la automatización,
usa una Auth Key y un Auth Secret independientes, con ámbitos adecuados, proporcionados por tu gestor
de secretos como TRANSLOADIT_KEY y TRANSLOADIT_SECRET, siguiendo las
indicaciones de despliegue del SDK.
Estas credenciales de API autentican las solicitudes a Transloadit; son distintas de las
credenciales de Template que se usan para acceder a un proveedor de almacenamiento. Mantén el Auth Secret fuera
del código del navegador y del control de versiones. Luego consulta los comandos disponibles:
npx -y @transloadit/node --help
De manera opcional, si quieres ayudar a tu agente (Cursor, Codex, Claude Code, etc.) a encontrar estos Intents y darle superpoderes para el procesamiento de medios, puedes instalar nuestras Skills globalmente mediante:
npx -y skills add https://github.com/transloadit/skills -g --all --copy
Espero que esto te facilite mucho la creación y gestión de archivos multimedia. Si falta alguna función o podría ser aún más práctico, avísame en el registro de incidencias de GitHub.
