Intents do Node SDK: comandos CLI para tarefas comuns

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos · Mostrar biografia

O Node SDK agora inclui comandos Intent: comandos CLI de alto nível para tarefas comuns na Transloadit. Esses comandos facilitam muito o uso da Transloadit para tarefas pontuais, sem precisar primeiro escrever JSON de Assembly Instructions à mão.

A ideia de adicionar conveniências de linha de comando ao nosso Node SDK surgiu de um problema prático que enfrentávamos. Quando criamos integrações duradouras, as Instructions em JSON e os Templates reutilizáveis são exatamente a abstração certa. São expressivos, estáveis e adequados a fluxos de trabalho personalizados com vários Steps. Para tarefas rápidas na linha de comando, porém, podem parecer trabalho extra.

No meu dia a dia, como alguém que cofundou a empresa, percebi que não recorria à Transloadit quando queria converter rapidamente um arquivo Markdown em PDF, embora tenhamos um serviço muito capaz para fazer exatamente isso.

Então comecei a pensar no que uma integração precisaria fazer para que eu recorresse a ela. Anotei os comandos que queria usar e, a partir deles, desenvolvi uma implementação. Estamos chamando essa solução de Intents.

Os Intents ficam na CLI do nosso Node SDK, como uma camada adicional de abstração de alto nível sobre nossas primitivas, como Robots, Assemblies e Builtin Templates.

Antes, a CLI oferecia acesso direto a essas primitivas. A nova camada de Intents se organiza em torno do seu caso de uso pontual, em vez dos nossos componentes internos, com comandos fáceis de deduzir, como markdown pdf, markdown docx, image remove-background, image generate e image describe.

Executar tarefas pontuais pela CLI

Se as suas credenciais TRANSLOADIT_KEY e TRANSLOADIT_SECRET estiverem disponíveis no shell, em um .env local ou em ~/.transloadit/credentials, agora você pode executar:

npx -y @transloadit/node markdown pdf --input ./README.md --print-urls

E receber uma tabela como esta, com a URL temporária real do seu resultado na última coluna:

STEP     NAME        URL
convert  README.pdf  https://example.com/README.pdf

Isso significa que você pode usar a Transloadit como uma ferramenta prática de CLI para tarefas rápidas, além de usá-la como uma integração incorporada ao back-end.

Usar comandos de alto nível em vez de JSON para tarefas comuns

Os Intents atendem a fluxos de trabalho comuns com nomes de comandos curtos e previsíveis. Alguns exemplos:

npx -y @transloadit/node image remove-background --input ./photo.jpg --print-urls
npx -y @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.png
npx -y @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json
npx -y @transloadit/node markdown docx --input ./plan.md --output plan.docx

Ou que tal gerar imagens com base em uma entrada:

npx -y @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.png

Para consultar a referência completa, acesse a referência dos comandos Intent no GitHub⁠ ou a documentação do Node SDK.

Conveniência como o princípio de design mais importante

Os Intents procuram adotar padrões úteis. Nesta atualização, image generate usa google/nano-banana-2 por padrão; você pode selecionar explicitamente uma alternativa compatível com --model. Execute npx -y @transloadit/node image generate --help para consultar as opções do comando instalado, em vez de tratar este artigo como um catálogo permanente de modelos.

Os modelos padrão podem mudar entre versões. Para uma integração reproduzível, fixe a versão do SDK nas dependências do seu projeto e escolha um modelo de forma deliberada. Depois, valide o resultado para o seu caso de uso.

Para definir um local de saída previsível, especifique --output. Se você omitir essa opção, a CLI deduz um caminho a partir do comando e de suas entradas; a referência dos comandos Intent documenta os detalhes. Use apenas --print-urls quando quiser URLs temporárias dos resultados sem baixar os arquivos localmente.

Para facilitar a leitura, uso a forma longa --output neste post, mas naturalmente também há aliases curtos, como -o.

Usar Intents para tarefas rápidas e JSON para fluxos personalizados

Os Intents não substituem o modelo de nível mais baixo da Transloadit. As Instructions em JSON continuam sendo a abstração certa a longo prazo para pipelines integrados de mídia. Elas permitem criar fluxos sob medida para o seu caso de uso e foram concebidas para serem salvas como Templates e reutilizadas muitas vezes em produção por meio dos nossos SDKs.

Mas, se você vive na linha de comando (ou talvez seu agente viva) e precisa processar mídia rapidamente, esta pode ser a solução ideal.

E lembre-se: mesmo que suas necessidades na CLI ultrapassem o que os Intents oferecem, nossa CLI ainda suporta npx -y @transloadit/node assemblies create, permitindo que você passe a criar seus próprios pipelines de mídia quando quiser.

Experimentar

Para uso interativo, comece com npx -y @transloadit/node auth login e siga as instruções de configuração do Node SDK. Para automação, use uma Auth Key e um Auth Secret separados e com escopo adequado, fornecidos pelo seu gerenciador de segredos como TRANSLOADIT_KEY e TRANSLOADIT_SECRET, seguindo as orientações de implantação do SDK. Essas credenciais de API autenticam as requisições à Transloadit; elas não são as Credenciais de Template usadas para acessar um provedor de armazenamento. Mantenha o Auth Secret fora do código executado no navegador e do controle de versão. Depois, consulte os comandos disponíveis:

npx -y @transloadit/node --help

Se quiser ajudar seu agente (Cursor, Codex, Claude Code etc.) a encontrar esses Intents e dar a ele superpoderes de processamento de mídia, você pode, opcionalmente, instalar nossas skills globalmente com:

npx -y skills add https://github.com/transloadit/skills -g --all --copy

Espero que isso facilite muito a criação e o gerenciamento de arquivos de mídia. Por favor, me avise pelo rastreador de issues no GitHub⁠ se faltar algum recurso ou se houver como tornar a experiência ainda mais prática.