먼저 읽으십시오: 동영상은 Base64 inline(전체 요청 ≤ 20 MB) 또는 YouTube 링크(Gemini 기본 형식)로만 전달할 수 있습니다. 일반 공개 동영상 URL(예:
https://example.com/demo.mp4)을 전달하면 Request contains an invalid argument가 반환됩니다 —— 이는 APIYI 차단이 아니라 Google이 직접 링크를 거부하는 것입니다. 아래의 “Video input methods”를 참조하십시오.시각적 API 테스트
동영상을 업로드하고 iCover 시각적 테스트 도구에서 이해 엔드포인트를 테스트하십시오.
지원 모델
안정적인 클래식인
gemini-2.5-pro(2M 컨텍스트)와 gemini-2.5-flash는 여전히 사용할 수 있습니다. 전체 과금은 모델 및 과금을 참조하십시오.
동영상 입력 방식
대부분의 문제는 여기서 발생합니다. 아래 표를 확인하여 입력 방식이 지원되는지 확인하십시오:빠른 시작: Base64 인라인 (OpenAI 호환 형식)
가장 일반적인 방법은 로컬 동영상을 읽어 → base64로 인코딩한 다음 →image_url 필드에 전달하는 것입니다.
<BASE64_VIDEO>을 동영상의 base64 문자열로 바꾸십시오. 큰 파일의 경우에는 SDK가 자동으로 인코딩하도록 두는 편이 좋습니다):
YouTube 링크(Gemini 네이티브 형식)
YouTube 링크는 다운로드가 필요 없고 20 MB 제한의 적용을 받지 않지만, Gemini 네이티브 형식으로만 전달할 수 있습니다(google-genai SDK, 엔드포인트 https://api.apiyi.com).
더 많은 네이티브 형식 사용법(스트리밍, 추론 예산, 함수 호출 등)은 Gemini Native Format을 참조하십시오.
고급 팁
타임스탬프 참조
모델은 기본적으로 초당 1프레임으로 샘플링하며 오디오 트랙도 이해하므로, prompt에서MM:SS로 순간을 직접 참조할 수 있습니다. 이는 순수한 프롬프팅 기법이며 모든 입력 방식에서 작동합니다:
일반적인 작업을 위한 프롬프팅 아이디어
동일한 동영상은 prompt만 바꾸면 서로 다른 분석을 지원하므로 코드 변경이 필요하지 않습니다:- 콘텐츠 요약: 주제, 핵심 순간, 결론을 3~5문장으로 요약합니다
- 교육적 분석: 핵심 개념, 장별 분해, 중요한 타임스탬프를 추출합니다
- 감시 분석: 비정상적인 행동, 존재하는 사람/객체, 그리고 발생 시점을 식별합니다
- 마케팅 검토: 판매 포인트가 어떻게 제시되는지, 페이싱, 타깃 청중과의 적합성을 분석합니다
- 동작 분석: 동작 단계, 자세 세부사항, 개선할 지점을 분해합니다
기술 노트
- 샘플링 속도: 기본적으로 모델은 초당 1프레임(FPS) 으로 샘플링하며 오디오 트랙도 이해합니다.
- 토큰 사용량: 기본 해상도에서는 대략 초당 300 tokens 정도이며, 저해상도에서는 대략 초당 100 tokens 정도입니다. 동영상이 길수록 더 많은 tokens가 사용되므로 이에 맞춰 예상해야 합니다.
- 지원 형식: mp4, mpeg, mov (quicktime), avi, webm, wmv, 3gpp 및 기타 일반적인 형식을 지원합니다.
FAQ
공개 비디오 링크가 Request contains an invalid argument / fails to fetch를 반환합니다
공개 비디오 링크가 Request contains an invalid argument / fails to fetch를 반환합니다
Google의 video understanding은 임의의 공개 직링크를 허용하지 않으며(예:
https://example.com/video.mp4) Request contains an invalid argument를 반환합니다. 이는 APIYI 또는 Nginx 차단이 아닙니다. 다음 중 하나를 사용하십시오: ① Base64 인라인(≤20 MB); 또는 ② YouTube 링크(네이티브 형식).왜 20 MB 제한이 있습니까? 예전에는 작동했습니다
왜 20 MB 제한이 있습니까? 예전에는 작동했습니다
Base64 인라인의 경우 전체 요청 본문은 항상 20 MB로 제한되어 있었습니다(Google의 공식 제한과 동일합니다). “예전에는 작동했다”는 것이 공개 직링크를 뜻한다면, 그것은 애초에 지원되는 방식이 아니었습니다. 일부 경우에는 우연히 오류가 나지 않았을 뿐이며, 이제는 사양에 따라 거부됩니다.
files.upload를 사용하여 대용량 비디오를 업로드할 수 있습니까?
files.upload를 사용하여 대용량 비디오를 업로드할 수 있습니까?
아닙니다. Google의 공식 Files API(
client.files.upload())는 서드파티에서 지원되지 않습니다. Google 자체 엔드포인트에서만 지원됩니다. 대용량 비디오는 YouTube 링크를 사용하거나, 20 MB 이하로 압축한 뒤 Base64를 사용하십시오.20 MB를 초과하는 비디오는 어떻게 합니까?
20 MB를 초과하는 비디오는 어떻게 합니까?
두 가지 방법이 있습니다: ① YouTube에 업로드한 뒤 링크를 전달합니다(네이티브 형식이며 20 MB 제한의 적용을 받지 않음); ② ffmpeg 같은 도구를 사용해 로컬에서 핵심 구간을 20 MB 이하로 압축하거나 잘라낸 뒤 base64로 인코딩합니다.
관련 자료
모델 및 요금
모든 Gemini 모델과 최신 요금을 살펴보세요
Gemini 네이티브 형식
YouTube 링크, 스트리밍, 추론 예산 및 기타 네이티브 사용법
Vision 이해 API
이미지 콘텐츠 인식 및 멀티모달 분석
API 레퍼런스
전체 API 사양 및 엔드포인트 상세 정보