AI 기술 설명 – 에이전틱 영상 이해(Agentic Video Understanding) – 긴 영상에서 필요한 구간만 골라 보는 Gemini 기능
에이전틱 영상 이해(Agentic Video Understanding)는 Gemini API에서 영상 파트에 "processing": "agentic" 한 줄을 넣으면 모델이 영상 전체를 한 번에 읽지 않고 필요한 구간만 골라 보는 기능입니다. 영상 이해 문서는 모델이 영상 타임라인을 직접 탐색하면서 자막(트랜스크립트)을 골라 훑고, 프레임 속도와 해상도를 질문에 맞춰 그때그때 조정한다고 설명해요.
기본값은 정적 처리(Static Processing)입니다. 영상을 1초에 한 프레임씩 뽑아 컨텍스트 윈도우(Context Window)에 한꺼번에 넣는 방식이라 짧은 영상에는 잘 맞지만, 긴 영상이면 그만큼 토큰이 쌓이죠. 구글 문서에 따르면 에이전틱 처리는 긴 영상에서 토큰을 최대 88% 덜 쓰고 품질은 약 7% 높다고 하는데, 이 숫자가 어떤 조건에서 나왔는지는 아래에서 따로 짚겠습니다.
에이전틱 영상 이해는 정적 처리와 무엇이 다른가
문서는 두 방식을 표로 나눠 둡니다. 정적 처리는 모든 Gemini 모델에서 되는 기본값이고, 에이전틱 처리는 특정 모델에서만 됩니다. 문서가 권하는 쓰임새도 갈려요. 긴 영상이나 특정 순간을 묻는 질문은 에이전틱, 5분 미만 짧은 영상에서 지연이 중요하거나 클립 전체의 프레임 단위 정밀도가 필요하면 정적입니다.
문서는 일반 지침으로 “에이전틱 모드로 시작하라”고 적습니다. 응답 품질이나 토큰 효율을 최적화하려는 경우에 특히 그렇다는 단서가 붙어요.
영상을 넣는 방법과 에이전틱 영상 이해의 위치
영상을 Gemini에 주는 방법은 문서에 네 가지로 정리돼 있습니다. File API는 유료 20GB(무료 2GB)까지이고 100MB 이상이거나 10분 넘는 영상, 다시 쓸 파일에 권장돼요. 클라우드 스토리지 등록은 파일당 2GB, 인라인 데이터는 100MB 미만이며 1분 이내의 짧은 일회성 입력용입니다. 마지막은 공개 YouTube URL입니다. 문서는 대부분의 경우 File API를 권한다고 적고, 요청 전체(파일과 프롬프트 등) 크기가 20MB를 넘거나 같은 영상을 여러 프롬프트에 쓰려면 File API를 꼭 쓰라고 안내해요.
에이전틱 영상 이해는 이 입력 방식과 별개로 영상 파트에 붙는 처리 옵션입니다. 문서는 File API 안내 바로 아래에서 토큰 효율과 성능을 최적화하려면 에이전틱 처리를 고려하라고 한 번 더 짚어 줘요. 이 글에서는 컨텍스트 엔지니어링 글에서 다룬 “읽는 양을 설계한다”는 문제를 영상에 적용한 기능으로 읽었는데, 이 연결은 문서가 한 말이 아니라 제 해석입니다.
컨텍스트 엔지니어링 – AI가 읽는 양을 설계하는 방법에이전틱 영상 이해를 켜는 설정은 영상 파트의 한 줄
켜는 방법은 input 배열에 들어가는 영상 파트에 "processing": "agentic"을 더하는 것입니다. 문서의 Python 예제는 강의 영상을 File API로 올리고, gemini-3.8-flash에 “발표된 세 가지 주요 논거가 무엇인가”를 묻는 형태예요.
예제는 background=True로 서버에서 비동기 실행하고, 상태가 in_progress인 동안 5초 간격으로 조회합니다. 에이전트 쪽에서 영상을 여러 번 살펴보느라 긴 영상은 시간이 더 걸릴 수 있어서예요. 짧은 영상이라면 background를 빼고 동기로 불러도 된다고 문서가 적었습니다. 영상 파일은 File API 외에 인라인 데이터나 클라우드 스토리지 등록으로도 줄 수 있지만, 에이전틱 예제는 File API로 올린 파일을 씁니다.
한 요청에 영상이 여러 개면 영상마다 방식을 다르게 줄 수도 있습니다. 문서의 예제는 한 영상에 "agentic", 다른 영상에 "static"을 넣어요. 영상 속 시점을 프롬프트에 적을 때는 01:15처럼 MM:SS 형식을 쓰라고 문서가 안내합니다.
응답에서 모델이 어디를 봤는지 확인하기
에이전틱 처리가 실제로 쓰였는지는 interaction.steps에서 확인합니다. 문서에 따르면 processing_call과 processing_result 단계가 있으면 모델이 영상을 동적으로 탐색했다는 뜻이에요. 전자는 모델이 영상 구간이나 오디오 트랜스크립트를 요청한 것(id로 식별)이고, 후자는 그 요청의 결과로 call_id로 이어집니다.
문서의 응답 예시에서는 생각 요약(thought) 사이사이에 이 단계가 두 쌍 들어가 있고 마지막에 model_output이 옵니다. 첫 요청은 자막을 살펴 주요 주제를 찾고, 두 번째는 시각 프레임을 불러 슬라이드 내용을 확인하는 식이에요. 문서는 이 단계를 UI의 진행 표시에 쓸 수 있고 응답으로 되돌려 줄 필요는 없다고 적습니다.
후속 질문에서 영상 맥락 유지
previous_interaction_id를 쓰는 상태 유지 방식에서는 서버가 영상 맥락을 들고 있어 따로 할 일이 없습니다. 상태를 저장하지 않는 step_list 방식은 응답에 들어온 processing_call과 processing_result가 영상 맥락을 담고 있어서, 다음 요청의 step_list에 그 단계를 전부 넣어야 해요. 빼도 지금은 API 오류가 나지 않지만 영상 맥락이 사라져 후속 질문의 품질이 크게 떨어진다고 문서가 경고합니다. 되돌려 보낸 단계는 입력 토큰으로 계산됩니다.
에이전틱 영상 이해의 수치와 지원 모델
지원 모델은 영상 이해 문서에 Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite로 적혀 있습니다. 2026년 9월 1일 변경 기록은 이 기능이 나왔다는 항목에서 Gemini 3.7 Flash, 3.6 Flash, 3.5 Flash-Lite를 적고 Interactions API와 GenerateContent API 양쪽이라고 밝혀요. 3.8 Flash가 변경 기록 문장에는 없어서, 나중에 더해진 것인지 단순 누락인지는 제가 가진 자료로는 알 수 없습니다. 이 글에서 읽은 예제는 모두 Interactions API 형식이었어요.
이 수치는 모두 구글 문서가 스스로 적은 것입니다. 이 문서에는 어떤 영상을 몇 건 대상으로, 어떤 지표로 쟀는지가 없고 “긴 영상”이 몇 분 이상인지도 정해 두지 않았어요. “최대”라는 표현이 붙어 있으니 내 영상에서도 그만큼 줄어든다는 뜻으로 읽을 수 없고, 직접 돌려 본 결과는 이 글에 없습니다.
토큰 계산 방식은 문서에 이렇게 나뉩니다.
| 방식 | 토큰이 세어지는 방법 | 문서의 수치 |
|---|---|---|
| 정적 처리 | 프레임(1초에 한 장)과 오디오를 영상 길이 초 단위로 계산 | 기본 해상도에서 초당 약 100토큰, 높은 해상도에서 약 300토큰 |
| 에이전틱 처리 | 탐색에 쓴 추론 토큰은 생각 토큰, 불러온 프레임·오디오·자막은 도구 사용 토큰 | 영상 내용과 탐색 방식에 따라 달라짐 |
정적 처리 쪽 숫자를 단순히 곱하면 1시간 영상이 기본 해상도에서 36만 토큰 안팎이 됩니다. 이 곱셈은 문서의 수치로 제가 계산한 것이고, 문서가 제시한 예시는 아니에요.
에이전틱 영상 이해를 쓰기 전에 알아둘 제한과 주의점
문서에 적힌 주의
- 클리핑 구간(
start_offset,end_offset)과 사용자 지정 프레임 속도(fps)는 정적 처리에서만 지원된다 - 5분 미만 짧은 영상에서는 내부 추론과 도구 왕복 때문에 첫 토큰 시간이 조금 늘 수 있다
- 오래 걸리는 요청을 동기·비스트리밍으로 보내면 연결이나 인증 유효 시간을 넘겨 401 또는 시간 초과 오류가 날 수 있다
- 후속 질문에서
step_list방식은 반환된 단계를 모두 다시 보내야 한다
시간이 오래 걸리는 영상은 스트리밍(stream=True)이나 백그라운드 실행(Background Execution, background=True)을 쓰라는 것이 문서의 안내입니다. 연결을 유지하고 중간 추론 단계를 보여 주기 때문이래요. 한 요청에 텍스트와 영상 하나를 같이 넣을 때는 텍스트 프롬프트를 영상 파트 뒤에 두라는 안내도 있습니다. media_resolution과 processing은 서로 독립이라 한 영상 입력에 둘 다 줄 수 있어요.
공식 문서에서 에이전틱 영상 이해에 요금을 따로 적은 곳은 찾지 못했습니다. 프리뷰 표시는 같은 문서의 YouTube URL 항목에만 붙어 있고(“프리뷰이며 무료이지만 가격과 한도는 바뀔 수 있다”), 에이전틱 처리 절에는 프리뷰 표기가 없어요. 다만 이 기능을 YouTube URL과 함께 쓸 수 있는지는 문서에 명시돼 있지 않아서 확인하지 못했습니다. 지원 영상 형식은 MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP이고, 1M 컨텍스트 모델은 기본(낮은 미디어 해상도)에서 최대 3시간, 높은 해상도에서 최대 1시간 영상을 처리한다고 적혀 있습니다.
이 글에서 읽은 범위
읽은 것은 영상 이해 문서 전체와 변경 기록의 9월 1일 항목입니다. 문서가 링크한 토큰 문서(tokens guide)와 백그라운드 실행 문서는 읽지 않았고, 직접 영상을 올려 돌려 본 결과도 없어서 문서가 약속한 동작을 정리한 글로 읽어 주세요. 카드 속 요청 형식과 응답 단계는 문서 예제에서 옮긴 것이지 제가 실행한 출력이 아닙니다.
참고한 공식 문서
본문은 Gemini API 영상 이해 문서와 Gemini API 변경 기록을 읽고 정리했습니다. 기능과 지원 모델이 바뀔 수 있으니 쓰기 전에 원문을 확인하세요.
에이전틱 영상 이해 자주 묻는 질문
에이전틱 영상 이해는 어떻게 켜나요?
input 배열의 영상 파트에 “processing”: “agentic”을 넣으면 됩니다. 공식 문서는 이 값을 넣지 않으면 기본인 정적 처리, 곧 1초에 한 프레임씩 뽑아 한 번에 컨텍스트에 넣는 방식이 쓰인다고 설명합니다.
어떤 모델에서 쓸 수 있나요?
영상 이해 문서는 Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite를 지원 모델로 적습니다. 2026년 9월 1일 변경 기록은 3.7 Flash, 3.6 Flash, 3.5 Flash-Lite만 적고 있어서 두 문서의 표기가 다릅니다.
짧은 영상에도 에이전틱 처리가 낫나요?
문서는 5분 미만의 짧은 영상에서는 내부 추론과 도구 왕복 때문에 첫 토큰이 나오기까지 시간이 조금 늘 수 있다고 적습니다. 지연에 민감한 짧은 영상이나 모든 프레임이 필요한 경우에는 정적 처리를 고르라는 것이 문서의 안내입니다.
글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.
이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.
