Cloudinary Automation
자연어를 통해 Cloudinary 미디어 관리 워크플로우(폴더 생성, 업로드 프리셋 구성, 에셋 조회, 변환 관리, 폴더 검색, 사용량 모니터링)를 자동화합니다.
툴킷 문서: composio.dev/toolkits/cloudinary
설정
- Rub MCP 서버를 환경에 추가:
https://rube.app/mcp - 프롬프트가 표시되면 Cloudinary 계정을 연결 (Composio를 통한 API 키 인증)
- Cloudinary 자동화를 위한 자연어 명령을 입력
핵심 워크플로우
1. 폴더로 에셋 구성
호스팅된 이미지, 비디오, 원시 파일을 구성하기 위한 폴더 구조를 생성합니다.
도구: CLOUDINARY_CREATE_FOLDER
주요 매개변수:
folder-- 새 에셋 폴더의 전체 경로 (필수), 예:images/events/2023
보조 도구:
CLOUDINARY_SEARCH_FOLDERS-- Lucene 스타일 표현식을 사용하여 이름, 경로, 생성일로 폴더 검색expression-- 검색 필터 (예:name:sample AND path:events)max_results-- 1-500개 결과 (기본값 50)sort_by-- 정렬 객체 목록 (예:[{"created_at": "desc"}])next_cursor-- 페이지네이션 커서
CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER-- 특정 폴더 내 에셋 목록 조회
예시 프롬프트:
"Cloudinary에 'marketing/campaigns/spring-2026' 폴더를 생성해줘"
2. 업로드 프리셋 구성
대상 폴더, 허용 형식, 변환, 태그, 덮어쓰기 규칙 등 중앙 집중식 업로드 동작을 정의합니다.
도구: CLOUDINARY_CREATE_UPLOAD_PRESET
주요 매개변수:
name-- 프리셋 이름 (생략 시 자동 생성)folder-- 업로드 대상 폴더 경로 (예:samples/)allowed_formats-- 쉼표로 구분된 목록 (예:jpg,png,webp)tags-- 적용할 쉼표로 구분된 태그 (예:marketing,thumbnail)transformation-- 수신 변환 (예:c_limit,w_500)eager-- 업로드 시 생성할 eager 변환 (예:c_fill,g_face,h_150,w_150)unsigned-- 서명되지 않은 업로드 허용 (true/false)overwrite-- 동일한 public_id를 가진 기존 에셋 덮어쓰기 (unsigned=true일 때는true불가)resource_type--image,video또는raw(기본값image)unique_filename-- 충돌 방지를 위해 임의 접미사 추가 (기본값true)use_filename-- 원본 파일명 사용 (기본값false)moderation-- 모더레이션 유형:manual,webpurify,aws_rek등auto_tagging-- AI 자동 태깅을 위한 신뢰도 임계값 0.0-1.0notification_url-- 업로드 알림을 위한 웹훅 URL
예시 프롬프트:
"'product-images'라는 업로드 프리셋을 만들어줘. JPG와 PNG만 허용하고, 'products/' 폴더에 저장하며, 0.7 신뢰도로 자동 태깅되게 해줘"
3. 에셋 상세 정보 조회
특정 에셋의 public ID로 메타데이터, 파생 에셋, 관련 리소스를 포함한 전체 상세 정보를 검색합니다.
도구: CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID
주요 매개변수:
public_id-- 에셋의 public ID (필수)resource_type--image,video또는raw(필수)type-- 전송 유형:upload,private,authenticated,fetch등 (필수)colors-- 색상 히스토그램 및 주요 색상 포함faces-- 감지된 얼굴 좌표 포함media_metadata-- IPTC, XMP 및 상세 메타데이터 포함quality_analysis-- 품질 분석 점수 포함phash-- 유사성 감지를 위한 지각 해시 포함versions-- 백업된 버전 포함related-- 관련 에셋 포함max_results-- 반환할 최대 파생/관련 에셋 수 (1-500)
예시 프롬프트:
"이미지 'products/hero-banner'의 색상 분석 및 품질 점수를 포함한 전체 상세 정보를 가져와줘"
4. 변환 및 파생 에셋 관리
기존 변환 목록 조회, 업로드된 에셋에 eager 변환 적용, 파생 리소스 정리.
도구:
CLOUDINARY_GET_TRANSFORMATIONS-- 명명된 및 명명되지 않은 모든 변환 목록 조회max_results-- 1-500 (기본값 10)next_cursor-- 페이지네이션 커서
CLOUDINARY_EXPLICIT_RESOURCE-- 기존 에셋 업데이트: 변환 사전 생성, 메타데이터 업데이트, 새 폴더로 이동, 또는 태그 수정public_id-- 대상 에셋 (필수)eager-- 사전 생성할 변환 문자열 목록 (예:["c_fill,w_300,h_200", "c_thumb,w_100,h_100,g_face"])eager_async-- 비동기적으로 변환 생성tags-- 기존 태그 대체asset_folder-- 에셋을 새 폴더로 이동display_name-- 표시 이름 설정context-- 키-값 메타데이터 (예:{"alt": "Mountain view"})invalidate-- CDN 캐시 무효화 (최대 1시간 소요)
CLOUDINARY_DELETE_DERIVED_RESOURCES-- 특정 파생 에셋을 ID로 삭제 (호출당 최대 100개)
예시 프롬프트:
"에셋 'products/hero-banner'에 대해 300x200 fill 크롭과 100x100 얼굴 감지 썸네일을 사전 생성해줘"
5. 사용량 및 구성 모니터링
계정 수준 사용량 제한, 환경 구성, 태그 인벤토리를 확인합니다.
도구:
CLOUDINARY_GET_USAGE-- 스토리지, 대역폭, 요청, 할당량 한도 모니터링CLOUDINARY_GET_CONFIG-- 환경 구성 세부 정보 조회settings--true로 설정하면folder_mode같은 구성 설정 포함
CLOUDINARY_GET_TAGS-- 리소스 유형별 모든 태그 목록 조회
예시 프롬프트:
"내 Cloudinary 계정 사용량과 남은 할당량을 보여줘"
6. 웹훅 트리거 설정
특정 Cloudinary 이벤트에 대한 웹훅 알림을 생성합니다.
도구: CLOUDINARY_CREATE_TRIGGER
업로드 완료, 변환 완료 또는 기타 이벤트 발생 시 콜백을 수신하는 데 사용합니다.
예시 프롬프트:
"업로드 이벤트가 발생하면 https://my-app.com/hook으로 알림을 보내는 웹훅 트리거를 생성해줘"
알려진 문제점
| 문제점 | 설명 |
|---|---|
| 폴더 생성 멱등성 | CLOUDINARY_CREATE_FOLDER는 경로가 이미 존재하면 오류가 발생하거나 아무 작업도 수행하지 않을 수 있음 -- 멱등적인 폴더 명명 설계 필요 |
| 프리셋-업로드 불일치 | allowed_formats, folder, unsigned 같은 업로드 프리셋 옵션이 실제 업로드 방식과 일치해야 하며, 그렇지 않으면 업로드가 거부됨 |
| 엄격한 에셋 조회 | CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID는 resource_type, type, public_id 중 하나라도 잘못되면 에셋이 존재하더라도 실패함 |
| 폴더 경로 민감성 | CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER는 정확히 지정된 폴더의 에셋만 나열하며, 오타가 있으면 빈 결과를 반환함 |
| 할당량 차단 | CLOUDINARY_GET_USAGE는 계정 수준 제한을 반영하며, 한도에 도달하면 사용량을 확인하고 해결할 때까지 업로드가 자동으로 차단됨 |
| CDN 무효화 지연 | CLOUDINARY_EXPLICIT_RESOURCE에서 invalidate=true를 설정하면 전파에 최대 1시간 소요 |
| 서명되지 않음 vs 덮어쓰기 충돌 | 업로드 프리셋에서 unsigned=true일 때 overwrite=true를 설정할 수 없음 |
빠른 참조
| 작업 | 도구 슬러그 | 주요 매개변수 |
|---|---|---|
| 폴더 생성 | CLOUDINARY_CREATE_FOLDER | folder |
| 폴더 검색 | CLOUDINARY_SEARCH_FOLDERS | expression, max_results |
| 폴더 에셋 목록 | CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER | 폴더 경로 |
| 업로드 프리셋 생성 | CLOUDINARY_CREATE_UPLOAD_PRESET | name, folder, allowed_formats, tags |
| 에셋 상세 정보 조회 | CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID | public_id, resource_type, type |
| 변환 목록 조회 | CLOUDINARY_GET_TRANSFORMATIONS | max_results, next_cursor |
| 에셋 업데이트/변환 | CLOUDINARY_EXPLICIT_RESOURCE | public_id, eager, tags |
| 파생 에셋 삭제 | CLOUDINARY_DELETE_DERIVED_RESOURCES | derived_resource_ids |
| 사용량 조회 | CLOUDINARY_GET_USAGE | (없음) |
| 구성 조회 | CLOUDINARY_GET_CONFIG | settings |
| 태그 목록 조회 | CLOUDINARY_GET_TAGS | resource_type |
| 웹훅 생성 | CLOUDINARY_CREATE_TRIGGER | 이벤트 유형, URL |
Powered by Composio