Agentes de IA
Agentes de programação com IA, como Claude Code, OpenAI Codex e Cursor, podem se conectar à Transloadit e usar 96 Robots atuais para fazer upload, codificar e transformar arquivos. Os agentes podem combinar o servidor MCP, para acesso a ferramentas em tempo de execução, Agent Skills reutilizáveis, para fluxos de trabalho direcionados por humanos, e o llms.txt, para contexto de documentação. A CLI oferece um caminho de automação separado para humanos e CI.
Comece pelo seu projeto
Cole este prompt no seu agente de programação a partir da raiz do projeto. Ele faz o agente inspecionar o seu stack antes de escolher um SDK, o MCP ou skills, e mantém a primeira alteração fácil de revisar:
Set up the smallest safe Transloadit integration for this repository.
1. Inspect the project’s language, runtime, package manager, existing upload/media code, tests, and agent configuration before changing files.
2. Choose the narrowest integration that fits: an official SDK for application code, MCP for agent-executed runtime tools, the CLI (npx -y @transloadit/node) for scripts and CI jobs, and Agent Skills for repeatable workflow guidance. Reuse an existing integration when present.
3. Before editing, summarize what you found, which path you chose, and the files and commands you expect to change. Use the project’s existing package manager.
4. For interactive hosted MCP, add the hosted URL https://api2.transloadit.com/mcp to the client configuration without any token or key, and have the user approve browser OAuth. For CI or headless hosted MCP, mint an mcp-audience Bearer token at run time in a trusted environment, mint a new one when it expires, and supply it through secret storage or an environment variable.
5. Use TRANSLOADIT_KEY and TRANSLOADIT_SECRET only in a trusted server, CLI, CI, or self-hosted MCP process. When signing with an Auth Key, match its signature algorithm: for the Node CLI or self-hosted MCP, set TRANSLOADIT_SIGNATURE_ALGORITHM; in Node SDK code, pass the signatureAlgorithm option. Console keys with Smart CDN signing on (the default) use sha256; the Console’s snippet for the key shows the value.
6. Never expose TRANSLOADIT_SECRET to browser, mobile, or other client code. Give client code a public Auth Key and a Template ID; for production, generate the params and signature on a trusted backend with Signature Authentication. Use unsigned client params only with test credentials.
7. Never hardcode, print, commit, or overwrite credentials, including minted Bearer tokens. Keep secrets out of committed MCP configuration. If required credentials are unavailable, scaffold placeholders and stop before account operations.
8. Create one minimal, typed workflow and validate its Assembly Instructions. Prefer an existing small media fixture. Without an account, validate inline instructions locally with npx -y @transloadit/node assemblies lint --steps <file>. Linting against a Template ID needs credentials. Do not create an account, change a plan, or modify production Templates.
9. Run the repository’s checks. If authenticated Transloadit access (an approved hosted MCP connection or credentials in a trusted process) and a suitable fixture are available and the user has authorized a live test, run one Assembly, wait for completion, and report its Assembly ID, status, and result URL. Otherwise, report the exact command or MCP tool call the maintainer can run. Credentials or an approved connection alone do not authorize a live run.
10. Summarize every changed file, verification result, and any remaining manual step.
O resultado esperado é uma pequena alteração no repositório, não apenas um exemplo de código gerado. Revise o limite de credenciais proposto pelo agente antes de permitir uma Assembly real.
O que o agente deve escolher
| Sinal do projeto | Ponto de partida |
|---|---|
| Aplicação em Node.js, Python, Ruby, PHP, Go, Java, Android ou iOS | O SDK oficial correspondente |
| O agente precisa validar instruções com lint, consultar a documentação ou executar Assemblies | Servidor MCP |
| Scripts de build, tarefas de CI, pipelines de shell ou lint sem conta | CLI |
| A equipe quer um fluxo de trabalho reutilizável e versionado | Agent Skills |
| Ainda não é necessária nenhuma integração em tempo de execução | llms.txt e páginas de documentação em Markdown |
Servidor MCP
O Model Context Protocol (MCP) dá aos agentes acesso direto, em tempo de execução, às ferramentas da Transloadit.

Há três formas de se conectar. Escolha a primeira que se adequar ao seu cliente:
| Cliente | Conectar com | Credenciais |
|---|---|---|
| Cliente de agente interativo, como Claude, ChatGPT, Codex ou Cursor | URL hospedada | Aprove o OAuth no seu navegador |
| Tarefa de CI ou runtime de agente sem interface | URL hospedada com um token Bearer | Token gerado a partir de uma Auth Key |
| Agente que deve executar o servidor por conta própria | Hospedagem própria via stdio | Nenhuma para documentação e lint; Auth Key para Assemblies |
Conectar por URL
Adicione a URL do MCP hospedado ao seu cliente MCP:
https://api2.transloadit.com/mcp
Aprove o acesso OAuth no seu navegador e escolha o Workspace que o cliente pode usar. Não há servidor local para instalar nem Auth Key ou Secret para copiar. A aprovação cria uma Auth Key dedicada para o aplicativo, limitada às permissões exibidas; revogue o acesso em Aplicativos conectados.
O servidor hospedado pede que você faça login antes que qualquer ferramenta seja executada, incluindo a documentação de Robots e o lint. Para usá-las sem uma conta, execute o servidor com hospedagem própria.
CI e clientes sem interface
Quando ninguém puder aprovar o acesso em um navegador, envie ao endpoint hospedado um token com a
audiência mcp como Authorization: Bearer <token>. Gere-o em um ambiente
confiável que tenha uma Auth Key e o respectivo Secret (TRANSLOADIT_KEY e
TRANSLOADIT_SECRET para a CLI):
npx -y @transloadit/node auth token --aud mcp
O comando imprime JSON. Capture apenas o valor access_token e repasse-o ao
runtime do agente por meio de um armazenamento de segredos ou de uma variável de ambiente; não exiba
a resposta em logs nem na transcrição do agente.
- Expiração: os tokens expiram após o intervalo
expires_inretornado (uma semana por padrão para MCP). Gere um por tarefa ou sessão e gere um novo se o trabalho durar mais que esse intervalo. - Escopo: use
--scopepara restringir o acesso; caso contrário, o token herda os escopos da Auth Key. - Revogação: exclua a Auth Key a partir da qual um token foi gerado para cortar o acesso antes que ele expire. Use uma Auth Key dedicada para CI.
Veja CI e clientes sem interface para exemplos de configuração de clientes.
Hospedagem própria via stdio
Configure o servidor como um comando stdio no seu cliente MCP; a maioria dos clientes o inicia para você. A documentação de Robots e o lint funcionam sem uma conta:
npx -y @transloadit/mcp-server stdio
Para operações de conta, como criar Assemblies, forneça TRANSLOADIT_KEY e
TRANSLOADIT_SECRET pelo ambiente do processo do servidor e defina
TRANSLOADIT_SIGNATURE_ALGORITHM de acordo com a Auth Key. As chaves criadas no Console com a
assinatura do Smart CDN ativada (o padrão) usam sha256, enquanto o servidor
usa sha384 por padrão; o snippet do Console para a chave mostra qual valor
definir. Veja a configuração do algoritmo de assinatura.
O processo stdio mantém essas credenciais na máquina do agente; por isso, use uma Auth Key dedicada apenas com os escopos de que ela precisa e mantenha as credenciais fora dos arquivos de configuração do MCP versionados no repositório.
Para exemplos de configuração de clientes (Claude, Cursor, VS Code/Copilot), detalhes de autenticação, documentação das ferramentas, limites e diferenças de comportamento entre a versão hospedada e a de hospedagem própria, veja a documentação do servidor MCP.
Caminhos de automação
As ferramentas para agentes da Transloadit combinam ferramentas de execução com orientação de fluxos de trabalho e contexto de documentação. A CLI e o MCP executam fluxos de trabalho; as Agent Skills e o llms.txt ajudam os agentes a usar essas ferramentas:
- CLI: use
@transloadit/nodequando uma pessoa ou uma tarefa de CI precisar de um comando repetível para criar uma Assembly, aguardar a conclusão e coletar os resultados. - MCP: exponha as ferramentas da Transloadit a agentes incorporados ou hospedados. O agente pode
consultar a documentação dos Robots, validar Assembly Instructions com lint, criar Assemblies e
acompanhar as atualizações de status. Para arquivos passados diretamente para
transloadit_create_assembly, use URLs públicas, arquivos inline pequenos ou anexos que o cliente repassa. Fazer upload de arquivos locais ou do sandbox pelo comando de upload retornado exige um shell; veja as entradas suportadas. - Agent Skills: mantenha no controle de versão playbooks de fluxos de trabalho de mídia específicos da sua equipe, para agentes que já têm ferramentas úteis, como acesso ao terminal, MCP, a CLI ou SDKs. As skills dizem ao agente quais Templates, etapas de verificação e alternativas usar, mas não concedem novos recursos por si sós.
- llms.txt: forneça a qualquer LLM um mapa atualizado dos produtos, soluções, integrações, recursos para desenvolvedores e conteúdos de aprendizado da Transloadit antes que ele proponha uma Assembly.
Use o MCP hospedado com OAuth no navegador quando uma pessoa conectar um cliente de agente
interativo. Para automação sem supervisão, mantenha as credenciais em um ambiente confiável: envie
um token Bearer com a audiência mcp ao MCP hospedado ou forneça uma Auth
Key e um Secret ao stdio com hospedagem própria, à CLI ou ao seu próprio backend.
Agent Skills
As Agent Skills são arquivos Markdown
(SKILL.md) que ensinam os agentes a realizar tarefas passo a passo.

Na prática, um servidor MCP é uma interface de API que um agente pode chamar em tempo de execução (por meio de um processo MCP local ou hospedado), enquanto as skills são playbooks versionados que dizem ao agente o que fazer, em que ordem e como verificar o resultado. As skills não adicionam novo acesso a ferramentas por si sós. Elas codificam como você quer que o agente use, de forma consistente, as ferramentas disponíveis no seu ambiente (MCP, CLI, SDKs).
- Use o MCP para execução incorporada e repetível (criação de Assemblies, polling, resultados).
- Use skills como playbooks reutilizáveis e direcionados por humanos para tarefas como configuração, scaffolding, Templates e migrações.
Os dois também se complementam. Uma skill pode padronizar um fluxo de trabalho e, em seguida, instruir o agente a usar o MCP (ou a CLI local como alternativa) na execução propriamente dita.
Instalação com a CLI de Skills
npx skills add transloadit/skills
Isso instala todas as 19 skills da Transloadit no seu projeto:
- docs-transloadit-robots
Consulta offline de Robots da Transloadit e da documentação/exemplos de seus parâmetros via a CLI
transloadit. Use para redigir ou validar o JSON destepssem adivinhar nomes/parâmetros de Robots. - integrate-asset-delivery-with-transloadit-smartcdn-in-nextjs
Adicione assinatura de URLs do Smart CDN da Transloadit do lado do servidor, para um recurso explicitamente configurado, a um projeto Next.js com App Router.
- integrate-uppy-transloadit-s3-uploading-to-nextjs
Adicione o Uppy Dashboard + uploads da Transloadit a um app Next.js (App Router), com geração de assinatura do lado do servidor e exportação opcional via /s3/store.
- transform-build-mosaic-collage-with-transloadit
Colagem pontual de fotos em mosaico justificado (N imagens locais -> uma única imagem) usando a CLI oficial
@transloadit/node. Usa o efeitomosaicdo Robot/image/mergepara criar um layout em blocos justificado com fotos com recorte central e baixa o resultado para um caminho de saída explícito via--output. - transform-build-polaroid-collage-with-transloadit
Colagem pontual de fotos Polaroid empilhadas (N imagens locais -> uma única imagem) usando a CLI oficial
@transloadit/node. Usa o efeitopolaroid-stackdo Robot/image/mergee baixa o resultado para um caminho de saída explícito via--output. - transform-caption-video-with-transloadit
Adicione legendas simples gravadas na imagem a um vídeo local e baixe o vídeo legendado e as marcações de legenda em SRT usando o Builtin caption-video e a CLI oficial da Transloadit.
- transform-capture-webpage-with-transloadit
Capture uma página web pública ou um HTML local como imagem ou PDF usando o Builtin capture-webpage e a CLI oficial da Transloadit.
- transform-convert-markdown-to-pdf-with-transloadit
Converta um documento local do Office ou um arquivo local de HTML, Markdown ou texto em PDF usando o Builtin convert-to-pdf e a CLI oficial da Transloadit. Inclui o fluxo de trabalho existente de conversão de Markdown em PDF.
- transform-describe-image-with-transloadit
Descrição pontual de imagem usando a CLI oficial
@transloadit/node. Useimage describe --fields labelspara rótulos de objetos, ouimage describe --for wordpresspara um JSON estruturado com texto alternativo, título, legenda e descrição. - transform-encode-hls-video-with-transloadit
Codificação HLS pontual (vídeo local -> versões HLS + playlist) usando a Transloadit via a CLI
transloadit. Prefira Builtin Templates (builtin/encode-hls-video@latest) e baixe as saídas localmente via-o. - transform-encode-video-with-transloadit
Codifique um vídeo local em MP4 ou WebM para reprodução na web usando o Builtin encode-video e a CLI oficial da Transloadit.
- transform-extract-text-with-transloadit
Extraia texto legível ou JSON de PDFs, digitalizações, fotos e documentos do Office locais usando o Builtin extract-text e a CLI oficial da Transloadit.
- transform-generate-image-with-transloadit
Geração de imagem pontual (prompt -> arquivo de imagem) usando a Transloadit via a CLI
transloadit. Prefiraimage generatepara geração somente a partir de texto e para geração guiada por uma entrada, e use--outputquando precisar de um caminho determinístico. - transform-make-video-covers-with-transloadit
Crie imagens de capa a partir de um vídeo local, usando quadros em intervalos regulares, posições temporais exatas ou seleção inteligente por meio do Builtin video-covers e da CLI oficial da Transloadit.
- transform-prepare-image-with-transloadit
Prepare imagens locais para um site com correção de orientação, redimensionamento, compressão e conversão de formato usando o Builtin prepare-image e a CLI oficial da Transloadit.
- transform-remove-background-with-transloadit
Remova o fundo de uma foto local e baixe um PNG transparente usando o Builtin remove-background e a CLI oficial da Transloadit.
- transform-transcribe-audio-with-transloadit
Transcreva áudio ou vídeo local em texto, JSON com marcações de tempo, SRT ou WebVTT usando o Builtin transcribe e a CLI oficial da Transloadit.
- transform-upscale-image-with-transloadit
Ampliação pontual de imagem com IA (imagem local -> imagem ampliada) usando a Transloadit via a CLI
transloadit. Prefira a intençãoimage upscalee use--outputpara um caminho determinístico. - transloadit
Skill principal de entrada da Transloadit. Direcione para a skill
integrate-*,transform-*oudocs-*correta e prefira executar vianpx -y @transloadit/node ...(CLI) para um comportamento determinístico.
Descoberta automática
O catálogo de skills também pode ser descoberto em transloadit.com/.well-known/skills/index.json, seguindo a RFC Agent Skills Discovery. Isso significa que você também pode instalá-las com:
npx skills add https://transloadit.com
Instalação manual
Clone o repositório transloadit/skills ou crie um link simbólico para ele no diretório de skills do seu agente:
| Agente | Caminho |
|---|---|
| Claude Code | .claude/skills/ |
| OpenAI Codex | .codex/skills/ |
| Gemini CLI | .gemini/skills/ |
| Cursor | .cursor/skills/ |
| Windsurf | .codeium/windsurf/skills/ |
llms.txt
A Transloadit publica um arquivo llms.txt, um índice de roteamento compacto de todo o site que segue o padrão llms.txt. Ele abrange produtos e serviços, soluções, integrações, índices de mídia e de tarefas, recursos para desenvolvedores e de aprendizado, e suporte.
Para descobrir Robots especificamente, use /docs/robots/llms.txt. O
arquivo legado de compatibilidade llms-full.txt inclui inline os
schemas completos dos parâmetros dos Robots, mas é grande. Prefira llms.txt
para a descoberta e busque apenas as páginas Markdown vinculadas que forem relevantes para a tarefa.
Qual abordagem devo usar?
| Abordagem | Ideal para | Configuração |
|---|---|---|
| MCP hospedado com OAuth | Clientes de agente interativos | Adicione a URL e aprove o acesso no seu navegador |
| MCP hospedado com um token Bearer | CI e clientes de agente sem interface | Gere um token em um ambiente confiável |
| MCP com hospedagem própria (stdio) | Executar o servidor localmente, documentação e lint sem conta | Configure o stdio no seu cliente MCP; forneça chaves para operações de conta |
| SDK oficial | Código de aplicação | Instale o SDK correspondente; mantenha o Auth Secret no servidor |
| CLI | Scripts, tarefas de CI e lint sem conta | Execute npx -y @transloadit/node; forneça credenciais para operações de conta |
| Agent Skills | Fluxos de trabalho reutilizáveis da Transloadit, direcionados por humanos | Instale com um único comando |
| llms.txt | Dar a qualquer LLM um contexto amplo da documentação da Transloadit | Busque a URL |
Essas abordagens se complementam. Comece com o MCP hospedado e OAuth no navegador para ter acesso interativo às ferramentas. Para ferramentas de agentes sem supervisão, envie um token Bearer ao MCP hospedado ou forneça uma Auth Key e um Secret ao stdio com hospedagem própria. Use um SDK oficial para código de aplicação ou a CLI para scripts e tarefas de CI. Instale skills para orientar os fluxos de trabalho e aponte seu LLM para o llms.txt para obter contexto de documentação.