SDK de Node.js
Contamos con un kit de desarrollo de software completo para Node.js que facilita la comunicación con la REST API de Transloadit desde tus aplicaciones Node.
Instalación
El SDK actual es exclusivo de ESM y admite Node.js 20.10.0 o posterior. Los ejemplos de Storage que aparecen a continuación usan SDK/CLI 6.9.0 o posterior. Para consultar documentación de versiones anteriores, visita v3 o v2. Para conocer los detalles de actualización, lee la guía de migración.
Usa @transloadit/node como nombre del paquete. El nombre anterior del paquete npm,
transloadit, se conserva como alias para mantener la compatibilidad con versiones anteriores.
Dentro de tu proyecto, instala el SDK con npm:
npm install @transloadit/node
Si tu proyecto ya usa Yarn o pnpm, conserva su gestor de paquetes y su archivo de bloqueo:
yarn add @transloadit/node
Para pnpm, usa pnpm add @transloadit/node.
CLI
Este paquete incluye una CLI completa:
npx @transloadit/node --help
npx @transloadit/node auth login
El inicio de sesión abre el navegador para que puedas elegir un Workspace y autorizar la CLI sin copiar un secreto de API en tu shell. Para la automatización y los servidores de aplicaciones, usa Auth Keys configuradas por separado; la referencia de credenciales describe las opciones admitidas. No despliegues la clave desechable de inicio de sesión de la CLI como clave de una aplicación.
npx @transloadit/node usa la CLI del SDK instalado u ofrece descargarla si el
paquete no está presente. Los ejemplos indican el paquete explícitamente; no se requiere una
instalación global. Para una demostración independiente de Storage, usa el
inicializador upload-once con mantenimiento activo.
Comandos Intent
Para tareas puntuales y rápidas, la CLI también incluye comandos Intent de alto nivel. Estos encapsulan flujos de trabajo habituales de Transloadit en subcomandos intuitivos, para que no tengas que empezar con Assembly Instructions en JSON para cada tarea.
Si exportas una Auth Key en lugar de iniciar sesión con el navegador, usa su mismo algoritmo de
firma. El ejemplo de la CLI con clave manual y los ejemplos de JavaScript que aparecen a
continuación usan SHA-256, que aceptan las Auth Keys con la firma de Smart CDN habilitada. Si tu
clave usa otro algoritmo, como SHA-384 en claves sin firma de Smart CDN, establece el valor
correspondiente en TRANSLOADIT_SIGNATURE_ALGORITHM y signatureAlgorithm.
Por ejemplo:
export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
export TRANSLOADIT_SIGNATURE_ALGORITHM="sha256"
npx @transloadit/node markdown pdf --input ./README.md --print-urls
Otros ejemplos incluyen:
npx @transloadit/node image remove-background --input ./photo.jpg --print-urlsnpx @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.pngnpx @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.pngnpx @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json
image generate ahora usa google/nano-banana-2 de forma predeterminada, incluso en ejecuciones guiadas por la entrada.
Si omites --output, la CLI escribe junto al archivo de entrada cuando se
trata de un único archivo local y es posible hacerlo. De lo contrario, usa el directorio de
trabajo actual. Usa --print-urls por sí solo cuando quieras obtener URL
temporales de los resultados sin descargarlos localmente.
También actualizamos el repositorio público de Skills de Transloadit para usar el mismo flujo de generación de imágenes basado en Intent.
Para consultar la referencia completa de comandos, visita la referencia de comandos Intent y el README del paquete.
Storage y entrega de imágenes
Prueba Storage y Smart CDN con el ejemplo upload-once, o sigue la guía de Viewer para Next.js para mostrar imágenes adaptables en una aplicación existente.
La CLI puede almacenar originales de distintos tipos de medios, no solo imágenes:
npx @transloadit/node storage store ./photo.jpg ./clip.mp4 ./guide.pdf website/media/
Esto no publica el directorio. Usa storeAsset() para las subidas desde servidores
de aplicaciones y conserva el comprobante de activo/versión devuelto junto con su propietario.
Consulta originales de distintos tipos de medios
para conocer la verificación de bytes, la sobrescritura explícita, la recuperación del catálogo y
las descargas de originales. Las fuentes HTTP/S3 existentes también pueden usar Viewer sin
migrar a Storage.
Proyectos CommonJS
El SDK es exclusivo de ESM. Si usas CommonJS, utiliza una importación dinámica:
async function getClient() {
const { Transloadit } = await import('@transloadit/node')
return new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
// Match another Signature algorithm if your Auth Key requires one.
signatureAlgorithm: 'sha256',
})
}
Uso
El siguiente código subirá una imagen y la redimensionará para crear una miniatura:
import { ApiError, Transloadit } from '@transloadit/node'
const transloadit = new Transloadit({
authKey: 'YOUR_TRANSLOADIT_KEY',
authSecret: process.env.TRANSLOADIT_SECRET,
// Match another Signature algorithm if your Auth Key requires one.
signatureAlgorithm: 'sha256',
})
try {
const options = {
files: {
file1: '/PATH/TO/FILE.jpg',
},
params: {
steps: {
// You can have many Steps. In this case we will just resize any inputs (:original)
resize: {
use: ':original',
robot: '/image/resize',
result: true,
width: 75,
height: 75,
},
},
// OR if you already created a template, you can use it instead of "steps":
// template_id: 'YOUR_TEMPLATE_ID',
},
waitForCompletion: true, // Wait for the Assembly (job) to finish executing before returning
}
const status = await transloadit.createAssembly(options)
if (status.results.resize) {
console.log('✅ Success - Your resized image:', status.results.resize[0].ssl_url)
} else {
console.log("❌ The Assembly didn't produce any output. Make sure you used a valid image file")
process.exitCode = 1
}
} catch (err) {
console.error('❌ Unable to process Assembly:', err instanceof ApiError ? (err.code ?? 'API request failed.') : 'Check your connection and input files.')
process.exitCode = 1
if (err instanceof ApiError && err.assemblyId) {
console.error(`💡 More info: https://api2.transloadit.com/assemblies/${err.assemblyId}`)
}
}
Puedes encontrar detalles sobre tus Assemblies ejecutadas aquí.
Ejemplos
- Sube y redimensiona una imagen
- Sube una imagen y conviértela a WebP
- Rasteriza SVG a PNG
- Recorta un rostro de una imagen y descarga el resultado
- Ejemplo de reintento
- Calcula los costos totales (uso en GB)
- CRUD de Templates
- CRUD de credenciales de Template
Para ver más ejemplos totalmente funcionales, consulta
examples/.
Documentación
Consulta GitHub para ver la documentación completa y la guía de migración para conocer los detalles de actualización.