openclip-thumbnails

OpenClip을 사용해 비디오에서 정지 프레임을 썸네일 이미지로 추출하고, 압축, 리사이즈, 자르기, 포맷 변환(jpg/png/webp)을 수행합니다. OpenClip 계정만 있으면 무료로 사용할 수 있으며, 별도의 구독이 필요하지 않습니다.

openclip-thumbnails란 무엇인가요?

이 스킬은 OpenClip MCP 서버를 통해 비디오에서 썸네일을 추출하고 이미지를 편집하는 두 가지 무료 도구를 제공합니다. `extract_thumbnails`는 비디오에서 고르게 분산된 프레임을 ZIP 파일로 반환하며, `edit_image`는 이미지 압축, 리사이즈, 자르기, 포맷 변환을 단일 작업 단위로 수행합니다. Claude Code, Claude Desktop/Web, Cursor 등 다양한 MCP 클라이언트를 지원하며, OAuth 인증을 통해 API 키 없이 사용할 수 있습니다. 모든 작업은 비동기로 처리되므로 `get_tool_job_status`로 폴링해야 하며, 출력 URL은 영구적인 CDN 링크로 제공됩니다. 특정 시간의 프레임이 필요하면 `edit_video`로 먼저 트리밍한 후 썸네일을 추출하는 방식으로 활용합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor

npx skills add https://github.com/OpenClip-App/agent-skills/tree/main/skills/openclip-thumbnails

문서

OpenClip: 썸네일 및 이미지 편집

두 가지 무료 도구로, 보통 함께 사용됩니다:

extract_thumbnails - 비디오에서 프레임을 추출합니다.
edit_image - 이미지를 압축, 리사이즈, 자르기, 또는 포맷을 변환합니다.

두 도구 모두 무료이며, OpenClip 계정이 필요하지만 구독이나 크레딧은 필요하지 않습니다.

설정 (한 번만)

OpenClip은 https://openclip.app/mcp에 있는 원격 MCP 서버입니다. OAuth 프롬프트가 나타나면 OpenClip 계정으로 로그인하면 되며, 복사할 API 키는 없습니다.

Claude Code: claude mcp add --transport http openclip https://openclip.app/mcp 실행 후 /mcp로 인증합니다.
Claude Desktop / web: 설정 > 커넥터 > "사용자 정의 커넥터 추가"에서 URL을 붙여넣고 로그인합니다.
Cursor (.cursor/mcp.json): { "mcpServers": { "openclip": { "url": "https://openclip.app/mcp" } } }
헤더 전용 클라이언트: openclip.app/settings/connect에서 MCP 토큰을 생성하고 Authorization: Bearer <token> 헤더와 함께 https://openclip.app/mcp/key에 연결합니다.

정상 동작 확인: get_account를 호출해 보세요.

파일 업로드

create_upload(filename, content_type)은 id와 upload_url을 반환합니다.
원시 바이트를 upload_url에 PUT으로 전송합니다.
반환된 id를 video(썸네일) 또는 file(이미지 편집) 인자로 전달합니다.

complete_upload를 호출하지 마세요. 해당 API는 유료 클리핑 파이프라인을 시작합니다. 무료 도구는 업로드된 파일을 직접 읽습니다. list_videos에 있는 비디오도 입력으로 사용할 수 있습니다.

extract_thumbnails

extract_thumbnails(video, count?, width?).

count - 1~10, 기본값 1. 프레임이 비디오 전체에 고르게 분산되므로, count: 5는 선택할 수 있는 대략적인 콘택트 시트를 제공합니다.
width - 출력 프레임의 선택적 픽셀 너비입니다.

출력은 프레임 ZIP 파일이며, 개별 이미지 URL이 아닙니다. 사용자에게 ZIP URL을 제공하거나, 특정 프레임이 필요하면 압축을 풀어 사용하세요.

사용자가 고르게 분산된 프레임 대신 정확한 특정 순간의 프레임을 원할 경우, 먼저 edit_video (operation="trim", openclip-video-editing 참조)로 비디오를 해당 시점으로 자른 후, 잘린 클립에서 썸네일 하나를 추출하세요.

edit_image

edit_image(file, operation, ...params), 한 번 호출에 하나의 작업:

compress - quality 1~100 (기본값 80), 선택적 format (jpg, png, webp).
resize - width와 height (픽셀 단위), 선택적 format.
crop - aspect ("1:1", "9:16", "16:9", "4:5") 또는 명시적 x, y, width, height, 선택적 format.

이미지가 웹 페이지에 사용될 경우 webp를, 모든 환경에서 동작해야 할 경우 jpg를 사용하세요.

폴링

두 도구 모두 status: "queued" 상태의 tool_job 해시 ID를 반환합니다. 5~10초마다 get_tool_job_status(tool_job)을 폴링하세요:

queued / processing - 아직 작업 중, 계속 폴링.
completed - 영구 CDN outputs URL과 result_meta를 반환합니다.
failed - error를 반환합니다.

규칙

항상 폴링하세요. 두 도구 모두 비동기입니다.
한 번 호출에 하나의 edit_image 작업만 수행합니다. 리사이즈 후 압축이 필요하면 두 번의 호출을 순차적으로 실행하세요.
extract_thumbnails는 항상 ZIP을 반환합니다. 사용자에게 개별 프레임 URL을 약속하지 마세요.
출력 URL은 서명이나 만료가 없는 영구 CDN 링크입니다.
무료 사용은 일일 요청 한도와 파일 크기 제한이 있습니다.

예시 프롬프트 → 동작

"이 비디오에서 썸네일을 추출해줘" - create_upload, PUT 바이트, extract_thumbnails(video), 폴링, ZIP URL 반환.
"선택할 수 있게 5개의 프레임을 줘" - extract_thumbnails(video, count=5), 폴링.
"1분 30초 지점의 프레임이 필요해" - edit_video(video, operation="trim", start_ms=90000, end_ms=91000), 폴링, 그 결과에 대해 extract_thumbnails, 폴링.
"이 이미지를 정사각형 webp로 만들어줘" - edit_image(file, operation="crop", aspect="1:1", format="webp"), 폴링.
"이 PNG가 너무 커, 줄여줘" - edit_image(file, operation="compress", quality=75, format="webp"), 폴링.

openclip-thumbnails