AI 멀티모달 (AI Multimodal)
Google Gemini의 멀티모달 API를 사용하여 오디오, 이미지, 비디오, 문서를 처리하고 이미지/비디오를 생성합니다.
설정 (Setup)
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플래그로 순환 이벤트 기록- 이전 버전 호환: 단일 키도 정상 작동
빠른 시작 (Quick Start)
설정 확인: python scripts/check_setup.py
미디어 분석: python scripts/gemini_batch_process.py --files <파일> --task <analyze|transcribe|extract>
- 팁: 이미지를 분석하라는 요청을 받으면,
gemini명령어가 사용 가능한지 확인합니다. 가능하다면echo "<이미지 분석 프롬프트>" | gemini -y -m <gemini.model>명령어를 사용합니다 (모델은.claude/.ck.json파일의gemini.model에서 읽습니다).gemini명령어를 사용할 수 없으면python scripts/gemini_batch_process.py --files <파일> --task analyze명령어를 사용합니다. 콘텐츠 생성:python scripts/gemini_batch_process.py --task <generate|generate-video> --prompt "설명"
표준 입력 지원: 파일을 표준 입력(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(전통적인 방식)
모델 (Models)
- 이미지 생성:
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(고급)
스크립트 (Scripts)
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)
자세한 가이드는 다음 파일을 참조하세요:
| 주제 | 파일 | 설명 |
|---|---|---|
| 음악 | references/music-generation.md | 배경 음악 생성을 위한 Lyria RealTime API, 스타일 프롬프트, 실시간 제어, 비디오 제작 통합 |
| 오디오 | references/audio-processing.md | 오디오 형식 및 제한, 전사(타임스탬프, 화자, 세그먼트), 비음성 분석, File API 대 인라인 입력, 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 모델 매트릭스, 텍스트-투-비디오 및 이미지-투-비디오 빠른 시작, 다중 참조 및 확장 흐름, 카메라 및 타이밍 제어, 구성(해상도, 종횡비, 오디오, 안전), 프롬프트 디자인 패턴, 성능 팁, 제한 사항, 문제 해결, 비용 추정 |
제한 사항 (Limits)
형식: 오디오 (WAV/MP3/AAC, 9.5시간), 이미지 (PNG/JPEG/WEBP, 3.6k장), 비디오 (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] 전사 내용 ...