Communitygithub.com

akrindev/google-studio-skills

스크립트를 통해 Google Gemini File API에 파일을 업로드하고 관리합니다. 이미지, 오디오, 비디오, PDF 등 다양한 파일을 Gemini 모델에 사용할 수 있도록 지원하며, 업로드, 상태 확인, 파일 관리 기능을 제공합니다.

google-studio-skills란 무엇인가요?

이 스킬은 Google Gemini File API를 활용하여 명령줄 스크립트로 파일을 업로드하고 관리하는 방법을 제공합니다. 주로 Claude Code, Cursor, Codex와 같은 AI 에이전트에서 이미지(멀티모달 분석), 오디오(전사), 비디오(콘텐츠 분석), PDF(문서 분석) 등의 파일을 Gemini 모델에 전달하기 전에 준비하는 데 사용됩니다. `node scripts/upload.js <파일경로>` 명령어로 간단히 업로드할 수 있으며, `--name`으로 표시 이름을 지정하거나 `--wait` 플래그로 처리 완료를 기다릴 수 있습니다. 스킬은 파일 상태(PROCESSING, ACTIVE, FAILED)를 확인하고, gemini-text, gemini-image, gemini-batch, gemini-embeddings 등 다른 Gemini 스킬과 연계하여 멀티모달 분석, 배치 처리, 임베딩 생성 등을 수행할 수 있습니다. 파일 크기 제한(이미지 20MB, 오디오 25MB, 비디오 2GB, 문서 50MB)과 MIME 타입 자동 감지, 병렬 업로드 및 오류 처리 모범 사례를 포함합니다.

지원 대상~Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/akrindev/google-studio-skills/tree/HEAD/skills/gemini-files
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

Gemini File API

Gemini 모델에 사용할 파일을 실행 가능한 스크립트를 통해 업로드하고 관리합니다. 이미지, 오디오, 비디오, PDF 및 기타 파일 유형을 지원합니다.

이 스킬을 사용해야 하는 경우

다음과 같은 상황에서 이 스킬을 사용하세요:

  • 멀티모달 분석을 위한 이미지 업로드
  • 콘텐츠 처리를 위한 비디오 업로드
  • 문서 분석을 위한 PDF 업로드
  • 전사 또는 처리를 위한 오디오 업로드
  • 배치 작업을 위한 사전 파일 업로드
  • 파일 처리 상태 확인
  • 업로드된 파일 목록 조회 및 관리
  • 다른 Gemini 스킬(텍스트, 이미지 등)과 함께 파일 사용

사용 가능한 스크립트

scripts/upload.js

목적: 파일을 Gemini File API에 업로드합니다.

사용해야 하는 경우:

  • Gemini 처리를 위해 어떤 파일이든 업로드할 때
  • 멀티모달 생성을 위해 파일을 준비할 때
  • 분석을 위해 문서를 업로드할 때
  • 배치 파일 준비 시

주요 매개변수:

매개변수설명예시
path파일 경로 (필수)image.jpg
--name, -n표시 이름"my-document"
--wait, -w처리 완료 대기플래그

출력: 파일 이름, URI 및 상태 정보

워크플로우

워크플로우 1: 기본 파일 업로드

node scripts/upload.js image.jpg
  • 최적 대상: 빠른 업로드, 간단한 파일
  • 출력: API 사용을 위한 파일 이름 및 URI
  • 상태: PROCESSING 또는 ACTIVE

워크플로우 2: 사용자 정의 이름으로 업로드

node scripts/upload.js document.pdf --name "2026년 4분기 분기별 보고서"
  • 최적 대상: 파일 구성, 업로드 추적
  • 사용 시점: 원본 파일명이 충분히 설명적이지 않을 때
  • 표시 이름은 파일 목록에 나타납니다.

워크플로우 3: 업로드 후 처리 완료 대기

node scripts/upload.js video.mp4 --wait
  • 최적 대상: 대용량 파일, 비디오, 오디오
  • 파일이 ACTIVE 상태가 될 때까지 대기
  • 사용 시점: 업로드 직후 파일을 사용해야 할 때

워크플로우 4: 이미지 업로드 및 분석

# 1. 이미지 업로드
node scripts/upload.js photo.png --name "제품 사진"

# 2. gemini-text와 함께 사용하여 분석
node skills/gemini-text/scripts/generate.js "이 이미지 설명" --image photo.png
  • 최적 대상: 이미지 분석, 캡셔닝, 시각적 Q&A
  • 결합: 멀티모달 처리를 위한 gemini-text

워크플로우 5: PDF 업로드 및 콘텐츠 추출

# 1. PDF 업로드
node scripts/upload.js research-paper.pdf --name "AI-연구-논문" --wait

# 2. gemini-text로 콘텐츠 추출
node skills/gemini-text/scripts/generate.js "이 문서에서 주요 발견 사항 추출" --image research-paper.pdf
  • 최적 대상: 문서 처리, 콘텐츠 추출
  • 결합: 분석을 위한 gemini-text

워크플로우 6: 여러 파일 배치 업로드

# 1. 여러 파일 업로드
for file in *.jpg; do
    node scripts/upload.js "$file"
done

# 2. 업로드된 파일로 배치 작업 생성 (gemini-batch 스킬)
  • 최적 대상: 배치 처리를 위한 파일 준비
  • 결합: 대량 작업을 위한 gemini-batch

워크플로우 7: 오디오 업로드 및 전사

# 1. 오디오 업로드
node scripts/upload.js interview.mp3 --name "인터뷰-001" --wait

# 2. gemini-text로 처리 (전사 가능한 경우)
node skills/gemini-text/scripts/generate.js "이 오디오를 전사하고 요약" --image interview.mp3
  • 최적 대상: 오디오 처리, 전사, 팟캐스트 분석
  • 결합: 오디오 분석을 위한 gemini-text

워크플로우 8: 비디오 업로드 및 콘텐츠 분석

# 1. 비디오 업로드 (시간이 걸릴 수 있음)
node scripts/upload.js product-demo.mp4 --name "데모-비디오" --wait

# 2. gemini-text로 분석
node skills/gemini-text/scripts/generate.js "이 제품 데모 비디오 분석" --image product-demo.mp4
  • 최적 대상: 비디오 분석, 콘텐츠 요약
  • 참고: 비디오는 상당한 처리 시간이 필요할 수 있습니다.

매개변수 참조

지원되는 파일 유형

유형확장자최대 크기처리 시간
이미지jpg, jpeg, png, gif, webp20MB수 초
오디오mp3, wav, aac, flac25MB수 초~분
비디오mp4, mov, avi, webm2GB수 분~시간
문서pdf, txt50MB수 초~분

MIME 유형

스크립트가 확장자에 따라 자동 감지:

  • 이미지: image/jpeg, image/png, image/gif, image/webp
  • 오디오: audio/mpeg, audio/wav
  • 비디오: video/mp4, video/quicktime, video/webm
  • 문서: application/pdf, text/plain

파일 상태

상태설명사용 가능 여부
PROCESSING파일이 분석 중입니다아니요
ACTIVE파일이 준비되었습니다예
FAILED처리가 실패했습니다아니요

출력 해석

업로드 응답

Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING
  • 파일 이름: API 호출에 사용
  • URI: 내부 Google Cloud Storage 참조
  • 상태: PROCESSING = 대기, ACTIVE = 준비 완료

--wait 플래그 사용 시

Uploading video.mp4...
Uploaded: files/xyz789...
URI: gs://generation-tmp/xyz789...
State: PROCESSING
Waiting for processing...
Still processing...
File ready!
  • 스크립트가 상태가 ACTIVE가 될 때까지 폴링합니다.
  • 처리가 필요한 대용량 파일에 사용합니다.
  • 비디오의 경우 몇 분이 소요될 수 있습니다.

업로드된 파일 사용

파일이 업로드되면 이름으로 참조:

# gemini-text와 함께
node skills/gemini-text/scripts/generate.js "분석" --image <uploaded-file-path>

일반적인 문제

"google-genai not installed"

npm install @google/genai@latest dotenv@latest

"File not found"

  • 파일 경로가 올바른지 확인하세요.
  • 상대 경로가 실패하면 절대 경로를 사용하세요.
  • 파일 확장자가 지원되는 유형과 일치하는지 확인하세요.

"File too large"

  • 파일 유형별 크기 제한을 확인하세요.
  • 가능하면 이미지/비디오를 압축하세요.
  • 대용량 파일을 더 작은 부분으로 분할하세요.

"Unsupported file type"

  • 지원되는 확장자를 확인하세요.
  • 가능하면 지원되는 형식으로 변환하세요.
  • 이미지: jpg, png, gif, webp
  • 비디오: mp4, mov, avi, webm

"Processing failed"

  • 파일이 손상되지 않았는지 확인하세요.
  • 파일을 다시 업로드해 보세요.
  • 파일 형식이 유효한지 확인하세요.
  • API 할당량 제한을 확인하세요.

"File still processing" (--wait 없이)

  • 파일 상태가 PROCESSING이며 ACTIVE가 아닙니다.
  • --wait 플래그를 사용하거나 나중에 상태를 확인하세요.
  • 대용량 파일(특히 비디오)은 시간이 걸립니다.
  • 처리 시간은 몇 분에서 몇 시간까지 걸릴 수 있습니다.

모범 사례

업로드 전략

  • 바로 사용할 파일에는 --wait를 사용하세요.
  • 배치 업로드 시 시간을 절약하려면 --wait를 생략하세요.
  • 구성을 위해 설명적인 --name을 사용하세요.
  • 나중에 사용하기 위해 파일 이름을 기록해 두세요.

파일 구성

  • 일관된 명명 규칙을 사용하세요.
  • 이름에 날짜나 버전을 포함하세요.
  • 관련 파일을 함께 그룹화하세요.
  • 코드에 파일 이름을 문서화하세요.

성능 팁

  • 여러 파일을 병렬로 업로드하세요 (별도 프로세스).
  • 배치 작업을 위해 파일을 사전 업로드하세요.
  • API 호출 전에 파일 상태를 확인하세요.
  • 저장 공간을 관리하기 위해 오래된 파일을 삭제하세요.

오류 처리

  • 업로드 후 반환 상태를 확인하세요.
  • 실패한 업로드를 재시도하세요.
  • 업로드 전에 파일 무결성을 확인하세요.
  • 감사 추적을 위해 파일 이름을 로깅하세요.

다른 스킬과의 통합

  • gemini-text: 멀티모달 분석, 문서 처리
  • gemini-image: 업로드된 참조를 기반으로 이미지 생성
  • gemini-batch: 배치 작업에 업로드된 파일 사용
  • gemini-embeddings: 파일 콘텐츠에서 임베딩 생성

파일 수명 주기

  • 업로드 → PROCESSING → ACTIVE → API에서 사용
  • 저장 공간을 확보하기 위해 오래된 파일 삭제
  • 파일은 일정 기간 후에 만료될 수 있음
  • 백업을 위해 중요한 파일 다운로드

관련 스킬

  • gemini-text: 텍스트 생성으로 업로드된 파일 분석
  • gemini-image: 업로드된 참조를 기반으로 이미지 생성
  • gemini-batch: 배치 처리에 업로드된 파일 사용
  • gemini-embeddings: 파일 콘텐츠에서 임베딩 생성

빠른 참조

# 기본 업로드
node scripts/upload.js image.jpg

# 사용자 정의 이름 사용
node scripts/upload.js document.pdf --name "내 문서"

# 처리 완료 대기
node scripts/upload.js video.mp4 --wait

# 여러 파일
for file in *.jpg; do node scripts/upload.js "$file"; done

파일 관리 API

스크립트에는 없지만, JavaScript로 파일을 관리할 수도 있습니다:

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// 모든 파일 목록 조회
for await (const file of client.files.list()) {
  console.log(`${file.name}: ${file.displayName} (${file.state})`);
}

// 파일 정보 가져오기
const file = await client.files.get({ name: "files/abc123..." });
console.log(`상태: ${file.state}`);

// 파일 삭제
await client.files.delete({ name: "files/abc123..." });

참조

관련 스킬

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community