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 "<image 분석 프롬프트>" | gemini -y -m <gemini.model>명령어를 사용하세요 (모델은.opencode/.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로 스트리밍하고, 구조화된 결과(텍스트/JSON/CSV/markdown 및 생성된 에셋)를 저장합니다. Imagen 4 및 Veo 워크플로우에 사용됩니다.media_optimizer.py: ffmpeg/Pillow 기반 사전 점검 도구로, 오디오, 이미지, 비디오 입력을 압축/크기 조정/변환하고, 대상 크기/비트레이트를 적용하며, 긴 클립을 1시간 단위로 분할하고, 디렉토리 단위로 일괄 처리하여 미디어가 Gemini 제한 내에 있도록 합니다.document_converter.py: Gemini 기반 변환기로 PDF/이미지/Office 문서를 업로드하고, 마크다운 보존 프롬프트를 적용하며, 여러 파일을 일괄 처리하고,docs/assets아래에 자동으로 이름을 지정하여 출력합니다. 모델, 프롬프트, 자동 파일명 지정, 상세 로깅을 위한 CLI 플래그를 제공합니다.check_setup.py: 대화형 준비 상태 확인 도구로, 디렉토리 구조, 중앙 집중식 환경 변수 확인, 필수 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와 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,600개), 비디오 (MP4/MOV, 6시간), PDF (1,000페이지) 크기: 인라인 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] 변환 내용 ...