Cloudinary

Visão geral

Cloudinary é uma plataforma de gerenciamento de mídia na nuvem para upload, armazenamento, transformação e entrega de imagens e vídeos via CDN. Com a integração no SquadOS, seus agentes podem fazer upload de arquivos, aplicar transformações avançadas, pesquisar ativos por expressão, gerenciar pastas e metadados — tudo de forma programática, sem sair do fluxo de automação.

• Site oficial: https://cloudinary.com/
• Documentação na Composio: docs.composio.dev/toolkits/cloudinary

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Consulte a Composio para os campos obrigatórios de conexão.

Como obter a credencial

1. Acesse cloudinary.com e faça login (ou crie uma conta gratuita).
2. No painel principal, localize o Dashboard — ele exibe seu Cloud name, API Key e API Secret na seção “Product Environment Credentials”.
3. Copie a API Key (e anote o API Secret e o Cloud name, pois a Composio pode solicitá-los no momento da conexão).

Dica

Use as credenciais de um ambiente dedicado (product environment) em vez das credenciais pessoais de conta. O Cloudinary permite criar múltiplos ambientes, facilitando a separação entre produção e desenvolvimento.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Cloudinary.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde informa as credenciais obtidas acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Nota

Esta integração expõe 109 ações no total. Abaixo estão as principais; a lista completa está na documentação da Composio.

Fazer upload de ativo

CLOUDINARY_UPLOAD_ASSET

Faz upload de arquivos de mídia (imagens, vídeos, arquivos brutos) para o Cloudinary a partir de armazenamento local ou URLs remotas. Suporta uploads síncronos e assíncronos com opções de transformação e análise.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
file	object	Não	Arquivo a fazer upload. Forneça este campo ou file_url.
file_url	string	Não	URL de um arquivo remoto a fazer upload. O Cloudinary buscará e fará o upload do arquivo a partir desta URL.
public_id	string	Não	ID público a atribuir ao ativo. Se não especificado, o Cloudinary gera um automaticamente.
resource_type	string (“image” | “video” | “raw” | “auto”)	Não	Tipo do recurso. Use auto para detecção automática.
folder	string	Não	Caminho da pasta onde o ativo deve ser armazenado (ex.: imagens/eventos/2024).
tags	string	Não	Lista de tags separadas por vírgula a atribuir ao ativo.
transformation	string	Não	Transformação a aplicar no upload (ex.: w_400,h_300,c_fill).
overwrite	boolean	Não	Sobrescrever ativos existentes com o mesmo public_id. Padrão: false.
upload_preset	string	Não	Nome de um upload preset a utilizar.
notification_url	string	Não	URL de webhook para notificação ao concluir o upload.
async	boolean	Não	Quando true, o upload é processado de forma assíncrona.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Fazer upload com detecção automática

CLOUDINARY_UPLOAD_FILE_AUTO_DETECT

Faz upload de arquivos com detecção automática do tipo de recurso. Use quando não souber com antecedência se o arquivo é uma imagem, vídeo ou arquivo bruto — o Cloudinary detecta automaticamente com base no conteúdo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
file	string	Sim	Arquivo a fazer upload. Pode ser uma URL (http/https), caminho local ou URI de dados em base64 (ex.: data:image/png;base64,...).
public_id	string	Não	ID público a atribuir ao ativo.
folder	string	Não	Caminho da pasta onde armazenar o upload.
tags	string	Não	Lista de tags separadas por vírgula.
overwrite	boolean	Não	Sobrescrever ativos existentes com o mesmo public_id.
upload_preset	string	Não	Nome de um upload preset. As configurações do preset substituem parâmetros individuais.
transformation	string	Não	Transformação de entrada a aplicar no upload (ex.: c_limit,w_500).
notification_url	string	Não	URL de webhook para notificação ao concluir.
async	boolean	Não	Processar o upload de forma assíncrona.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Pesquisar ativos

CLOUDINARY_SEARCH_ASSETS

Pesquisa e filtra ativos usando expressões de consulta avançadas. Use quando precisar encontrar ativos específicos por tipo de recurso, tags, metadados ou outros atributos, com suporte a ordenação e paginação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
expression	string	Não	Expressão de pesquisa. Suporta correspondência exata, curinga, presença, maior/menor que e intervalos. Exemplo: resource_type:image AND tags:kitten.
max_results	integer	Não	Número máximo de resultados a retornar. Padrão: 50; máximo: 500.
sort_by	array	Não	Array de objetos de ordenação, cada um com um campo e direção. Padrão: [{'created_at': 'desc'}].
fields	string	Não	Lista de campos separados por vírgula a incluir na resposta.
next_cursor	string	Não	Cursor para obter a próxima página de resultados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter recurso por ID público

CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID

Obtém os detalhes de um único recurso pelo ID público. Os três campos resource_type, type e public_id devem corresponder exatamente aos valores do ativo armazenado — uma divergência em qualquer um causa falha na busca, mesmo que o ativo exista sob outra combinação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
public_id	string	Sim	ID público do recurso.
resource_type	string (“image” | “video” | “raw”)	Sim	Tipo do recurso: image, video ou raw.
type	string	Sim	Tipo de entrega: upload, private, authenticated, etc.
faces	boolean	Não	Incluir coordenadas de faces detectadas.
colors	boolean	Não	Incluir histograma de cores e cores predominantes.
max_results	integer	Não	Número máximo de ativos derivados ou relacionados a retornar (1–500).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter recurso por ID de ativo

CLOUDINARY_GET_RESOURCE_BY_ASSET_ID

Obtém detalhes de um recurso pelo seu ID de ativo imutável. Use quando tiver o asset_id e não o public_id.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
asset_id	string	Sim	ID de ativo único e imutável. Diferente do public_id; não substitua um pelo outro.
faces	boolean	Não	Incluir coordenadas de faces detectadas.
colors	boolean	Não	Incluir histograma de cores e cores predominantes.
max_results	integer	Não	Número máximo de ativos derivados a retornar (1–500).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir ativo

CLOUDINARY_DESTROY_ASSET

Exclui permanentemente um ativo do Cloudinary pelo ID público. Esta operação é irreversível e remove o ativo do armazenamento do Cloudinary.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
public_id	string	Sim	ID público do ativo a excluir. Esta operação é permanente e não pode ser desfeita.
resource_type	string (“image” | “video” | “raw”)	Não	Tipo de recurso a excluir. Use video tanto para vídeos quanto para áudios.
invalidate	boolean	Não	Invalidar cópias em cache do ativo no CDN. Pode levar alguns minutos para propagar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar imagens

CLOUDINARY_LIST_IMAGES

Lista ativos de imagem do Cloudinary com filtragem opcional por prefixo, tags ou IDs públicos. Suporta paginação para grandes conjuntos de resultados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
type	string	Não	Tipo de armazenamento dos ativos.
prefix	string	Não	Prefixo de public_id para filtrar. Requer o parâmetro type.
public_ids	array	Não	Lista de IDs públicos a retornar.
tags	boolean	Não	Incluir a lista de tags de cada ativo. Padrão: false.
max_results	integer	Não	Número máximo de resultados a retornar (1–500).
next_cursor	string	Não	Cursor para paginação.
direction	string (“asc” | “desc”)	Não	Direção de ordenação dos resultados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar vídeos

CLOUDINARY_LIST_VIDEOS

Lista ativos de vídeo do Cloudinary com filtragem opcional por prefixo, IDs públicos, tags ou timestamps.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
type	string	Não	Tipo de armazenamento dos ativos de vídeo. Necessário para filtragem por prefixo.
prefix	string	Não	Prefixo de public_id. Requer o parâmetro type.
public_ids	array	Não	Array de IDs públicos a retornar.
tags	boolean	Não	Incluir a lista de tags de cada ativo. Padrão: false.
max_results	integer	Não	Número máximo de resultados a retornar (1–500).
next_cursor	string	Não	Cursor para paginação.
direction	string (“asc” | “desc”)	Não	Direção de ordenação.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar arquivos brutos

CLOUDINARY_LIST_RAW_FILES

Lista arquivos brutos do Cloudinary com filtragem opcional por prefixo, tags ou IDs públicos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
type	string	Não	Tipo de armazenamento dos ativos.
prefix	string	Não	Prefixo de public_id. Requer o parâmetro type.
public_ids	array	Não	Array de IDs públicos a retornar.
tags	boolean	Não	Incluir a lista de tags de cada ativo. Padrão: false.
max_results	integer	Não	Número máximo de resultados a retornar (1–500).
next_cursor	string	Não	Cursor para paginação.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar pasta

CLOUDINARY_CREATE_FOLDER

Cria uma nova pasta de ativos. Use quando precisar organizar ativos em diretórios aninhados. Confirme que o caminho da pasta ainda não existe antes de criar.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
folder	string	Sim	Caminho completo da nova pasta de ativos (ex.: imagens/eventos/2024).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir pasta

CLOUDINARY_DELETE_FOLDER

Exclui uma pasta vazia do Cloudinary. A pasta deve estar vazia antes da exclusão.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
folder	string	Sim	Caminho completo da pasta a excluir. A pasta deve estar vazia.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Pesquisar pastas

CLOUDINARY_SEARCH_FOLDERS

Pesquisa pastas de ativos com filtragem, ordenação e paginação. Use quando precisar localizar pastas específicas por nome, caminho ou data de criação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
expression	string	Não	Expressão de pesquisa estilo Lucene para filtrar pastas. Exemplo: name:sample AND created_at>1w.
max_results	integer	Não	Número máximo de pastas a retornar (1–500). Padrão: 50.
sort_by	array	Não	Lista de objetos de ordenação. Formato: [{'campo':'direção'}].
next_cursor	string	Não	Cursor para a próxima página de resultados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar transformação

CLOUDINARY_CREATE_TRANSFORMATION

Cria uma nova transformação nomeada atribuindo um nome personalizado a um conjunto de parâmetros de transformação. Use quando precisar salvar e reutilizar uma configuração de transformação com um nome memorável.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da transformação a criar.
transformation	string	Sim	String de transformação válida (ex.: w_100,h_150,c_fill,g_auto).
allowed_for_strict	boolean	Não	Se esta transformação nomeada deve ser permitida quando transformações estritas estiverem habilitadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter transformação

CLOUDINARY_GET_TRANSFORMATION

Recupera os detalhes de uma transformação específica. Use quando precisar obter informações sobre uma transformação nomeada ou string de transformação, incluindo seus parâmetros e status de uso.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
transformation	string	Sim	Identificador da transformação. Pode ser uma transformação nomeada (ex.: small_profile_thumbnail) ou uma string de transformação (ex.: w_100,h_150,c_fill,g_auto).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualização explícita de recurso

CLOUDINARY_EXPLICIT_RESOURCE

Atualiza um ativo existente e/ou gera derivações de transformações de forma antecipada (eager) usando a API Explicit do Cloudinary. Use quando precisar pré-gerar transformações, atualizar metadados, mover ativos para novas pastas ou modificar tags em recursos já enviados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
public_id	string	Sim	ID público do recurso existente a atualizar ou gerar transformações.
resource_type	string (“image” | “video” | “raw”)	Não	Tipo do recurso. Padrão: image.
type	string	Não	Tipo de entrega: upload, private ou authenticated. Padrão: upload.
tags	array	Não	Lista de tags a atribuir ao recurso. Substitui as tags existentes.
eager	array	Não	Lista de strings de transformação eager a pré-gerar.
eager_async	boolean	Não	Se true, as transformações eager são geradas de forma assíncrona.
context	object	Não	Metadados contextuais personalizados como pares chave-valor.
metadata	object	Não	Campos de metadados estruturados a definir no recurso.
invalidate	boolean	Não	Invalidar o cache CDN para este ativo (pode levar até 1 hora).
asset_folder	string	Não	Novo caminho de pasta de ativos para mover o recurso (modo de pasta dinâmica).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar recurso por ID público

CLOUDINARY_UPDATE_RESOURCE_BY_PUBLIC_ID

Atualiza propriedades de um ativo pelo ID público no Cloudinary. Use quando precisar modificar tags, metadados, nome de exibição ou outras propriedades sem fazer novo upload.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
public_id	string	Sim	ID público do ativo a atualizar.
resource_type	string (“image” | “video” | “raw”)	Sim	Tipo do recurso: image, video ou raw.
type	string	Sim	Tipo de armazenamento do recurso.
tags	string	Não	Lista de tags separadas por vírgula a atribuir ao recurso.
context	string	Não	Lista de pares chave-valor de metadados contextuais separados por pipe.
metadata	string	Não	Campos de metadados personalizados separados por pipe (por external_id) e seus valores.
display_name	string	Não	Nome de exibição do recurso.
asset_folder	string	Não	Pasta onde o ativo deve ser colocado.
moderation_status	string (“approved” | “rejected”)	Não	Status de moderação do recurso.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Renomear ou mover ID público de recurso

CLOUDINARY_RENAME_RESOURCE

Renomeia o ID público de um ativo usando o endpoint de renomeação do Cloudinary. Use para reorganizar recursos alterando o public_id sem fazer novo upload. Atenção: renomear altera as URLs; considere invalidar o cache CDN.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
from_public_id	string	Sim	ID público atual do recurso a renomear.
to_public_id	string	Sim	Novo ID público do recurso. Pode incluir caminho de pasta (ex.: pasta/novo_nome).
resource_type	string (“image” | “video” | “raw”)	Sim	Tipo do recurso: image, video ou raw.
type	string	Não	Tipo de entrega atual do recurso. Padrão: upload.
overwrite	boolean	Não	Se true, sobrescreve o to_public_id se já existir.
invalidate	boolean	Não	Invalidar o cache CDN para a URL antiga.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Gerar arquivo compactado

CLOUDINARY_GENERATE_ARCHIVE

Cria um arquivo ZIP ou TGZ contendo um conjunto de ativos do seu ambiente Cloudinary. Use quando precisar baixar múltiplos ativos em um único arquivo. Suporta filtragem por tags, IDs públicos ou prefixos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
resource_type	string (“image” | “video” | “raw” | “all”)	Sim	Tipo de recursos a incluir no arquivo.
tags	array	Não	Lista de tags para filtrar ativos a incluir no arquivo.
public_ids	array	Não	Lista de IDs públicos de ativos específicos a incluir.
prefixes	array	Não	Lista de prefixos para filtrar ativos.
target_format	string (“zip” | “tgz”)	Não	Formato do arquivo.
async	boolean	Não	Se true, gera o arquivo de forma assíncrona.
notification_url	string	Não	URL para receber notificação POST ao concluir.
target_public_id	string	Não	ID público a atribuir ao arquivo gerado.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Gerar sprite

CLOUDINARY_GENERATE_SPRITE

Gera sprites mesclando múltiplas imagens em uma única imagem grande. Use quando precisar combinar imagens para entrega web eficiente. Nota: esta API foi descontinuada em 2025 e pode não estar disponível em todas as contas Cloudinary.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
tag	string	Não	Tag que identifica as imagens a incluir no sprite. É necessário fornecer tag ou urls, mas não ambos.
urls	array	Não	Lista de URLs de imagens a incluir no sprite. É necessário fornecer urls ou tag, mas não ambos.
transformation	string	Não	String de transformação a aplicar a cada imagem antes de mesclar no sprite.
async	boolean	Não	Definir como true para geração assíncrona de sprite.
notification_url	string	Não	URL de webhook para notificação ao concluir.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar imagem a partir de texto

CLOUDINARY_CREATE_IMAGE_FROM_TEXT

Cria uma imagem a partir de texto usando a API de geração de texto do Cloudinary. Use quando precisar gerar imagens de texto personalizadas com opções de estilo específicas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
text	string	Sim	O texto a gerar como imagem. Este é o único campo obrigatório.
public_id	string	Não	Identificador para acessar a imagem gerada. Se não especificado, o Cloudinary gera um automaticamente.
font_family	string	Não	Nome da família de fontes a usar.
font_size	integer	Não	Tamanho da fonte em pontos. Padrão: 12.
font_color	string	Não	Nome ou representação RGB da cor da fonte (ex.: red ou rgb:FF0000). Padrão: black.
font_weight	string (“normal” | “bold”)	Não	Peso da fonte.
background	string	Não	Nome ou representação RGB da cor de fundo. Padrão: transparent.
text_align	string (“left” | “center” | “right” | “justify”)	Não	Alinhamento do texto.
opacity	integer	Não	Opacidade do texto entre 0 e 100. Padrão: 100.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Pesquisa visual de ativos

CLOUDINARY_SEARCH_VISUAL_ASSETS

Encontra imagens na sua biblioteca de ativos com base em similaridade visual ou conteúdo. Use quando quiser pesquisar imagens visualmente similares usando uma URL de imagem, um ativo existente ou uma descrição em texto.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
image_url	string	Não	URL de uma imagem a usar como consulta de pesquisa. Encontra imagens visualmente similares.
text	string	Não	Descrição em texto para pesquisar imagens semanticamente similares.
image_asset_id	string	Não	ID de ativo de uma imagem Cloudinary existente a usar como consulta de pesquisa.
threshold	number	Não	Limiar de similaridade para filtrar resultados (0.0–1.0). Valores mais altos retornam resultados mais similares.
max_results	integer	Não	Número máximo de resultados a retornar (1–500). Padrão: 50.
next_cursor	string	Não	Cursor para paginação.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter uso

CLOUDINARY_GET_USAGE

Obtém detalhes de uso do ambiente do produto. Use quando precisar monitorar armazenamento, largura de banda, requisições e outros limites de uso da sua conta Cloudinary. Exceder esses limites pode bloquear uploads silenciosamente — verifique o uso quando operações falharem de forma inesperada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Testar conectividade com o Cloudinary

CLOUDINARY_PING_CLOUDINARY_SERVERS

Testa a acessibilidade e autenticação da API do Cloudinary. Use para verificar se as credenciais estão corretas e se a API está respondendo.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar upload presets

CLOUDINARY_LIST_UPLOAD_PRESETS

Lista todos os upload presets configurados na conta. Use quando precisar recuperar e paginar pelas configurações de upload presets.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
order_by	string (“name” | “id” | “updated_at”)	Não	Campo de ordenação para upload presets.
direction	string (“asc” | “desc”)	Não	Direção de ordenação.
next_cursor	string	Não	Cursor para paginação.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar upload preset

CLOUDINARY_CREATE_UPLOAD_PRESET

Cria um novo upload preset. Use para definir opções centralizadas de upload (tags, formatos, transformações, etc.) antes dos envios de ativos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Não	Nome para o novo preset. Se omitido, o Cloudinary gera um.
folder	string	Não	Caminho de pasta na conta Cloudinary para armazenar uploads.
tags	string	Não	Lista de tags separadas por vírgula a aplicar aos uploads.
eager	string	Não	Transformações eager a gerar no upload (ex.: c_fill,g_face,h_150,w_150).
unsigned	boolean	Não	Permitir uploads sem assinatura usando este preset.
overwrite	boolean	Não	Sobrescrever ativos existentes com o mesmo public_id. Não pode ser true quando unsigned=true.
transformation	string	Não	Transformação de entrada a aplicar no upload (ex.: c_limit,w_500).
allowed_formats	string	Não	Lista de formatos permitidos separados por vírgula (ex.: jpg,png).
notification_url	string	Não	URL de webhook para receber notificações de upload.
resource_type	string (“image” | “video” | “raw”)	Não	Tipo de ativo ao qual este preset se aplica.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar campos de metadados

CLOUDINARY_LIST_METADATA_FIELDS

Lista todos os campos de metadados estruturados definidos no seu ambiente de produto Cloudinary. Use para recuperar definições do esquema de metadados, com filtragem opcional por IDs externos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
external_ids	array	Não	Os IDs externos dos campos de metadados a recuperar. Se não fornecido, todos os campos de metadados serão retornados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar campo de metadados

CLOUDINARY_CREATE_METADATA_FIELD

Cria uma nova definição de campo de metadados. Use ao estender seu esquema de metadados com novos campos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
type	string (“string” | “integer” | “date” | “enum” | “set”)	Sim	Tipo de dado do campo de metadados.
label	string	Sim	Rótulo legível exibido na interface.
external_id	string	Não	ID único para o campo (máx. 255 caracteres). Gerado automaticamente se omitido.
mandatory	boolean	Não	Se um valor é obrigatório (padrão: false).
default_value	string	Não	Valor padrão para o campo. Obrigatório se mandatory=true.
datasource	object	Não	Lista predefinida de valores para campos de metadados do tipo enum ou set.
validation	object	Não	Regras de validação, ex.: greater_than, strlen, strregex.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.