Veo 3 API 튜토리얼: Google 최신 모델로 영화적 영상 생성하기

핵심 수치 3가지:

• 생성 시간: 8초 영상 기준 약 2-4분 (비동기 처리)
• 비용: veo-003 모델 기준 초당 약 $0.35 (8초 영상 = ~$2.80)
• 출력 해상도: 720p, 1080p, 4K 지원 (모델 버전에 따라 다름)

---

Veo 3.1은 Google의 최신 비디오 생성 모델로, 텍스트 프롬프트에서 고화질 영상과 오디오를 동시에 생성한다. Gemini API를 통해 접근하며, 기존 이미지-투-비디오 파이프라인과는 달리 오디오 트랙을 네이티브로 생성한다는 점이 핵심 차이다. 이 튜토리얼은 Python으로 Veo 3 API를 호출하는 전체 과정을 다룬다 — 환경 설정부터 프로덕션 수준의 에러 핸들링까지.

---

목차

1. 사전 요구사항
2. 인증 및 환경 설정
3. 기본 구현: 첫 번째 비디오 생성
4. 프로덕션 구현: 비동기 + 재시도 로직
5. API 파라미터 레퍼런스
6. 에러 핸들링
7. 비용 및 성능 테이블
8. 한계점 및 주의사항

---

1. 사전 요구사항 {#prerequisites}

계정 및 접근 권한

• Google AI Studio 계정: aistudio.google.com 에서 API 키 발급
• Veo 3 접근 권한: 현재 **유료 API 티어(Gemini API Paid tier)**에서만 사용 가능. 무료 티어는 Veo 2까지만 지원
• Python: 3.9 이상

주의: Google AI Studio 무료 플랜에서는 veo-003 모델이 반환되지 않는다. 호출 시 403 PERMISSION_DENIED 에러가 발생한다. 반드시 결제 수단을 연결한 프로젝트에서 API 키를 발급받을 것.

라이브러리 설치

# google-genai는 구버전 google-generativeai와 다른 패키지다
# Veo 3 API는 반드시 google-genai >= 0.8.0 이상 필요
pip install google-genai>=0.8.0

# 환경변수 관리용 (선택사항이지만 권장)
pip install python-dotenv

# 비디오 메타데이터 확인용 (선택사항)
pip install opencv-python

라이브러리 버전 확인:

python -c "import google.genai; print(google.genai.__version__)"
# 출력 예시: 0.8.0 이상이어야 함

---

2. 인증 및 환경 설정 {#authentication}

API 키 설정

.env 파일을 프로젝트 루트에 생성:

# .env 파일
GOOGLE_API_KEY=your_api_key_here

환경 변수를 코드에서 직접 하드코딩하지 않는 이유: API 키가 실수로 git에 커밋되는 것을 방지하기 위함이다.

클라이언트 초기화 검증

import os
from dotenv import load_dotenv
from google import genai

# .env 파일 로드
load_dotenv()

# API 키 유효성 사전 확인
api_key = os.getenv("GOOGLE_API_KEY")
if not api_key:
    raise EnvironmentError("GOOGLE_API_KEY 환경변수가 설정되지 않았습니다.")

# 클라이언트 초기화
# google-genai 패키지는 google.genai 네임스페이스를 사용
client = genai.Client(api_key=api_key)

# 사용 가능한 모델 목록에서 Veo 접근 권한 확인
# 이 호출이 성공하면 인증이 올바르게 된 것
try:
    # 간단한 연결 테스트: 모델 정보 조회
    print("클라이언트 초기화 성공")
    print(f"API 키 앞 8자리: {api_key[:8]}...")
except Exception as e:
    print(f"초기화 실패: {e}")

---

3. 기본 구현: 첫 번째 비디오 생성 {#basic-implementation}

Veo 3 API의 비디오 생성은 비동기(long-running operation) 방식으로 동작한다. 요청을 보내면 즉시 결과가 반환되지 않고, operation ID가 반환되며 이를 폴링해야 한다.

import os
import time
from dotenv import load_dotenv
from google import genai
from google.genai import types

load_dotenv()

client = genai.Client(api_key=os.getenv("GOOGLE_API_KEY"))

def generate_video_basic(prompt: str, output_path: str = "output.mp4") -> str:
    """
    텍스트 프롬프트로 8초 영상을 생성하는 기본 함수.
    
    Args:
        prompt: 영상 설명 텍스트 (영어 프롬프트가 더 나은 결과를 냄)
        output_path: 저장할 파일 경로
    
    Returns:
        저장된 파일 경로
    """
    
    # generate_videos는 즉시 operation 객체를 반환
    # 실제 영상 생성은 백그라운드에서 진행됨
    operation = client.models.generate_videos(
        model="veo-003",  # Veo 3 최신 안정 버전
        prompt=prompt,
        config=types.GenerateVideosConfig(
            # 8초가 현재 지원되는 유일한 길이 (2025년 기준)
            duration_seconds=8,
            # 720p는 처리 속도가 빠르고 비용이 낮음
            # 고품질 결과물이 필요하면 "1080p" 또는 "4k" 사용
            resolution="720p",
            # 오디오 생성 활성화 (Veo 3의 핵심 기능)
            generate_audio=True,
        ),
    )
    
    print(f"Operation 시작됨: {operation.name}")
    print("폴링 시작... (약 2-4분 소요)")
    
    # 완료될 때까지 15초 간격으로 폴링
    # 너무 자주 폴링하면 rate limit에 걸릴 수 있음
    poll_interval = 15  # seconds
    max_wait = 300  # 5분 타임아웃
    elapsed = 0
    
    while not operation.done:
        time.sleep(poll_interval)
        elapsed += poll_interval
        operation = client.operations.get(operation)
        
        print(f"  대기 중... {elapsed}초 경과")
        
        if elapsed >= max_wait:
            raise TimeoutError(f"{max_wait}초 내에 완료되지 않았습니다.")
    
    # 생성 완료 후 결과 처리
    if operation.response and operation.response.generated_videos:
        video = operation.response.generated_videos[0]
        
        # 비디오 데이터를 파일로 저장
        client.files.download(file=video.video)
        video.video.save(output_path)
        
        print(f"영상 저장 완료: {output_path}")
        return output_path
    else:
        raise RuntimeError("영상 생성 완료됐지만 결과가 비어있습니다.")


# 실행 예시
if __name__ == "__main__":
    # 영화적 프롬프트: 카메라 무브먼트와 조명 조건을 명시할수록 결과가 좋음
    prompt = (
        "Cinematic aerial shot of a misty mountain valley at golden hour, "
        "slow push-in camera movement, fog rolling through pine trees, "
        "dramatic volumetric lighting, 4K film grain"
    )
    
    result_path = generate_video_basic(prompt, "mountain_valley.mp4")
    print(f"완료: {result_path}")

---

4. 프로덕션 구현: 비동기 + 재시도 로직 {#production-implementation}

기본 구현은 단일 요청에는 충분하지만, 프로덕션 환경에서는 네트워크 오류, API rate limit, 그리고 여러 영상을 배치로 처리해야 하는 상황을 다뤄야 한다.

import os
import time
import logging
from pathlib import Path
from dataclasses import dataclass
from typing import Optional
from dotenv import load_dotenv
from google import genai
from google.genai import types
from google.api_core import exceptions as google_exceptions

load_dotenv()

# 로깅 설정: 프로덕션에서는 파일 핸들러 추가 권장
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)
logger = logging.getLogger(__name__)


@dataclass
class VideoGenerationConfig:
    """영상 생성 설정을 타입 안전하게 관리하는 dataclass."""
    model: str = "veo-003"
    resolution: str = "720p"
    duration_seconds: int = 8
    generate_audio: bool = True
    # aspect_ratio: "16:9"이 기본값이며 현재 유일하게 안정적으로 지원됨
    aspect_ratio: str = "16:9"
    # 폴링 간격 (초) — 너무 낮으면 429 Too Many Requests 발생
    poll_interval: int = 15
    # 최대 대기 시간 (초)
    max_wait_seconds: int = 360
    # 재시도 횟수 (네트워크 오류 시)
    max_retries: int = 3


class VeoVideoGenerator:
    """
    Veo 3 API 래퍼 클래스.
    재시도 로직, 로깅, 에러 핸들링을 포함한 프로덕션 수준 구현.
    """
    
    def __init__(self, api_key: Optional[str] = None):
        # 명시적으로 전달된 API 키 우선, 없으면 환경변수 사용
        self.api_key = api_key or os.getenv("GOOGLE_API_KEY")
        if not self.api_key:
            raise EnvironmentError("API 키가 없습니다.")
        
        self.client = genai.Client(api_key=self.api_key)
        logger.info("VeoVideoGenerator 초기화 완료")
    
    def generate(
        self,
        prompt: str,
        output_path: str,
        config: Optional[VideoGenerationConfig] = None,
    ) -> str:
        """
        영상을 생성하고 파일로 저장.
        
        Args:
            prompt: 영상 설명 (영어 권장, 300자 이내에서 최적 성능)
            output_path: 저장 경로 (.mp4 확장자)
            config: 생성 설정. None이면 기본값 사용
        
        Returns:
            저장된 파일의 절대 경로
        
        Raises:
            RuntimeError: 생성 실패 시
            TimeoutError: max_wait_seconds 초과 시
        """
        if config is None:
            config = VideoGenerationConfig()
        
        # 출력 디렉토리가 없으면 생성
        output_file = Path(output_path)
        output_file.parent.mkdir(parents=True, exist_ok=True)
        
        # 재시도 로직이 포함된 operation 시작
        operation = self._start_generation_with_retry(prompt, config)
        
        # 완료 대기 및 폴링
        operation = self._wait_for_completion(operation, config)
        
        # 결과 저장
        return self._save_result(operation, output_file, config)
    
    def _start_generation_with_retry(
        self,
        prompt: str,
        config: VideoGenerationConfig,
    ):
        """재시도 로직을 포함한 generation 요청."""
        
        for attempt in range(1, config.max_retries + 1):
            try:
                logger.info(f"영상 생성 요청 시작 (시도 {attempt}/{config.max_retries})")
                logger.info(f"프롬프트: {prompt[:100]}...")
                
                operation = self.client.models.generate_videos(
                    model=config.model,
                    prompt=prompt,
                    config=types.GenerateVideosConfig(
                        duration_seconds=config.duration_seconds,
                        resolution=config.resolution,
                        generate_audio=config.generate_audio,
                        aspect_ratio=config.aspect_ratio,
                    ),
                )
                
                logger.info(f"Operation ID: {operation.name}")
                return operation
            
            except google_exceptions.ResourceExhausted as e:
                # 429: Rate limit 초과
                # 지수 백오프: 60초, 120초, 180초
                wait_time = 60 * attempt
                logger.warning(f"Rate limit 초과. {wait_time}초 후 재시도...")
                time.sleep(wait_time)
            
            except google_exceptions.PermissionDenied as e:
                # 403: 재시도해도 해결 안 됨 — 즉시 실패
                logger.error("권한 없음: 유료 티어인지 확인하세요.")
                raise
            
            except google_exceptions.InvalidArgument as e:
                # 400: 파라미터 오류 — 재시도해도 해결 안 됨
                logger.error(f"잘못된 파라미터: {e}")
                raise
        
        raise RuntimeError(f"{config.max_retries}회 재시도 후에도 요청 실패")
    
    def _wait_for_completion(self, operation, config: VideoGenerationConfig):
        """폴링으로 operation 완료 대기."""
        elapsed = 0
        
        while not operation.done:
            time.sleep(config.poll_interval)
            elapsed += config.poll_interval
            
            try:
                operation = self.client.operations.get(operation)
            except google_exceptions.NotFound:
                # Operation이 만료됐을 때 (매우 드문 케이스)
                raise RuntimeError(f"Operation을 찾을 수 없습니다: {operation.name}")
            
            logger.info(f"생성 중... {elapsed}초 경과 / 최대 {config.max_wait_seconds}초")
            
            if elapsed >= config.max_wait_seconds:
                raise TimeoutError(
                    f"{config.max_wait_seconds}초 타임아웃 초과. "
                    f"Operation: {operation.name}"
                )
        
        # 에러 상태 확인 (완료됐지만 실패한 경우)
        if hasattr(operation, 'error') and operation.error:
            raise RuntimeError(
                f"서버 측 생성 실패: {operation.error.message} "
                f"(코드: {operation.error.code})"
            )
        
        logger.info(f"생성 완료! 총 소요 시간: {elapsed}초")
        return operation
    
    def _save_result(self, operation, output_file: Path, config: VideoGenerationConfig) -> str:
        """생성된 영상을 파일로 저장."""
        
        if not (operation.response and operation.response.generated_videos):
            raise RuntimeError("응답에 영상 데이터가 없습니다.")
        
        video = operation.response.generated_videos[0]
        
        # 파일 다운로드 및 저장
        self.client.files.download(file=video.video)
        video.video.save(str(output_file))
        
        file_size_mb = output_file.stat().st_size / (1024 * 1024)
        logger.info(f"저장 완료: {output_file} ({file_size_mb:.1f} MB)")
        
        return str(output_file.absolute())


# 배치 생성 예시 (여러 영상을 순차 처리)
def batch_generate(prompts: list[dict], output_dir: str = "outputs/") -> list[str]:
    """
    여러 프롬프트를 순차적으로 처리.
    병렬 처리는 rate limit(분당 요청 수)으로 인해 권장하지 않음.
    """
    generator = VeoVideoGenerator()
    results = []
    
    for i, item in enumerate(prompts):
        output_path = f"{output_dir}video_{i:03d}.mp4"
        
        try:
            path = generator.generate(
                prompt=item["prompt"],
                output_path=output_path,
                config=VideoGenerationConfig(
                    resolution=item.get("resolution", "720p"),
                    generate_audio=item.get("audio", True),
                ),
            )
            results.append({"status": "success", "path": path})
        
        except Exception as e:
            logger.error(f"영상 {i} 생성 실패: {e}")
            results.append({"status": "failed", "error": str(e)})
        
        # 요청 간 30초 대기 — rate limit 방지
        if i < len(prompts) - 1:
            logger.info("다음 요청까지 30초 대기...")
            time.sleep(30)
    
    return results


# 실행 예시
if __name__ == "__main__":
    generator = VeoVideoGenerator()
    
    custom_config = VideoGenerationConfig(
        resolution="1080p",       # 더 높은 해상도
        generate_audio=True,      # 네이티브 오디오 포함
        poll_interval=20,         # 20초마다 상태 확인
        max_wait_seconds=480,     # 8분 타임아웃
    )
    
    path = generator.generate(
        prompt=(
            "A lone astronaut walks across a red Martian desert at sunset, "
            "wide-angle lens, dust particles floating in the air, "
            "Interstellar-style cinematography, IMAX quality"
        ),
        output_path="outputs/mars_walk.mp4",
        config=custom_config,
    )
    
    print(f"영상 생성 완료: {path}")

---

5. API 파라미터 레퍼런스 {#api-reference}

GenerateVideosConfig에서 사용할 수 있는 파라미터 전체 목록:

파라미터 이름	타입	기본값	유효 범위	영향
model	str	-	"veo-003", "veo-003-fast"	품질 vs 속도 트레이드오프
duration_seconds	int	8	8 (현재 고정)	영상 길이 (2025년 기준 8초만 지원)
resolution	str	"720p"	"720p", "1080p", "4k"	출력 해상도 및 파일 크기
aspect_ratio	str	"16:9"	"16:9", "9:16"	가로/세로 비율
generate_audio	bool	False	True, False	네이티브 오디오 트랙 포함 여부
number_of_videos	int	1	1–4	한 번에 생성할 영상 수 (비용 x배)
negative_prompt	str	None	자유 텍스트	영상에서 제외할 요소 지정
seed	int	None	0–2147483647	동일 프롬프트로 재현 가능한 결과 생성
image (img2vid)	types.Image	None	PNG/JPEG	이미지를 시작 프레임으로 사용

참고: veo-003-fast는 처리 시간이 약 50% 짧지만 세부 텍스처와 일관성이 다소 낮다. 프로토타이핑에는 fast 버전을 사용하고, 최종 출력에는 veo-003을 권장한다.

---

6. 에러 핸들링 {#error-handling}

Veo 3 API에서 실제로 마주칠 수 있는 에러 코드와 해결 방법:

HTTP 코드	gRPC 코드	에러 메시지 패턴	원인	해결 방법
400	INVALID_ARGUMENT	"Invalid resolution"	지원되지 않는 해상도 값	"720p", "1080p", "4k" 중 하나 사용
400	INVALID_ARGUMENT	"Prompt too long"	프롬프트가 너무 긴 경우	500자 이내로 줄일 것
403	PERMISSION_DENIED	"Veo 3 requires..."	무료 티어 또는 접근 권한 없음	유료 플랜으로 업그레이드
429	RESOURCE_EXHAUSTED	"Quota exceeded"	분당 요청 수 초과	지수 백오프 후 재시도
500	INTERNAL	"Internal server error"	서버 측 처리 실패	30초 후 재시도
503	UNAVAILABLE	"Service unavailable"	일시적 서비스 중단	60초 후 재시도
N/A	N/A	operation.error.code: 7	안전 필터 차단	프롬프트 수정 (폭력, 성인 콘텐츠 제거)
N/A	N/A	operation.error.code: 3	생성 자체 실패	프롬프트 단순화 후 재시도

안전 필터 에러 핸들링 예시

def handle_safety_filter(prompt: str, generator: VeoVideoGenerator) -> Optional[str]:
    """
    안전 필터에 걸렸을 때 프롬프트를 자동으로 수정하는 패턴.
    완벽하지 않지만 흔한 케이스를 처리함.
    """
    
    # 안전 필터를 자주 트리거하는 단어 목록 (실무에서 확인된 것들)
    risky_terms = ["blood", "weapon", "fight", "explosion", "nude", "violent"]
    
    cleaned_prompt = prompt
    filtered_terms = []
    
    for term in risky_terms:
        if term.lower() in prompt.lower():
            cleaned_prompt = cleaned_prompt.replace(term, "")
            filtered_terms.append(term)
    
    if filtered_terms:
        logging.warning(f"제거된 단어들: {filtered_terms}")
        logging.info(f"수정된 프롬프트: {cleaned_prompt[:100]}...")
    
    try:
        return generator.generate(
            prompt=cleaned_prompt.strip(),
            output_path="filtered_output.mp4"
        )
    except Exception as e:
        logging.error(f"필터 후에도 실패: {e}")
        return None

---

7. 비용 및 성능 테이블 {#cost-performance}

Google AI for Developers 공식 문서 기준 (2025년 7월 기준):

모델	해상도	오디오	예상 처리 시간	비용 (8초 영상)	파일 크기 (8초)
veo-003	720p	미포함	2-3분	~$2.10	~15-25 MB
veo-003	720p	포함	2-4분	~$2.80	~20-30 MB
veo-003	1080p	미포함	3-5분	~$4.20	~40-60 MB
veo-003	1080p	포함	3-6분	~$4.90	~50-70 MB
veo-003	4K	미포함	5-8분	~$8.40	~120-180 MB
veo-003-fast	720p	미포함	1-2분	~$1.05	~15-25 MB

비용 계산 기준: Google 공식 가격표상 $0.35/second이며, 오디오 생성은 추가 비용이 발생한다. 정확한 현재 가격은 Google AI Studio Pricing 페이지에서 확인할 것.

실용적인 비용 최적화 전략:

1. 프로토타이핑: veo-003-fast + 720p 조합으로 아이디어 검증 → 비용 62% 절감
2. 배치 최소화: number_of_videos=4는 4배 비용이 들지만 API 오버헤드는 1회 — 여러 변형이 필요할 때만 사용
3. seed 파라미터 활용: 마음에 드는 결과를 재현할 때 동일 seed로 동일 결과 → 실험 비용 절감

---

8. 한계점 및 주의사항 {#limitations}

현재 기술적 한계 (2025년 7월 기준)

• 고정된 영상 길이: 8초만 지원. 더 긴 영상이 필요하면 여러 클립을 생성 후 편집 툴로 연결해야 한다
• 텍스트 렌더링: 영상 내 텍스트(간판, 자막 등)의 정확도가 낮다. 로고나 레이블이 포함된 장면에서는 결과물을 반드시 검토해야 한다
• 프롬프트 언어: 한국어 프롬프트도 처리되지만, 영어 프롬프트 대비 일관성이 떨어지는 경우가 있다. 영화적 결과물이 목표라면 영어 사용 권장
• 카메라 제어의 한계: “dolly zoom” 같은 구체적인 기법은 텍스트로 표현 가능하지만 정확한 카메라 경로는 제어 불가
• 일관된 캐릭터: 동일 캐릭터가 여러 클립에 걸쳐 외모를 유지하는 것은 현재 지원되지 않음 (이미지-투-비디오로 일부 보완 가능)
• 지역 제한: 일부 국가에서는 API 접근이 제한될 수 있음

언제 Veo 3를 쓰지 말아야 하는가

시나리오	이유	대안
정밀한 타이밍이 필요한 광고	8초 고정, 특정 컷 포인트 제어 불가	Runway Gen-3, Kling
반복 캐릭터가 등장하는 시리즈	일관된 외모 유지 불가	Pika 2.2 (character consistency)
초저예산 (월 $10 이하)	8초 영상 하나에 ~$2.80	Minimax Video (저비용)
실시간 생성이 필요한 앱	최소 2분 처리 시간	사전 생성 + 캐싱 아키텍처

---

결론

Veo 3 API는 veo-003 모델, GenerateVideosConfig, 그리고 폴링 기반 비동기 패턴으로 구성된다. 유료 티어 API 키, google-genai>=0.8.0, 그리고 이 글의 프로덕션 코드 블록 하나면 오늘 바로 동작하는 파이프라인을 만들 수 있다. 비용은 720p 기준 영상당 약 $2.80이므로, 대량 배치 처리 전에 반드시 veo-003-fast로 프롬프트를 검증할 것.

참고: 여러 AI 모델을 하나의 파이프라인에서 사용한다면, AtlasCloud는 Kling, Flux, Seedance, Claude, GPT 등 300개 이상의 모델에 단일 API로 접근할 수 있습니다. API 키 하나로 모든 모델 사용 가능. 신규 사용자는 첫 충전 시 25% 보너스(최대 $100).