SDK de Node.js

Tenemos un kit de desarrollo de software completo para Node.js que facilita la comunicación con la REST API de Transloadit desde tus aplicaciones de Node.

Instala

Nota: Esta documentación abarca la versión v4 del SDK de Node (ESM, Node.js 20+). Para consultar la documentación de versiones anteriores, consulta v3⁠ o v2⁠. Para obtener detalles sobre la actualización, consulta la guía de migración de v3 → v4⁠.

Usa @transloadit/node como nombre del paquete. El nombre anterior del paquete npm, transloadit, se mantiene como alias para ofrecer compatibilidad con versiones anteriores.

Dentro de tu proyecto, escribe:

yarn add @transloadit/node

o

npm install --save @transloadit/node

CLI

Este paquete incluye una CLI completa:

export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
npx -y @transloadit/node --help

Comandos de intención

Para tareas puntuales rápidas, la CLI también incluye comandos de intención de alto nivel. Estos encapsulan flujos de trabajo comunes de Transloadit en subcomandos fáciles de deducir, para que no tengas que comenzar cada tarea con Assembly Instructions en JSON.

Por ejemplo:

export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
npx -y transloadit markdown pdf --input ./README.md --print-urls

Otros ejemplos incluyen:

• npx -y transloadit image remove-background --input ./photo.jpg --print-urls
• npx -y transloadit image generate --prompt "A red bicycle in a studio" --output bicycle.png
• npx -y transloadit 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
• npx -y transloadit image describe --input ./hero.jpg --for wordpress --output fields.json

image generate ahora usa google/nano-banana-2 de forma predeterminada, incluidas las ejecuciones guiadas por entradas.

Si omites --output, la CLI escribe junto a un único archivo local de entrada cuando es posible. De lo contrario, usa como alternativa el directorio de trabajo actual. Usa solo --print-urls cuando quieras obtener URL temporales de los resultados sin descargarlos localmente.

También actualizamos el repositorio público de habilidades de Transloadit⁠ para que use el mismo flujo de generación de imágenes basado en intención.

Para consultar la referencia completa de comandos, consulta la referencia de comandos de intención⁠ y el archivo README⁠ del paquete.

Proyectos CommonJS

El SDK solo admite 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,
  })
}

Uso

El siguiente código subirá una imagen y la redimensionará como miniatura:

import { ApiError, Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

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")
  }
} catch (err) {
  console.error('❌ Unable to process Assembly.', err)
  if (err instanceof ApiError && err.assemblyId) {
    console.error(`💡 More info: https://api2.transloadit.com/assemblies/${err.assemblyId}`)
  }
}

Puedes consultar aquí los detalles de tus Assemblies ejecutadas.

Ejemplos

• Sube una imagen y redimensiónala⁠
• Sube una imagen y conviértela a WebP⁠
• Rasteriza un SVG a PNG⁠
• Recorta un rostro de una imagen y descarga el resultado⁠
• Consulta el ejemplo de reintento⁠
• Calcula los costos totales (uso en GB)⁠
• CRUD de Templates⁠
• CRUD de credenciales de Template⁠

Para consultar más ejemplos completamente funcionales, revisa examples/⁠.

Documentación

Consulta GitHub⁠ para acceder a la documentación completa y la guía de migración⁠ para obtener detalles sobre la actualización de v3 → v4.