Cloudinary Automation (Automação Cloudinary)

Automação Cloudinary

Automatize fluxos de trabalho de gerenciamento de mídia do Cloudinary — crie pastas, configure predefinições de upload, busque ativos, gerencie transformações, pesquise pastas e monitore o uso — tudo por meio de linguagem natural.

Documentação do toolkit: composio.dev/toolkits/cloudinary

---

Configuração

1. Adicione o servidor MCP Rube ao seu ambiente: https://rube.app/mcp
2. Conecte sua conta Cloudinary quando solicitado (autenticação via chave API através do Composio)
3. Comece a emitir comandos em linguagem natural para automação do Cloudinary

---

Fluxos de Trabalho Principais

1. Organizar Ativos com Pastas

Crie estruturas de pastas para organizar imagens, vídeos e arquivos brutos hospedados.

Ferramenta: CLOUDINARY_CREATE_FOLDER

Parâmetros principais:

• folder — caminho completo da nova pasta de ativos (obrigatório), ex.: images/events/2023

Ferramentas de suporte:

• CLOUDINARY_SEARCH_FOLDERS — pesquise pastas por nome, caminho ou data de criação usando expressões no estilo Lucene
  • expression — filtro de pesquisa (ex.: name:sample AND path:events)
  • max_results — 1-500 resultados (padrão 50)
  • sort_by — lista de objetos de ordenação (ex.: [{"created_at": "desc"}])
  • next_cursor — cursor de paginação
• CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER — liste ativos dentro de uma pasta específica

Exemplo de prompt:

"Crie uma pasta chamada 'marketing/campaigns/spring-2026' no Cloudinary"

---

2. Configurar Predefinições de Upload

Defina comportamentos centralizados de upload, incluindo pasta de destino, formatos permitidos, transformações, tags e regras de substituição.

Ferramenta: CLOUDINARY_CREATE_UPLOAD_PRESET

Parâmetros principais:

• name — nome da predefinição (gerado automaticamente se omitido)
• folder — caminho da pasta de destino para uploads (ex.: samples/)
• allowed_formats — lista separada por vírgulas (ex.: jpg,png,webp)
• tags — tags separadas por vírgulas a serem aplicadas (ex.: marketing,thumbnail)
• transformation — transformação de entrada (ex.: c_limit,w_500)
• eager — transformações imediatas a serem geradas no upload (ex.: c_fill,g_face,h_150,w_150)
• unsigned — permitir uploads não assinados (true/false)
• overwrite — substituir ativos existentes com o mesmo public_id (não pode ser true quando unsigned=true)
• resource_type — image, video ou raw (padrão image)
• unique_filename — anexar sufixo aleatório para evitar colisões (padrão true)
• use_filename — usar o nome do arquivo original (padrão false)
• moderation — tipo de moderação: manual, webpurify, aws_rek, etc.
• auto_tagging — limiar de confiança entre 0.0 e 1.0 para marcação automática por IA
• notification_url — URL de webhook para notificações de upload

Exemplo de prompt:

"Crie uma predefinição de upload chamada 'product-images' que permita apenas JPG e PNG, armazene na pasta 'products/' e faça marcação automática com confiança 0.7"

---

3. Buscar Detalhes de Ativos

Recupere detalhes completos de um ativo específico pelo seu ID público, incluindo metadados, ativos derivados e recursos relacionados.

Ferramenta: CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID

Parâmetros principais:

• public_id — ID público do ativo (obrigatório)
• resource_type — image, video ou raw (obrigatório)
• type — tipo de entrega: upload, private, authenticated, fetch, etc. (obrigatório)
• colors — incluir histograma de cores e cores predominantes
• faces — incluir coordenadas de faces detectadas
• media_metadata — incluir metadados IPTC, XMP e detalhados
• quality_analysis — incluir pontuações de análise de qualidade
• phash — incluir hash perceptual para detecção de similaridade
• versions — incluir versões com backup
• related — incluir ativos relacionados
• max_results — máximo de ativos derivados/relacionados a retornar (1-500)

Exemplo de prompt:

"Obtenha detalhes completos da imagem 'products/hero-banner' incluindo análise de cores e pontuações de qualidade"

---

4. Gerenciar Transformações e Ativos Derivados

Liste transformações existentes, aplique transformações imediatas em ativos carregados e limpe recursos derivados.

Ferramentas:

• CLOUDINARY_GET_TRANSFORMATIONS — liste todas as transformações nomeadas e não nomeadas
  • max_results — 1-500 (padrão 10)
  • next_cursor — cursor de paginação
• CLOUDINARY_EXPLICIT_RESOURCE — atualize um ativo existente: pré-gerar transformações, atualizar metadados, mover para novas pastas ou modificar tags
  • public_id — ativo alvo (obrigatório)
  • eager — lista de strings de transformação para pré-gerar (ex.: ["c_fill,w_300,h_200", "c_thumb,w_100,h_100,g_face"])
  • eager_async — gerar transformações de forma assíncrona
  • tags — substituir tags existentes
  • asset_folder — mover ativo para uma nova pasta
  • display_name — definir nome de exibição
  • context — metadados chave-valor (ex.: {"alt": "Vista da montanha"})
  • invalidate — invalidar cache do CDN (leva até 1 hora)
• CLOUDINARY_DELETE_DERIVED_RESOURCES — exclua ativos derivados específicos por IDs (até 100 por chamada)

Exemplo de prompt:

"Pré-gerar um recorte de preenchimento de 300x200 e uma miniatura de detecção de rosto de 100x100 para o ativo 'products/hero-banner'"

---

5. Monitorar Uso e Configuração

Verifique limites de uso no nível da conta, configuração do ambiente e inventário de tags.

Ferramentas:

• CLOUDINARY_GET_USAGE — monitore armazenamento, largura de banda, requisições e limites de cota
• CLOUDINARY_GET_CONFIG — busque detalhes da configuração do ambiente
  • settings — defina como true para incluir configurações como folder_mode
• CLOUDINARY_GET_TAGS — liste todas as tags para um tipo de recurso

Exemplo de prompt:

"Mostre-me o uso da minha conta Cloudinary e a cota restante"

---

6. Configurar Gatilhos de Webhook

Crie notificações webhook para eventos específicos do Cloudinary.

Ferramenta: CLOUDINARY_CREATE_TRIGGER

Use para receber callbacks quando uploads forem concluídos, transformações terminarem ou outros eventos ocorrerem.

Exemplo de prompt:

"Crie um gatilho de webhook que notifique https://meu-app.com/hook em eventos de upload"

---

Armadilhas Conhecidas

Armadilha	Detalhes
Idempotência na criação de pastas	CLOUDINARY_CREATE_FOLDER pode gerar erro ou não fazer nada se o caminho já existir — projete nomes de pastas idempotentes
Alinhamento predefinição-upload	Opções da predefinição como allowed_formats, folder e unsigned devem corresponder ao método de upload real, senão os uploads serão rejeitados
Busca estrita de ativos	CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID falha se algum dos parâmetros resource_type, type ou public_id estiver incorreto, mesmo que o ativo exista
Sensibilidade do caminho da pasta	CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER lista apenas ativos na pasta exata especificada; erros de digitação retornam resultados vazios
Bloqueio por cota	CLOUDINARY_GET_USAGE reflete limites no nível da conta — atingir limites silenciosamente bloqueia uploads até que o uso seja verificado e resolvido
Atraso na invalidação do CDN	Definir invalidate=true em CLOUDINARY_EXPLICIT_RESOURCE leva até 1 hora para propagar
Conflito unsigned vs overwrite	Não é possível definir overwrite=true quando unsigned=true em predefinições de upload

---

Referência Rápida

Ação	Slug da Ferramenta	Parâmetros Principais
Criar pasta	CLOUDINARY_CREATE_FOLDER	folder
Pesquisar pastas	CLOUDINARY_SEARCH_FOLDERS	expression, max_results
Listar ativos da pasta	CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER	caminho da pasta
Criar predefinição de upload	CLOUDINARY_CREATE_UPLOAD_PRESET	name, folder, allowed_formats, tags
Obter detalhes do ativo	CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID	public_id, resource_type, type
Listar transformações	CLOUDINARY_GET_TRANSFORMATIONS	max_results, next_cursor
Atualizar/transformar ativo	CLOUDINARY_EXPLICIT_RESOURCE	public_id, eager, tags
Excluir ativos derivados	CLOUDINARY_DELETE_DERIVED_RESOURCES	derived_resource_ids
Obter uso	CLOUDINARY_GET_USAGE	(nenhum)
Obter configuração	CLOUDINARY_GET_CONFIG	settings
Listar tags	CLOUDINARY_GET_TAGS	resource_type
Criar webhook	CLOUDINARY_CREATE_TRIGGER	tipo de evento, URL

---

Desenvolvido por Composio