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 "2026년 4분기 분기별 보고서"
- 용도: 파일 구성, 업로드 추적
- 사용 시기: 원본 파일 이름만으로 충분히 설명되지 않을 때
- 표시 이름이 파일 목록에 표시됨
워크플로우 3: 업로드 후 처리 완료 대기
python scripts/upload.py video.mp4 --wait
- 용도: 대용량 파일, 비디오, 오디오
- 파일이 ACTIVE 상태가 될 때까지 대기
- 사용 시기: 업로드 직후 파일을 즉시 사용해야 할 때
워크플로우 4: 분석을 위한 이미지 업로드
# 1. 이미지 업로드
python scripts/upload.py photo.png --name "제품-사진"
# 2. gemini-text로 분석
python skills/gemini-text/scripts/generate.py "이 이미지 설명" --image photo.png
- 용도: 이미지 분석, 캡션 생성, 시각적 Q&A
- 결합: 다중 모드 처리를 위한 gemini-text
워크플로우 5: 콘텐츠 추출을 위한 PDF 업로드
# 1. PDF 업로드
python scripts/upload.py research-paper.pdf --name "AI-연구-논문" --wait
# 2. gemini-text로 콘텐츠 추출
python skills/gemini-text/scripts/generate.py "이 문서에서 주요 결과 추출" --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 "인터뷰-001" --wait
# 2. gemini-text로 처리 (전사 가능한 경우)
python skills/gemini-text/scripts/generate.py "이 오디오를 전사하고 요약" --image interview.mp3
- 용도: 오디오 처리, 전사, 팟캐스트 분석
- 결합: 오디오 분석을 위한 gemini-text
워크플로우 8: 콘텐츠 분석을 위한 비디오 업로드
# 1. 비디오 업로드 (시간이 걸릴 수 있음)
python scripts/upload.py product-demo.mp4 --name "데모-비디오" --wait
# 2. gemini-text로 분석
python skills/gemini-text/scripts/generate.py "이 제품 데모 비디오를 분석" --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 "분석" --image <uploaded-file-path>
일반적인 문제
"google-genai가 설치되지 않음"
pip install google-genai
"파일을 찾을 수 없음"
- 파일 경로가 올바른지 확인
- 상대 경로가 실패하면 절대 경로 사용
- 파일 확장자가 지원되는 유형과 일치하는지 확인
"파일이 너무 큼"
- 파일 유형별 크기 제한 확인
- 가능하면 이미지/비디오 압축
- 대용량 파일을 더 작은 부분으로 분할
"지원되지 않는 파일 유형"
- 지원되는 확장자 확인
- 가능하면 지원되는 형식으로 변환
- 이미지: jpg, png, gif, webp
- 비디오: mp4, mov, avi, webm
"처리 실패"
- 파일이 손상되지 않았는지 확인
- 파일을 다시 업로드해 보세요
- 파일 형식이 유효한지 확인
- API 할당량 한도 확인
"파일이 아직 처리 중입니다" (--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 "내 문서"
# 처리 완료 대기
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"상태: {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
- 지원 형식: 이미지, 오디오, 비디오, 문서 (위 표 참조)