Gemini File API
실행 가능한 스크립트를 통해 Gemini 모델에서 사용할 파일을 업로드하고 관리합니다. 이미지, 오디오, 비디오, PDF 및 기타 파일 형식을 지원합니다.
이 스킬을 사용해야 하는 경우
다음과 같은 상황에서 이 스킬을 사용하세요:
- 다중 모드 분석을 위한 이미지 업로드
- 콘텐츠 처리를 위한 비디오 업로드
- 문서 분석을 위한 PDF 업로드
- 전사 또는 처리를 위한 오디오 업로드
- 배치 작업을 위한 파일 사전 업로드
- 파일 처리 상태 확인
- 업로드된 파일 목록 조회 및 관리
- 다른 Gemini 스킬(텍스트, 이미지 등)과 함께 파일 사용
사용 가능한 스크립트
scripts/upload.py
목적: Gemini File API에 파일 업로드
사용 시점:
- Gemini 처리를 위한 모든 파일 업로드
- 다중 모드 생성을 위한 파일 준비
- 분석을 위한 문서 업로드
- 배치 파일 준비
주요 매개변수:
| 매개변수 | 설명 | 예시 |
|---|---|---|
path | 파일 경로 (필수) | image.jpg |
--name, -n | 표시 이름 | "my-document" |
--wait, -w | 처리 완료 대기 | 플래그 |
출력: 파일 이름, URI 및 상태 정보
워크플로우
워크플로우 1: 기본 파일 업로드
python scripts/upload.py image.jpg
- 최적: 빠른 업로드, 단순 파일
- 출력: API 사용을 위한 파일 이름 및 URI
- 상태: PROCESSING 또는 ACTIVE
워크플로우 2: 사용자 지정 이름으로 업로드
python scripts/upload.py document.pdf --name "Quarterly Report Q4 2026"
- 최적: 파일 구성, 업로드 추적
- 사용 시점: 원래 파일 이름이 충분히 설명적이지 않을 때
- 표시 이름이 파일 목록에 나타납니다.
워크플로우 3: 업로드 후 처리 완료 대기
python scripts/upload.py video.mp4 --wait
- 최적: 대용량 파일, 비디오, 오디오
- 파일이 ACTIVE 상태가 될 때까지 대기
- 사용 시점: 업로드 직후 파일을 즉시 사용해야 할 때
워크플로우 4: 분석을 위한 이미지 업로드
# 1. 이미지 업로드
python scripts/upload.py photo.png --name "product-shot"
# 2. 분석을 위해 gemini-text와 함께 사용
python skills/gemini-text/scripts/generate.py "Describe this image" --image photo.png
- 최적: 이미지 분석, 캡션 생성, 시각적 Q&A
- gemini-text와 결합하여 다중 모드 처리
워크플로우 5: 콘텐츠 추출을 위한 PDF 업로드
# 1. PDF 업로드
python scripts/upload.py research-paper.pdf --name "AI-Research-Paper" --wait
# 2. gemini-text로 콘텐츠 추출
python skills/gemini-text/scripts/generate.py "Extract key findings from this document" --image research-paper.pdf
- 최적: 문서 처리, 콘텐츠 추출
- gemini-text와 결합하여 분석
워크플로우 6: 배치를 위한 여러 파일 업로드
# 1. 여러 파일 업로드
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. 업로드된 파일을 사용하여 배치 작업 생성 (gemini-batch 스킬)
- 최적: 배치 처리를 위한 파일 준비
- gemini-batch와 결합하여 대량 작업
워크플로우 7: 전사를 위한 오디오 업로드
# 1. 오디오 업로드
python scripts/upload.py interview.mp3 --name "interview-001" --wait
# 2. gemini-text로 처리 (전사 기능 사용 가능한 경우)
python skills/gemini-text/scripts/generate.py "Transcribe and summarize this audio" --image interview.mp3
- 최적: 오디오 처리, 전사, 팟캐스트 분석
- gemini-text와 결합하여 오디오 분석
워크플로우 8: 콘텐츠 분석을 위한 비디오 업로드
# 1. 비디오 업로드 (시간이 걸릴 수 있음)
python scripts/upload.py product-demo.mp4 --name "demo-video" --wait
# 2. gemini-text로 분석
python skills/gemini-text/scripts/generate.py "Analyze this product demo video" --image product-demo.mp4
- 최적: 비디오 분석, 콘텐츠 요약
- 참고: 비디오는 상당한 처리 시간이 필요할 수 있음
매개변수 참조
지원되는 파일 형식
| 유형 | 확장자 | 최대 크기 | 처리 시간 |
|---|---|---|---|
| 이미지 | jpg, jpeg, png, gif, webp | 20MB | 초 |
| 오디오 | mp3, wav, aac, flac | 25MB | 초-분 |
| 비디오 | mp4, mov, avi, webm | 2GB | 분-시간 |
| 문서 | pdf, txt | 50MB | 초-분 |
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와 함께
python skills/gemini-text/scripts/generate.py "Analyze" --image <uploaded-file-path>
일반적인 문제
"google-genai not installed"
pip install google-genai
"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: 파일 콘텐츠에서 임베딩 생성
빠른 참조
# 기본 업로드
python scripts/upload.py image.jpg
# 사용자 지정 이름
python scripts/upload.py document.pdf --name "My Document"
# 처리 완료 대기
python scripts/upload.py video.mp4 --wait
# 여러 파일
for file in *.jpg; do python scripts/upload.py "$file"; done
파일 관리 API
스크립트에는 없지만, Python을 통해 파일을 관리할 수도 있습니다:
from google import genai
client = genai.Client()
# 모든 파일 나열
for file in client.files.list():
print(f"{file.name}: {file.display_name} ({file.state})")
# 파일 정보 가져오기
file = client.files.get(name="files/abc123...")
print(f"State: {file.state}")
# 파일 삭제
client.files.delete(name="files/abc123...")
참조
- API 키 받기: https://aistudio.google.com/apikey
- 문서: https://ai.google.dev/gemini-api/docs/file-upload
- 파일 API: https://ai.google.dev/gemini-api/docs/files
- 지원되는 형식: 이미지, 오디오, 비디오, 문서 (위 표 참조)