Do zero a um arquivo processado com a CLI da Transloadit
Processe um arquivo pelo terminal sem copiar segredos da API. Execute
auth login, aprove a solicitação no navegador (ou cadastre-se ali primeiro)
e seu próximo comando processará um arquivo.
A mesma CLI pode transformar uma frase em Assembly Instructions, validar e corrigir Instructions que você escreveu à mão e executá-las em uma pasta inteira. A seguir, mostramos cada uma dessas operações usando nossa API de produção, além da solução do SDK para Node para uploads interrompidos no meio.
Fazer login pelo navegador
Os exemplos abaixo usam @transloadit/node 5.1.0. Os comandos da CLI são executados via
npx, então você só precisa do Node.js 20.10 ou mais recente:
$ npx -y @transloadit/node auth login
Enter code VKVQ-C5H6 at https://transloadit.com/c/cli-auth?code=VKVQ-C5H6
A CLI abre essa página para você. Com --no-browser, ela apenas imprime o link,
o que ajuda ao usar SSH. Faça login ou cadastre-se se ainda não tiver uma conta, confira se o código
na página corresponde ao do terminal e aprove a solicitação. A CLI então imprime
Logged in to workspace … e tudo está pronto. Os códigos expiram após 15 minutos.
A aprovação cria uma nova Auth Key no seu
Workspace, identificada com o nome de host da sua máquina
e a data, para que você possa encontrá-la depois em Credenciais no Console. A CLI a armazena em
~/.transloadit/credentials, um arquivo que apenas seu usuário pode ler. Essa única chave pode criar
Assemblies, ler
Templates e assinar URLs do
Smart CDN. auth status mostra em qual Workspace você
está conectado, e auth logout exclui o arquivo e revoga a chave. Já tem uma chave?
auth login --stdin a importa de uma entrada no estilo dotenv.
O login no seu laptop não se destina à automação:
- Em CI, continue passando
TRANSLOADIT_KEYeTRANSLOADIT_SECRETdo seu gerenciador de segredos, usando uma chave com escopo restrito àquela tarefa. As variáveis de ambiente têm precedência sobre o login salvo. - Nos servidores da aplicação, use uma chave de implantação separada, para que sair da conta no laptop nunca interrompa a produção.
Transformar uma frase em um arquivo processado
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 sua frase em Assembly Instructions, valida o resultado com as
verificações descritas abaixo, faz até três tentativas se o lint encontrar erros e então executa as
Instructions no seu arquivo. Nosso JPEG de 9,3 MB voltou como um WebP de 62 KB em cerca de 20 segundos,
incluindo a etapa de compilação.
A compilação é, por si só, uma Assembly que usa o 🤖 /ai/chat (English) como Robot, então ela aparece no seu uso como qualquer outra Assembly. Quando precisar executar a mesma tarefa novamente, compile uma vez e guarde o resultado:
npx -y @transloadit/node assembly-instructions compile "resize to 400px wide and convert to WebP" > webp-thumbs.json
As Instructions geradas podem ser assim:
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"webp": {
"robot": "/image/resize",
"use": ":original",
"width": 400,
"resize_strategy": "fit",
"zoom": true,
"format": "webp",
"background": "none",
"result": true
}
}
}
Essas Instructions usam o 🤖 /image/resize
como Robot em um único Step
de redimensionamento que você pode revisar, versionar e reutilizar sem chamar um modelo novamente.
Um modelo pode retornar
Instructions diferentes para a mesma frase, então leia o que você guardar. Para tarefas comuns com
opções fixas e sem uso de IA, os comandos de intenção (English), como
image resize, continuam sendo o caminho mais rápido.
Passe o arquivo salvo diretamente para assemblies create para reutilizá-lo:
npx -y @transloadit/node assemblies create --steps webp-thumbs.json -i chameleon.jpg -o saved-thumb.webp
Detectar erros antes da produção
assemblies lint verifica as Instructions na sua máquina com o mesmo linter usado pelo
editor do Console e pelo servidor MCP. Ele não precisa de credenciais, então pode ser executado em CI
e em hooks de pré-commit sem segredos. Aqui está um arquivo com três erros comuns: um Step sem
use, uma chave JSON duplicada e um erro de digitação no nome de um 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 …
Adicione --fix, e o linter corrigirá o que puder com segurança e reescreverá
o próprio arquivo:
$ 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 …
O Step thumb agora fica assim:
{
"steps": {
// …
"thumb": {
"robot": "/image/resize",
"width": 800,
"height": 300,
"use": ":original"
},
// …
},
}
--fix manteve o último width, o valor que um parser
JSON mantém, direcionou o Step para :original e reformatou o arquivo. O erro de
digitação permanece, porque o linter não pode saber qual Step você quis usar. Altere
thumbs para thumb, e o arquivo passará na validação,
mesmo com avisos tratados como falhas:
$ npx -y @transloadit/node assemblies lint --steps steps.json --fatal warning
No issues found
O lint termina com um código de saída diferente de zero quando há erros e, com
--fatal warning, também quando há avisos. Assim, o mesmo comando em uma tarefa de CI
impede que Instructions com erros sejam entregues. --steps - lê da entrada padrão,
--json imprime os problemas em um formato legível por máquina, e
--template valida seus Steps mesclados com um Template salvo da mesma forma que a
API os mescla. Essa última opção exige credenciais.
Processar uma pasta inteira
assemblies create executa Instructions em arquivos e diretórios e baixa os resultados.
--steps aceita tanto o arquivo abaixo, que contém apenas Steps, quanto a forma
{ "steps": … } acima. Com alguns JPEGs em photos/, isso cria
miniaturas com 400 pixels de largura:
{
":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 recebe sua própria Assembly, com cinco processadas por vez por padrão
(--concurrency altera isso), e cada resultado é salvo em
thumbs/ com o nome do arquivo da foto. Execute o comando novamente, e ele
ignorará toda foto cuja miniatura seja mais recente que o original. Assim, apenas arquivos novos ou
alterados custam uma Assembly. --reprocess-stale processa tudo novamente. Adicione
--recursive para incluir subpastas, ou --watch para manter o
comando em execução e processar os arquivos à medida que forem alterados.
Retomar uploads após uma falha
Para uploads grandes feitos pelos seus próprios scripts Node.js, o
resumeAssemblyUploads() do SDK continua um upload interrompido em vez de começar de novo.
Instale @transloadit/node@5.1.0 no seu projeto e defina TRANSLOADIT_KEY e
TRANSLOADIT_SECRET para uma Auth Key da aplicação configurada para SHA-384, o padrão do
SDK. Esses scripts leem as credenciais das variáveis de ambiente. Baixe a foto de exemplo:
curl -fsSLo prinsengracht.jpg https://demos.transloadit.com/inputs/prinsengracht.jpg
Salve a Assembly URL assim que o upload começar:
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
Se esse processo terminar inesperadamente, um segundo script enviará os bytes restantes para a mesma 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)
Interrompemos o upload de uma foto de 14 MB com o sinal enviado por Ctrl+C, confirmamos o upload parcial no status da Assembly e o retomamos:
$ node upload.mjs
^C
$ node resume.mjs
1048576 bytes uploaded
1114112 bytes uploaded
…
14160569 bytes uploaded
ASSEMBLY_COMPLETED
O upload continuou a partir de 1.048.576 bytes em vez de zero. O SDK identifica os uploads pelo nome do campo, nome do arquivo e tamanho, então passe os mesmos caminhos de antes. Apenas entradas com caminhos de arquivos permitem retomada; fluxos e buffers não permitem. A API atualiza o status de uploads parciais de forma assíncrona. Se você retomar antes de o upload parcial aparecer no status da Assembly, o SDK fará o upload desse arquivo novamente desde o início, ainda na mesma Assembly.
Conhecer os limites
- A chave do login pelo navegador pode executar Assemblies e ler Templates, mas não pode criar nem
alterar Templates. Os comandos
templatesque fazem gravações precisam de uma chave separada com essa permissão. runecompileusam um modelo de IA, e duas execuções da mesma frase podem produzir Instructions diferentes.- No plano gratuito Community, os resultados de imagens recebem marcas-d’água, e os resultados de áudio e vídeo são cortados. Nossa FAQ explica por quê.
Experimentar
npx -y @transloadit/node auth login
Ainda não tem uma conta? Cadastre-se na página que abrir ou crie uma conta primeiro. A visão geral da CLI apresenta a ferramenta, e o README do SDK documenta os comandos e a API para retomar uploads. Se preferir que um agente opere a Transloadit, veja nosso servidor MCP (English) e nossas habilidades para agentes. Conte para nós o que está faltando no rastreador de issues do node-sdk.