Migrar do Cloudinary para o Transloadit

O Cloudinary oferece suporte a upload presets⁠, URLs de transformação⁠ e uma biblioteca de ativos⁠. O Transloadit centraliza o processamento em torno de Assembly Instructions: workflows explícitos que executam Robots para fazer upload, importar, transformar, otimizar, armazenar e entregar arquivos.

Este guia migra uploads e processamento para Templates e exporta ativos para um armazenamento que você controla. Mantenha o catálogo de ativos da sua aplicação junto a esse armazenamento. A importação de DAM hospedado, as pastas e os metadados gerenciados, a entrega pública através de tlcdn.com, as execuções de teste e os manifestos de migração, os papéis da Media Library, os seletores de ativos e as integrações com CMS/editores exigem um plano de migração separado e estão fora deste workflow.

Mapa de migração

Decisões antes de migrar. Esta tabela mapeia tarefas, não APIs intercambiáveis. Recrie no seu backend a validação, a nomenclatura e as regras de acesso dos presets. A seleção automática de formato e qualidade⁠ e o corte baseado em gravidade⁠ do Cloudinary exigem comparações de saída; o corte fixo em WebP abaixo não reproduz o comportamento de f_auto, q_auto ou g_auto. Inventarie separadamente transformações nomeadas, overlays, efeitos de IA e add-ons, e decida quais recriar, manter ou deixar de fora. Este guia não fornece equivalentes para esses efeitos.

Comece pelo workflow, não pela URL

As URLs de transformação do Cloudinary⁠ codificam parâmetros de processamento no caminho de entrega. No Transloadit, coloque os Steps de processamento necessários em um Template e o chame a partir da sua aplicação. Mantenha as definições de Template sob controle de versão junto com o código da sua aplicação e os ativos de regressão.

Por exemplo, este Template produz um corte fixo de 1600 × 900 em WebP e otimiza essa saída. Compare sua aparência e tamanho de arquivo com a versão do Cloudinary que você está substituindo:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "hero": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 1600,
      "height": 900,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized": {
      "use": "hero",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": "optimized",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "media/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Substitua YOUR_AWS_CREDENTIALS por Template Credentials de terceiros salvas. Este exemplo assume que a sua CDN serve a raiz do bucket e tem permissão para ler os seus objetos; url_prefix só altera as URLs retornadas, não a configuração da CDN nem as permissões de acesso. acl: "bucket-default" não envia nenhuma ACL de objeto; configure o acesso através da política do seu bucket e do acesso de origem da CDN.

O seu backend cria uma requisição de Assembly assinada com o template_id salvo e uma notify_url para Assembly Notifications. Verifique a assinatura da notificação e exija ASSEMBLY_COMPLETED antes de atualizar os registros da aplicação. Neste exemplo, leia os arquivos exportados a partir de results.optimized: o Step de armazenamento atualiza as URLs do Step que o produziu. Persista apenas resultados com is_temp_url: false; URLs temporárias do Transloadit expiram após 24 horas e não são URLs de entrega. Veja salvando resultados de conversão.

Substitua URLs de imagem dinâmicas

Se a sua aplicação depende de URLs de transformação dinâmicas, há dois caminhos de migração comuns:

1. Use um Template por família de transformação e dispare uma Assembly quando o ativo for criado ou alterado.
2. Use Smart CDN com URLs assinadas para transformações sob demanda que devem ser armazenadas em cache na borda.

Para páginas de alto tráfego, prefira gerar e armazenar variantes canônicas com antecedência. Para bibliotecas de ativos muito grandes com padrões de acesso de cauda longa, a Smart CDN pode reduzir o trabalho de pré-processamento.

A Smart CDN precisa de um Template separado, composto apenas por Robots compatíveis, com um ramo de resposta terminando em /file/serve. Por exemplo, importe uma imagem, redimensione-a e entregue essa saída. /video/encode e /video/adaptive não são compatíveis com a Smart CDN; gere URLs assinadas da Smart CDN no seu backend.

Substitua as referências de entrega. Mantenha um mapeamento de cada URL de versão original e usada para o seu destino verificado, incluindo referências em registros de banco de dados, srcset, CSS, templates de e-mail e conteúdo de CMS. As URLs de entrega do Cloudinary⁠ codificam o nome do cloud, os tipos de recurso e entrega, e o ID público, com componentes opcionais de transformação e versão; alterar apenas o nome do host não é capaz de traduzir esses caminhos. Substitua referências incorporadas a res.cloudinary.com na sua aplicação. Coloque redirecionamentos em uma rota da aplicação ou em um host de mídia que você controla, preserve a autorização para mídia restrita e mantenha o serviço de origem enquanto links antigos ainda precisarem dele.

Importe ativos existentes do Cloudinary

Construa o inventário primeiro. Use a Admin API⁠ do Cloudinary para listar os tipos de recurso e os tipos de entrega usados na sua conta, percorra next_cursor por todas as páginas e solicite explicitamente tags, context e metadata. Se você restringir a resposta com fields, inclua também esses campos ali. Respeite o limite de taxa da Admin API da conta. Registre asset_id, public_id, tipo, versão, URL de origem, tamanho em bytes e o mapeamento de destino no seu próprio manifesto. Inclua registros de ativos exclusivos da aplicação que o inventário do Cloudinary não consegue fornecer.

Preserve a organização separadamente. Baixar um arquivo não transfere o seu catálogo de ativos:

Reconstrua os relacionamentos e permissões do catálogo na sua aplicação. O Template de importação abaixo copia o binário selecionado e uma miniatura; ele não cria um catálogo de DAM hospedado nem migra metadados, coleções ou histórico de versões. O componente de versão de uma URL de entrega⁠ controla a renovação do cache da CDN; use o mecanismo de download de backup para exportar arquivos anteriores retidos.

Se a mídia selecionada estiver disponível através de uma URL HTTPS autorizada, use 🤖/http/import em vez de fazer upload novamente:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.cloudinary_url}"
    },
    "thumbnail": {
      "use": "imported",
      "robot": "/image/resize",
      "width": 400,
      "height": 400,
      "resize_strategy": "fillcrop",
      "result": true
    },
    "exported": {
      "use": ["imported", "thumbnail"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "cloudinary-import/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

Passe uma URL de origem autorizada como o campo cloudinary_url da Assembly, selecionado pelo seu backend a partir do seu inventário de ativos. Uma URL transformada do Cloudinary⁠ importa essa versão específica; selecione o original deliberadamente quando precisar dele. Para ativos restritos⁠, gere o download autorizado apropriado no seu backend e reserve tempo suficiente para a importação. Mantenha o ID e a URL antigos do ativo até que a exportação concluída esteja acessível pelo caminho de entrega pretendido e suas dimensões e qualidade atendam aos seus requisitos. Este Template de importação retorna os arquivos exportados sob results.imported e results.thumbnail. Um objeto S3 privado ainda precisa de um download autorizado ou da sua CDN configurada.

Widget de upload e automação. Substitua o widget de upload do Cloudinary⁠ pelo Uppy e siga o guia de integração assinada no servidor⁠. Atualize os callbacks para persistir resultados verificados da Assembly. Um seletor da Media Library do Cloudinary⁠ seleciona ativos de DAM existentes; substituir esse seletor e sua integração com o CMS exige um navegador de ativos e um catálogo separados, além da substituição da interface de upload.

As notificações⁠ do Cloudinary cobrem vários eventos de ativos, incluindo notificações separadas de transformação antecipada (eager). Mapeie a conclusão do processamento para Assembly Notifications e trate eventos de renomeação, exclusão, catalogação e moderação na sua aplicação. Reescreva a verificação de assinatura para o formato de notificação do Transloadit, confirme o recebimento apenas após o tratamento durável e deduplique atualizações pelo Assembly ID. Teste falhas e o tratamento de novas tentativas usando a documentação da API de Webhooks, e registre importações com falha no manifesto antes de reenviá-las.

Decisões de segurança. O Cloudinary oferece suporte a uploads assinados e não assinados⁠; o esquema de assinatura não é intercambiável com a autenticação do Transloadit. Autorize usuários e assine apenas os Templates e campos permitidos no seu backend. Trate o acesso de entrega separadamente: o tipo de entrega privado⁠ do Cloudinary protege os originais, mas por padrão permite ativos derivados, enquanto o tipo autenticado protege ambos. Recrie a política pretendida no seu bucket e na sua CDN; um upload assinado ou uma URL de processamento assinada não é uma ACL para um objeto exportado.

Se você usa o add-on de detecção de malware Perception Point⁠ do Cloudinary, planeje a varredura e a quarentena antes da entrega pública no pipeline de substituição. Nenhum dos exemplos aqui ativa varredura de malware ou moderação de conteúdo. Este guia não configura um sistema de quarentena, uma política de moderação de conteúdo, DRM, nem uma implementação completa de controle de acesso.

Agentes e execução repetível. As ferramentas de agentes e servidores MCP⁠ do Cloudinary expõem operações de ativos, transformação, análise e ambiente para clientes de IA. Inventarie quaisquer agentes que chamem essas ferramentas como dependências da aplicação. Peça aos agentes que proponham Template Instructions versionadas e, em seguida, revise e execute o workflow salvo com entradas e variantes de saída limitadas. Mantenha Assembly IDs, motivos de falha e mapeamentos de destino para suporte e reexecução; adicionar um agente não migra o catálogo de ativos nem garante pixels idênticos. Este guia não porta ferramentas MCP individuais nem integrações de agentes.

Lista de verificação

Estimativa de esforço. Como margem de planejamento, reserve vários dias de engenharia para um caminho de upload, algumas transformações fixas e entrega pública, seguidos de tempo de preenchimento retroativo. Uma aplicação intensiva em DAM, com histórico, efeitos personalizados, entrega restrita e integrações com CMS, pode exigir semanas ou mais. Essas são estimativas, não benchmarks de migração medidos. Meça um lote representativo para estimar o tempo de transferência e o custo de processamento; inclua custos de download na origem, custos de armazenamento/CDN no destino e um período de sobreposição. Uma substituição de DAM hospedado precisa de uma estimativa separada.

1. Inventarie ativos, metadados, transformações usadas, integrações de widget/seletor e regras de autorização.
2. Crie Templates versionados e Template Credentials de terceiros; compare saídas representativas.
3. Defina tamanhos de lote limitados, concorrência, limites de novas tentativas e um orçamento de migração. Confirme com a sua equipe a região de execução, a região de armazenamento, a retenção e os requisitos de conformidade antes de mover dados.
4. Execute um piloto pequeno; verifique a conclusão, URLs duráveis, dimensões, tamanhos de arquivo, mapeamentos de metadados, acesso privado e recuperação de erros.
5. Alterne os novos uploads por trás de uma feature flag e faça o preenchimento retroativo dos ativos existentes em lotes limitados. Registre cada sucesso e falha para que novas tentativas não criem ativos duplicados sem rastreamento.
6. Substitua as referências de entrega ou adicione redirecionamentos em infraestrutura que você controla; teste páginas reais, links de e-mail e conteúdo em cache.
7. Mantenha os identificadores do Cloudinary e o caminho de entrega para possível reversão até que o período de sobreposição acordado termine e o inventário seja reconciliado. Desative apenas depois de resolver ativos ausentes e links antigos.