SDK para Node.js

Temos um kit completo de desenvolvimento de software para Node.js que facilita a comunicação com a REST API da Transloadit a partir dos seus apps Node.

Instalar

Nota: esta documentação abrange a v4 do SDK para Node (ESM, Node.js 20+). Para a documentação legada, veja v3 ou v2. Para detalhes sobre a atualização, leia o guia de migração v3 → v4.

Use @transloadit/node como nome do pacote. O nome legado do pacote npm transloadit é mantido como um alias para compatibilidade com versões anteriores.

Dentro do seu projeto, digite:

yarn add @transloadit/node

npm install --save @transloadit/node

CLI

Este pacote inclui uma CLI completa:

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

Observação

O binário da CLI ainda se chama transloadit, então os exemplos de comandos podem usar npx transloadit ....

Comandos de intenção

Para Jobs rápidos e pontuais, a CLI também inclui comandos de intenção de alto nível. Eles encapsulam fluxos de trabalho comuns da Transloadit em subcomandos intuitivos, para que você não precise começar com Assembly Instructions em JSON para cada tarefa.

Por exemplo:

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

Outros exemplos incluem:

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 agora usa google/nano-banana-2 por padrão, inclusive em execuções guiadas pela entrada.

Se você omitir --output, a CLI grava os resultados ao lado do arquivo de entrada quando há um único arquivo local e isso é possível. Caso contrário, usa o diretório de trabalho atual. Use --print-urls isoladamente quando quiser URLs temporárias dos resultados sem baixá-los localmente.

Também atualizamos o repositório público de habilidades da Transloadit para usar o mesmo fluxo de geração de imagens baseado em intenções.

Para a referência completa dos comandos, consulte a referência dos comandos de intenção e o README do pacote.

Projetos CommonJS

O SDK é exclusivamente ESM. Se seu projeto usa CommonJS, use uma importação 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

O código a seguir faz upload de uma imagem e a redimensiona para uma 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}`)
  }
}

Você encontra detalhes sobre suas Assemblies executadas aqui.

Exemplos

Para ver mais exemplos totalmente funcionais, consulte examples/.

Documentação

Consulte o GitHub para acessar a documentação completa e o guia de migração para detalhes sobre a atualização v3 → v4.