AI 멀티모달은(는) 무엇을 하나요?
Google Gemini의 멀티모달 API를 사용하여 오디오, 이미지, 비디오, 문서를 처리하고 이미지/비디오를 생성합니다.
설정
export GEMINI_API_KEY="your-key" # https://aistudio.google.com/apikey 에서 발급
pip install google-genai python-dotenv pillow
API 키 로테이션 (선택 사항)
대용량 사용 또는 속도 제한에 도달했을 때 여러 API 키를 설정할 수 있습니다:
# 기본 키 (필수)
export GEMINI_API_KEY="key1"
# 로테이션용 추가 키 (선택 사항)
export GEMINI_API_KEY_2="key2"
export GEMINI_API_KEY_3="key3"
또는 .env 파일에:
GEMINI_API_KEY=key1
GEMINI_API_KEY_2=key2
GEMINI_API_KEY_3=key3
기능:
- 속도 제한(429/RESOURCE_EXHAUSTED) 오류 시 자동 키 로테이션
- 속도 제한 후 키당 60초 쿨다운
--verbose플래그로 로테이션 이벤트 기록- 하위 호환성: 단일 키도 정상 작동
빠른 시작
설정 확인: python scripts/check_setup.py
미디어 분석: python scripts/gemini_batch_process.py --files <file> --task <analyze|transcribe|extract>
- 팁: 이미지 분석 요청 시,
gemini명령이 사용 가능한지 확인하고 가능하면echo "<분석 프롬프트>" | gemini -y -m <gemini.model>명령을 사용하세요 (모델은.claude/.ck.json의gemini.model에서 읽음).gemini명령이 없으면python scripts/gemini_batch_process.py --files <file> --task analyze명령을 사용하세요. 콘텐츠 생성:python scripts/gemini_batch_process.py --task <generate|generate-video> --prompt "설명"
stdin 지원: stdin으로 파일을 직접 파이프할 수 있습니다 (PNG/JPG/PDF/WAV/MP3 자동 감지).
cat image.png | python scripts/gemini_batch_process.py --task analyze --prompt "이것을 설명하세요"python scripts/gemini_batch_process.py --files image.png --task analyze(전통적 방식)
모델
- 이미지 생성:
imagen-4.0-generate-001(표준),imagen-4.0-ultra-generate-001(품질),imagen-4.0-fast-generate-001(속도) - 비디오 생성:
veo-3.1-generate-preview(오디오 포함 8초 클립) - 분석:
gemini-2.5-flash(권장),gemini-2.5-pro(고급)
스크립트
gemini_batch_process.py:transcribe|analyze|extract|generate|generate-video작업을 위한 CLI 오케스트레이터로, API 키를 자동 확인하고 작업별로 적절한 기본 모델을 선택하며, 파일을 인라인 또는 File API로 스트리밍하고, Imagen 4 + Veo 워크플로를 위해 구조화된 출력(텍스트/JSON/CSV/markdown 및 생성된 에셋)을 저장합니다.media_optimizer.py: ffmpeg/Pillow 기반 전처리 도구로, 오디오, 이미지, 비디오 입력을 압축/리사이즈/변환하고, 대상 크기/비트레이트를 적용하며, 긴 클립을 시간 단위로 분할하고, 디렉토리를 일괄 처리하여 미디어가 Gemini 제한 내에 있도록 합니다.document_converter.py: Gemini 기반 변환기로, PDF/이미지/Office 문서를 업로드하고, 마크다운 보존 프롬프트를 적용하며, 여러 파일을 일괄 처리하고,docs/assets아래에 자동으로 출력 파일 이름을 지정하며, 모델, 프롬프트, 자동 파일 이름 지정, 상세 로깅을 위한 CLI 플래그를 제공합니다.check_setup.py: 대화형 준비 상태 확인 도구로, 디렉토리 구조, 중앙 집중식 env 해석기, 필수 Python 종속성, GEMINI_API_KEY 가용성/형식을 확인한 후 라이브 Gemini API 호출을 수행하고, 문제가 있을 경우 해결 지침을 출력합니다.
--help를 사용하여 옵션을 확인하세요.
참고 자료
자세한 지침은 다음 파일을 참조하세요:
| 주제 | 파일 | 설명 |
|---|---|---|
| 음악 | references/music-generation.md | 배경 음악 생성을 위한 Lyria RealTime API, 스타일 프롬프트, 실시간 제어, 비디오 제작과의 통합. |
| 오디오 | references/audio-processing.md | 오디오 형식 및 제한, 전사(타임스탬프, 화자, 세그먼트), 비음성 분석, File API vs 인라인 입력, TTS 모델, 모범 사례, 비용 및 토큰 계산, 구체적인 회의/팟캐스트/인터뷰 레시피. |
| 이미지 | references/vision-understanding.md | 비전 기능 개요, 지원 형식 및 모델, 캡션 생성/분류/VQA, 탐지 및 세분화, OCR 및 문서 읽기, 다중 이미지 워크플로, 구조화된 JSON 출력, 토큰 비용, 모범 사례, 일반적인 제품/스크린샷/차트/장면 사용 사례. |
| 이미지 생성 | references/image-generation.md | Imagen 4 및 Gemini 이미지 모델 개요, generate_images vs generate_content API, 종횡비 및 비용, 텍스트/이미지/이미지+텍스트 모드, 편집 및 구성, 스타일 및 품질 제어, 안전 설정, 모범 사례, 문제 해결, 일반적인 마케팅/컨셉 아트/UI 시나리오. |
| 비디오 | references/video-analysis.md | 비디오 분석 기능 및 지원 형식, 모델/컨텍스트 선택, 로컬/인라인/YouTube 입력, 클리핑 및 FPS 제어, 다중 비디오 비교, 시간 기반 Q&A 및 장면 탐지, 시각적 컨텍스트를 포함한 전사, 토큰 및 비용 안내, 최적화/모범 사례 패턴. |
| 비디오 생성 | references/video-generation.md | Veo 모델 매트릭스, 텍스트-비디오 및 이미지-비디오 빠른 시작, 다중 참조 및 확장 워크플로, 카메라 및 타이밍 제어, 구성(해상도, 종횡비, 오디오, 안전), 프롬프트 디자인 패턴, 성능 팁, 제한 사항, 문제 해결, 비용 추정. |
제한 사항
형식: 오디오(WAV/MP3/AAC, 9.5시간), 이미지(PNG/JPEG/WEBP, 3.6천 개), 비디오(MP4/MOV, 6시간), PDF(1천 페이지) 크기: 인라인 20MB, File API 2GB 중요:
- 오디오 길이가 15분을 초과하는 경우, Gemini API 응답의 출력 토큰 제한으로 인해 전사 내용이 종종 잘립니다. 완전한 전사본을 얻으려면 오디오를 더 작은 청크(최대 15분)로 분할하고 각 세그먼트를 개별적으로 전사해야 합니다.
- 비디오 길이가 15분을 초과하는 경우, ffmpeg를 사용하여 비디오에서 오디오를 추출하고, 오디오를 15분으로 자르고, 모든 오디오 세그먼트를 전사한 다음 전사본을 하나로 결합합니다. 전사 출력 요구 사항:
- 형식: Markdown
- 메타데이터: 길이, 파일 크기, 생성 날짜, 설명, 파일 이름, 다루는 주제 등
- 부분: 시작-끝(예: 00:00-00:15), 오디오 청크 이름, 전사 내용, 상태 등
- 전사 형식:
[HH:MM:SS -> HH:MM:SS] 전사 내용 [HH:MM:SS -> HH:MM:SS] 전사 내용 ...