Gemini Agentic Video Understanding API 가이드

2시간짜리 강의 영상과 20초짜리 제품 클립을 같은 방식으로 분석할 필요는 없습니다. 긴 영상에서 특정 장면을 찾아야 하거나 특정 순간을 다시 확인해야 한다면 Gemini의 agentic video understanding 모드가 더 적합한 출발점입니다. 다만 Google이 말하는 ‘최대’ 절감 효과는 벤치마크 기준일 뿐, 모든 API 청구액이 66% 줄어든다는 뜻은 아닙니다.

영상 길이보다 분석 작업을 기준으로 모드 선택하기

Gemini agentic video understanding은 특정 시점을 찾거나 다시 살펴봐야 하는 질문에 잘 맞습니다. 반대로 짧은 클립에서 빠른 응답이 중요하거나, 샘플링 구간 전체를 일정하게 훑어야 한다면 static processing이 더 단순한 선택입니다.

Google은 출시 시점에 네 가지 활용 사례를 제시했습니다. 1초 미만 단위의 순간 검색, 긴 영상에서의 ‘건초더미 속 바늘’ 찾기, 이상 탐지, 동작이나 객체 수 세기입니다. 공식 발표에는 10분짜리 사용법 영상부터 90분 강의, 수 시간 분량의 녹화물까지 다양한 예시가 소개됩니다.

공개된 영상 길이 기준선은 없습니다. 5분 영상이라도 숨겨진 이벤트 하나를 찾아야 한다면 agentic processing이 타당할 수 있고, 더 긴 영상이라도 내용이 균일하다면 그렇지 않을 수 있습니다.

기능은 하나지만 API 요청 형식은 두 가지

‘Agentic’은 어디서나 같은 JSON 필드 하나로 켜는 옵션이 아닙니다. Google의 출시 예시는 Interactions API를 사용하며, 비디오 입력 안에 processing: "agentic"을 넣습니다. GenerateContent에서는 미디어 파트에서 처리 방식을 지정합니다.

Interactions API: 비디오 입력에 processing 지정

Google의 출시 글은 YouTube 영상을 대상으로 다음과 같은 Python 패턴을 제시합니다.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

이 설정은 관계없는 최상위 필드가 아니라 비디오 객체에 넣어야 합니다.

GenerateContent: 미디어 파트에 media processing 지정

Gemini video-understanding 문서는 GenerateContent 형식을 별도로 설명합니다. 이 요청 형식에서 미디어 입력은 media_processing: "AGENTIC"을 사용하며, JavaScript에서는 이에 대응하는 camelCase 속성인 mediaProcessing을 사용합니다.

최소한의 Python 예시는 다음과 같습니다.

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

로컬 영상을 쓴다면 YOUR_VIDEO_FILE_URI 자리에 Gemini 파일 업로드 과정에서 반환된 URI를 넣고, 미디어 파트를 전송하기 전에 파일 준비가 끝날 때까지 기다려야 합니다. 설치한 클라이언트 버전에 맞는 SDK 세부 사항은 최신 공식 video-understanding 가이드에서 확인하세요.

client.interactions.create에서 generateContent로 옮길 때 두 코드 조각을 서로 바꿔 쓰면 안 됩니다.

Agentic video understanding은 실제로 어떻게 동작하나

Static video processing은 고정된 프레임 레이트로 영상을 샘플링합니다. Google에 따르면 기본값은 초당 1프레임이며, API를 통해 비율을 조정할 수 있습니다. 이후 모델은 이렇게 샘플링된 프레임을 분석합니다.

반면 agentic 워크플로는 Gemini가 타임라인을 검색하고 훑으면서 적절한 속도를 고르고, 녹화 전체를 균일하게 불러오는 대신 시각 프레임·오디오·트랜스크립트를 활용하도록 합니다.

1. 질문과 관련된 구간 또는 모달리티를 요청합니다.
2. 반환된 프레임, 오디오 또는 트랜스크립트를 살펴봅니다.
3. 더 정밀한 시간 정보가 필요하면 좁은 구간을 다시 확인합니다.

Static sampling은 개발자가 적용 범위를 명확하게 정할 수 있습니다. Agentic processing은 어디를 봐야 할지에 대한 판단을 모델에 더 많이 맡기므로, 프로덕션 환경에서는 대표 영상으로 타임스탬프와 개수의 정확성을 검증해야 합니다.

‘최대 66% 절감’은 66% 할인이라는 뜻이 아니다

Google은 표준 영상 분석 벤치마크에서 다음과 같은 결과를 보고했으며, 특히 긴 영상에서 큰 개선 폭을 강조했습니다.

Google의 출시 발표에 따르면 agentic video understanding에는 표준 Gemini API 토큰 가격이 적용되며, 기능 자체에 대한 별도 요금은 없습니다. 실제 비용은 모델, 가져온 콘텐츠, 요청 내용, 출력에 따라 달라집니다. 토큰과 모델 가격을 더 폭넓게 살펴보려면 Gemini 3.7 Flash API 가격 가이드를 참고하세요.

같은 영상에 반복해서 질문한다면, API 워크플로가 지원하는 경우 영상 컨텍스트를 캐시하세요. Google Cloud의 실무 영상 분석 노트는 반복 분석에서 컨텍스트 캐싱을 중요한 비용 절감 수단으로 꼽습니다.

지원 범위와 출시 현황

Agentic video understanding은 별도로 발표된 비디오 모델이 아니라 세 가지 Flash 계열 모델에서 제공되는 처리 기능입니다. Google은 이 기능이 2026년 9월 1일 아래 모델과 환경에서 출시됐다고 설명합니다.

소비자용 Gemini와 YouTube 관련 출시는 계획 단계이므로, 모든 계정에서 현재 사용할 수 있다는 근거는 아닙니다.

기본 모드 전환 전, 4가지 프로덕션 테스트

출시 발표는 기능상의 주장을 제시하지만, 특정 영상에서 이 모드가 어떻게 동작하는지까지 알려주지는 않습니다. 기존 static 워크플로를 대체하기 전에는 작은 평가 세트로 검증해 보세요.

1. 타임스탬프 검색: 장면 전환, 짧은 등장 구간, 정확한 시작·종료 시점이 중요한 이벤트가 포함된 클립을 준비합니다. 반환된 타임스탬프를 사람이 검수한 기준값과 비교하세요.
2. 빠른 동작 수 세기: 반복 동작이나 화면을 가로지르는 객체가 있는 영상을 사용합니다. 총개수와 함께 답변이 집계 구간을 설명하는지도 확인하세요.
3. 오디오·트랜스크립트 근거 확인: 말로 전달되는 내용과 화면 속 행동이 다른 질문을 던져 보세요. 답변이 한 모달리티를 다른 모달리티로 조용히 대체하지 않는지 검증해야 합니다.
4. 운영 특성: 같은 파일을 두 모드로 실행하고 입력·출력 토큰, 실제 경과 시간 지연, 재시도, 빈 응답, 놓친 이벤트, static fallback 결과를 기록하세요. 선택적 검색이 근거를 놓치거나 허용하기 어려운 지연을 더한다면 fallback을 유지해야 합니다.

출시 글만 보고 ‘X분 이상이면 agentic을 사용한다’는 고정 규칙을 만들지는 마세요. 공개된 자료는 보편적인 영상 길이 임계값이 아니라 작업 기준의 선택을 뒷받침합니다.

Gemini agentic video understanding API FAQ

Agentic video understanding은 새로운 Gemini 모델인가요?

아니요. Google은 이를 Gemini 3.7 Flash, Gemini 3.6 Flash, Gemini 3.5 Flash-Lite에서 제공되는 영상 이해 기능으로 소개합니다.

YouTube URL 대신 업로드한 영상을 쓸 수 있나요?

네. Google은 업로드한 비디오 파일과 YouTube 동영상을 지원 API 입력으로 명시합니다. 로컬 파일은 먼저 업로드한 뒤 처리가 완료되면 반환된 파일 URI를 미디어 파트에 전달하면 됩니다.

Agentic video processing에는 추가 요금이 있나요?

Google은 별도 기능 요금이 없다고 밝힙니다. 일반 Gemini API 토큰 가격이 적용되며, 최종 비용은 가져온 콘텐츠와 나머지 요청 구성에 따라 달라집니다.

대표성 있는 영상 세트를 두 모드로 모두 실행해 본 뒤, 측정된 근거 품질과 토큰 비용이 애플리케이션 목표에 맞는 경우에만 agentic processing을 기본값으로 유지하세요.