De cero a un archivo procesado con la CLI de Transloadit

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos ·

Procesa un archivo desde tu terminal sin copiar secretos de la API. Ejecuta auth login, aprueba la solicitud en tu navegador (o regístrate allí primero) y tu siguiente comando procesa un archivo.

La misma CLI puede convertir una frase en Assembly Instructions, validar y corregir Instructions que escribiste a mano y ejecutarlas sobre una carpeta entera. A continuación, explicamos cada una de estas funciones con nuestra API de producción, además de la solución del SDK de Node para las subidas que se interrumpen a mitad.

Inicia sesión desde tu navegador

Los siguientes ejemplos usan @transloadit/node 5.1.0. Los comandos de la CLI se ejecutan mediante npx, así que solo necesitas Node.js 20.10 o posterior:

$ npx -y @transloadit/node auth login
Enter code VKVQ-C5H6 at https://transloadit.com/c/cli-auth?code=VKVQ-C5H6

La CLI abre esa página por ti. Con --no-browser, solo muestra el enlace, lo que resulta útil por SSH. Inicia sesión, o regístrate si aún no tienes una cuenta, verifica que el código de la página coincida con el de tu terminal y aprueba la solicitud. La CLI muestra entonces Logged in to workspace … y ya puedes continuar. Los códigos caducan después de 15 minutos.

Al aprobar la solicitud, se crea una nueva Auth Key en tu Workspace, etiquetada con el nombre de host de tu equipo y la fecha, para que puedas encontrarla más adelante en Credenciales en la Console. La CLI la guarda en ~/.transloadit/credentials, un archivo que solo tu usuario puede leer. Esa única clave puede crear Assemblies, leer Templates y firmar las URL de Smart CDN. auth status muestra en qué Workspace has iniciado sesión, y auth logout elimina el archivo y revoca la clave. ¿Ya tienes una clave? auth login --stdin la importa a partir de una entrada con formato dotenv.

El inicio de sesión en tu computadora portátil no está pensado para la automatización:

En CI, sigue proporcionando TRANSLOADIT_KEY y TRANSLOADIT_SECRET desde tu gestor de secretos, con una clave cuyos ámbitos estén limitados a esa tarea. Las variables de entorno tienen prioridad sobre el inicio de sesión guardado.
En los servidores de aplicaciones, usa una clave de despliegue independiente, para que cerrar sesión en tu computadora portátil nunca afecte a producción.

Convierte una frase en un archivo procesado

curl -fsSLo chameleon.jpg https://demos.transloadit.com/inputs/chameleon.jpg
npx -y @transloadit/node run "resize to 400px wide and convert to WebP" -i chameleon.jpg -o chameleon.webp

$ file chameleon.webp
chameleon.webp: RIFF (little-endian) data, WebP image, XMP metadata, EXIF metadata, ICC profile, 400x266

run compila tu frase en Assembly Instructions, valida el resultado con las comprobaciones descritas a continuación, realiza hasta tres intentos si la validación detecta errores y después ejecuta las Instructions sobre tu archivo. Nuestro JPEG de 9,3 MB se convirtió en un WebP de 62 KB en unos 20 segundos, incluida la compilación.

La compilación es en sí una Assembly que usa el Robot 🤖 /ai/chat (English), así que aparece en tu consumo como cualquier otra Assembly. Cuando necesites realizar la misma tarea de nuevo, compila una vez y guarda el resultado:

npx -y @transloadit/node assembly-instructions compile "resize to 400px wide and convert to WebP" > webp-thumbs.json

Las Instructions generadas pueden tener este aspecto:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "webp": {
      "robot": "/image/resize",
      "use": ":original",
      "width": 400,
      "resize_strategy": "fit",
      "zoom": true,
      "format": "webp",
      "background": "none",
      "result": true
    }
  }
}

Se trata de un único Step del Robot 🤖 /image/resize que puedes revisar, guardar en un commit y reutilizar sin volver a llamar a un modelo. Un modelo puede devolver Instructions diferentes para la misma frase, así que lee lo que guardes. Para tareas comunes con opciones fijas y sin IA, los comandos de intención, como image resize, siguen siendo la vía más rápida.

Pasa el archivo guardado directamente a assemblies create para reutilizarlo:

npx -y @transloadit/node assemblies create --steps webp-thumbs.json -i chameleon.jpg -o saved-thumb.webp

Detecta errores antes de llegar a producción

assemblies lint comprueba las Instructions en tu equipo con el mismo linter que usan el editor de nuestra Console y el servidor MCP. No necesita credenciales, por lo que se ejecuta en CI y en hooks de pre-commit sin secretos. Este archivo contiene tres errores comunes: un Step sin use, una clave de propiedad JSON duplicada y un error tipográfico en el nombre de un Step.

{
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "thumb": {
      "robot": "/image/resize",
      "width": 400,
      "height": 300,
      "width": 800
    },
    "optimized": { "robot": "/image/optimize", "use": "thumbs" },
    "exported": {
      "robot": "/s3/store",
      "use": [":original", "thumb", "optimized"],
      "credentials": "my-s3-credentials"
    }
  }
}

$ npx -y @transloadit/node assemblies lint --steps steps.json
[warning] missing-use (3:13) thumb The `use` parameter defines which files a _Robot_ should process. …
[warning] duplicate-key-in-step (7:6) thumb Duplicate key 'width' found
[error] undefined-step (9:54) optimized The _Step_ `optimized` attempts to use the output files from _Step_ `thumbs`, but _Step_ `thumbs` does not exist …

Añade --fix y el linter corrige lo que puede corregir de forma segura y reescribe el archivo original:

$ npx -y @transloadit/node assemblies lint --steps steps.json --fix
[error] undefined-step (13:13) optimized The _Step_ `optimized` attempts to use the output files from _Step_ `thumbs`, but _Step_ `thumbs` does not exist …

El Step thumb queda así:

{
  "steps": {
    // …
    "thumb": {
      "robot": "/image/resize",
      "width": 800,
      "height": 300,
      "use": ":original"
    },
    // …
  },
}

--fix conservó el último width, cuyo valor es el que conserva un analizador JSON, hizo que el Step apuntara a :original y reformateó el archivo. El error tipográfico permanece, porque el linter no puede saber a qué Step te referías. Cambia thumbs por thumb y el archivo pasa la validación, incluso si las advertencias se tratan como fallos:

$ npx -y @transloadit/node assemblies lint --steps steps.json --fatal warning
No issues found

La validación termina con un código distinto de cero si hay errores y, con --fatal warning, también si hay advertencias. Así, el mismo comando en una tarea de CI detiene las Instructions defectuosas antes de que lleguen a producción. --steps - lee de la entrada estándar, --json muestra los problemas en un formato legible por máquinas y --template valida tus Steps combinados con un Template guardado del mismo modo que los combina la API. Esta última opción sí necesita credenciales.

Procesa una carpeta entera

assemblies create ejecuta Instructions sobre archivos y directorios y descarga los resultados. --steps acepta tanto el archivo que solo contiene Steps de abajo como el formato { "steps": … } de arriba. Con unos cuantos JPEG en photos/, esto crea miniaturas de 400 píxeles de ancho:

{
  ":original": { "robot": "/upload/handle" },
  "thumb": { "robot": "/image/resize", "use": ":original", "width": 400 }
}

mkdir -p thumbs
npx -y @transloadit/node assemblies create --steps thumbs.json --input photos/ --output thumbs/

Cada foto tiene su propia Assembly, con cinco en paralelo de forma predeterminada (--concurrency cambia ese valor), y cada resultado se guarda en thumbs/ con el nombre de archivo de la foto. Si vuelves a ejecutar el comando, se omiten todas las fotos cuya miniatura sea más reciente que el original, de modo que solo los archivos nuevos o modificados te cuestan una Assembly. --reprocess-stale procesa todo de nuevo. Añade --recursive para incluir subcarpetas, o --watch para mantener el comando en ejecución y procesar los archivos a medida que cambian.

Reanuda las subidas después de un fallo

Para subidas grandes desde tus propios scripts de Node.js, resumeAssemblyUploads() del SDK continúa una subida interrumpida en lugar de empezar de nuevo. Instala @transloadit/node@5.1.0 en tu proyecto y establece TRANSLOADIT_KEY y TRANSLOADIT_SECRET para una Auth Key de aplicación configurada para SHA-384, el valor predeterminado del SDK. Estos scripts leen las credenciales de las variables de entorno. Descarga la foto de ejemplo:

curl -fsSLo prinsengracht.jpg https://demos.transloadit.com/inputs/prinsengracht.jpg

Guarda la URL de la Assembly en cuanto empiece la subida:

import { writeFile } from 'node:fs/promises'
import { Transloadit } from '@transloadit/node'

const client = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
})

const upload = client.createAssembly({
  params: { steps: { thumb: { robot: '/image/resize', use: ':original', width: 400 } } },
  files: { photo: './prinsengracht.jpg' },
  chunkSize: 1024 * 1024,
})
// The Assembly ID exists before the first byte is sent, so save it right away.
await writeFile('assembly.txt', `https://api2.transloadit.com/assemblies/${upload.assemblyId}`)
await upload

Si ese proceso se interrumpe, un segundo script envía los bytes que faltan a la misma Assembly:

import { readFile } from 'node:fs/promises'
import { Transloadit } from '@transloadit/node'

const client = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
})

const status = await client.resumeAssemblyUploads({
  assemblyUrl: await readFile('assembly.txt', 'utf8'),
  files: { photo: './prinsengracht.jpg' },
  chunkSize: 1024 * 1024,
  waitForCompletion: true,
  onUploadProgress: ({ uploadedBytes }) => console.log(`${uploadedBytes} bytes uploaded`),
})
console.log(status.ok)

Interrumpimos la subida de una foto de 14 MB con la señal que envía Ctrl+C, confirmamos la subida parcial en el estado de la Assembly y la reanudamos:

$ node upload.mjs
^C
$ node resume.mjs
1048576 bytes uploaded
1114112 bytes uploaded
…
14160569 bytes uploaded
ASSEMBLY_COMPLETED

La subida continuó a partir de 1.048.576 bytes en lugar de cero. El SDK identifica las subidas por el nombre del campo, el nombre del archivo y el tamaño, así que pasa las mismas rutas que antes. Solo se pueden reanudar las entradas basadas en rutas de archivo, no los streams ni los buffers. La API actualiza el estado de las subidas parciales de forma asíncrona. Si reanudas antes de que la subida parcial aparezca en el estado de la Assembly, el SDK vuelve a subir ese archivo desde el principio, dentro de la misma Assembly.

Conoce los límites

La clave del inicio de sesión desde el navegador puede ejecutar Assemblies y leer Templates, pero no puede crear ni modificar Templates. Los comandos de templates que realizan escrituras necesitan una clave independiente con ese permiso.
run y compile usan un modelo de IA, y dos ejecuciones de la misma frase pueden producir Instructions diferentes.
En el plan de suscripción gratuito Community, los resultados de imágenes llevan una marca de agua y los de audio y video se recortan. Nuestras preguntas frecuentes explican por qué.

Pruébalo

npx -y @transloadit/node auth login

¿Aún no tienes una cuenta? Regístrate en la página que se abre o crea una cuenta primero. La descripción general de la CLI presenta la herramienta, y el README del SDK documenta los comandos y la API para reanudar subidas. Si prefieres que un agente maneje Transloadit, consulta nuestro servidor MCP y nuestras Skills para agentes. Cuéntanos qué falta en el gestor de incidencias de node-sdk.