- 범용 형식은
video_url입니다:{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,..."}}형식은 Seed, Qwen, Kimi, MiniMax 및 Gemini에서 작동합니다. 이 페이지의 이전 버전에 안내되었던 기존image_url+data:video/mp4형식은 Gemini에서만 작동하며, 그 외 다른 모든 모델에서는 400을 반환합니다. - GPT, Grok, Claude, GLM 및 DeepSeek는 동영상 입력을 지원하지 않습니다. GPT와 GLM은 동영상을 자동으로 제외한 채 200을 반환하며, GPT는 그럴듯한 답변을 지어낼 수도 있습니다 — “동영상을 지원하지 않는 모델”을 참조하십시오.
- Gemini는 일반 공개 동영상 URL을 직접 지원하지 않습니다:
Request contains an invalid argument을 반환하거나, 동영상이 자동으로 제외된 채(prompt_tokens가 수십 개에 불과함) 200을 반환하여 동영상을 볼 수 없다고 답변하거나 검은 화면으로 묘사할 수 있습니다. 반면 Seed, Qwen, Kimi는 공개 https URL을 직접 수신할 수 있습니다.
시각적 API 테스트
AI 에이전트로 연동 구현하기
이 prompt를 복사하여 Codex / Claude Code / Cursor에 붙여넣으십시오
먼저 이 페이지의 일반 텍스트 버전을 가져온 다음(모든 문서 URL 끝에 .md 추가), 프로젝트 고유의 기술 스택으로 코드를 작성합니다. 범용 video_url 형식, Gemini의 공개 URL 불가 규칙 및 20 MB 제한, 비디오가 실제로 모델에 도달했는지 확인하기 위한 prompt_tokens 검사 등이 이미 요구사항에 반영되어 있습니다.
이 프로젝트의 비디오 이해 기능을 연동/트러블슈팅하십시오: 요약, 장면 설명, 동작 분석 또는 타임스탬프 참조를 위해 멀티모달 모델에 비디오를 전송합니다.
코드를 수정하기 전에 문서를 읽으십시오: 이 페이지의 일반 텍스트 버전을 확인하려면 https://docs.apiyi.com/en/api-capabilities/video-understanding.md 를 가져오십시오. YouTube 링크의 경우 gemini/native 페 … 도 읽으십시오.
- 엔드포인트 및 형식: OpenAI 호환
POST https://api.apiyi.com/v1/chat/completions을(를) 사용하고 항상 비디오를 다음과 같이 전달하십시오 …
총 9가지 요구사항이 있습니다. 아래 버튼을 사용하여 전체 prompt를 복사하십시오.
이 prompt가 방지해 주는 문제점
이 prompt가 방지해 주는 문제점
지원 모델
본 결과는 2026-10-11 (UTC+8)에 진행된 테스트를 기반으로 합니다. 2.5초마다 다른 숫자와 도형이 나타나는 동일한 10초 테스트 동영상을 모든 모델에 전송한 후, 각 타임스탬프와 함께 숫자를 순서대로 나열하도록 하였습니다. 동영상을 실제로 보지 않고 생성된 답변을 배제하기 위해 빈 이미지를 대조군으로 사용했습니다.gemini-3.7-flash 및 gemini-3.5-flash뿐만 아니라, 안정적인 클래식 모델인 gemini-2.5-pro(2M context) 및 gemini-2.5-flash도 계속 사용할 수 있습니다. 테스트 결과 3.8 Flash는 3.5 Flash의 절반 수준인 입력 가격으로 정확히 동일한 동영상 tokens(10초 기준 약 713 tokens)를 소모했습니다. 지연 시간 및 token 수치는 상기 10초 540p 테스트 클립 기준이며, 더 길거나 해상도가 높은 동영상은 대략 비례하여 증가합니다. 실제 지연 시간은 엔드포인트 및 제공업체 측의 대기열 상황에 따라서도 달라지므로 동일한 클립이라도 2~3배 차이가 날 수 있습니다.
동영상을 지원하지 않는 모델
동영상 입력 방식
빠른 시작: 범용 형식 (video_url)
Seed, Qwen, Kimi, MiniMax 및 Gemini에서 작동합니다.
<BASE64_VIDEO>을 동영상의 base64 문자열로 대체하거나, url 전체를 공개 주소로 대체하십시오):
Gemini 전용 형식
Base64 인라인 (레거시 image_url 형식)
Gemini는 위의 video_url 형식과 아래의 image_url 형식을 모두 지원하므로 기존 코드가 계속 작동합니다. 새 코드에서는 모델을 자유롭게 전환할 수 있도록 video_url을(를) 사용하십시오.
Base64 인라인 (Gemini 네이티브 형식)
프로젝트에서 이미 Google의 공식google-genai SDK를 사용하고 있다면 OpenAI 호환 형식으로 전환할 필요가 없습니다. base_url이(가) https://api.apiyi.com을(를) 가리키도록 설정하고 Part.from_bytes(으)로 동영상을 인라인 처리하십시오. 위와 마찬가지로 전체 요청 본문은 20 MB 미만을 유지해야 합니다.
-d @req.json(으)로 전송하십시오.
YouTube 링크 (Gemini 네이티브 형식)
YouTube 링크는 다운로드가 필요하지 않으며 20 MB 제한의 적용을 받지 않지만, Gemini 네이티브 형식을 통해서만 작동합니다(google-genai SDK, 엔드포인트 https://api.apiyi.com).
동영상을 지원하지 않는 모델: 프레임을 이미지로 전송
GPT 및 Grok과 같은 이미지 전용 모델의 경우, 로컬에서 일정한 간격으로 프레임을 추출하여 여러 이미지로 전송합니다. 자체 테스트 결과gpt-6-sol, gpt-6-luna, gpt-5.6-terra, grok-4.7 및 grok-4.5 모두 4개의 프레임에서 내용과 순서를 정확하게 설명했습니다. 트레이드오프: 오디오와 프레임 간의 움직임이 손실되며, 프롬프트에 시간 정보를 직접 명시해야 합니다.
고급 팁
타임스탬프 참조
MM:SS를 사용하여 prompt에서 세그먼트를 직접 참조할 수 있습니다. 이는 순수한 프롬프팅 기법이며 동영상을 지원하는 모든 모델에서 작동합니다:
답변을 신뢰할 수 없는 두 가지 경우
① 동영상이 모델에 도달하지 않은 경우: 응답의usage.prompt_tokens를 확인하십시오. 10초 분량의 클립은 Seed / Qwen에서 약 5,000 tokens, Gemini에서 약 700 tokens입니다. 단 수십 tokens에 불과하다면 동영상이 누락된 것이며(GPT 및 GLM에서 발생하거나 Gemini에 공개 URL을 제공했을 때 발생하는 현상입니다), 이 답변은 신뢰할 수 없습니다. 모델이 아무것도 볼 수 없다고 반드시 말하는 것은 아닙니다. 공개 URL이 제공된 경우 Gemini는 누락된 동영상을 “완전히 검은 화면”으로 설명하고, GPT는 존재하지 않는 콘텐츠를 지어냅니다.
② 입력이 잘못되었고 prompt가 특정 내용을 전제하는 경우: 예를 들어 잘못된 파일이 전송되었거나, 동영상이 검은색 또는 회색 화면으로 디코딩되었거나, 연동 과정에서 플레이스홀더 이미지가 사용된 경우입니다. 이 경우 prompt_tokens는 완전히 정상적으로 보이므로 token 수로는 이를 감지할 수 없습니다.
일반적인 작업을 위한 prompt 아이디어
코드를 변경할 필요 없이 prompt만 변경해도 동일한 동영상으로 완전히 다른 분석을 수행할 수 있습니다:- 콘텐츠 요약: 주제, 핵심 장면 및 시사점을 3~5개 문장으로 요약
- 강의 분석: 핵심 개념, 챕터 구분 및 중요한 타임스탬프 추출
- 보안 감시 검토: 이상 행동, 나타난 사람/물체 및 등장 시점 표시
- 마케팅 검토: 제품 셀링 포인트의 표현 방식, 템포 및 타깃 고객 적합도 평가
- 동작 분석: 동작 단계 세분화, 자세 교정 포인트 및 개선점 도출
기술 참고 사항
- Gemini: 기본적으로 초당 1프레임으로 샘플링하며 오디오 트랙도 함께 처리합니다. Gemini 3.x는 기본적으로 프레임을 저해상도로 계산하며, 자체 테스트 결과 초당 약 70 tokens가 소모됩니다.
- Seed / Qwen: 자체 테스트 기준(540p 동영상) 초당 약 500 tokens이며, Seed의 샘플링은
fps(으)로 조정할 수 있습니다. - Kimi K3: 자체 테스트 기준 초당 약 1,400 tokens가 소모되므로, 긴 동영상은 비용이 눈에 띄게 더 발생합니다.
- 지원 형식: mp4, mov, webm 등 일반적인 형식을 지원하며, H.264 mp4로 변환하면 가장 뛰어난 호환성을 제공합니다.
자주 묻는 질문
GPT, Grok 또는 Claude가 동영상을 이해할 수 있습니까?
GPT, Grok 또는 Claude가 동영상을 이해할 수 있습니까?
어떤 중국 모델이 동영상 이해를 지원합니까?
어떤 중국 모델이 동영상 이해를 지원합니까?
seed-2-0-pro-260328, dola-seed-2-1-turbo-260628, seed-2-0-lite-260428, seed-2-0-mini-260428, seed-1-8-251228), Qwen의 qwen3.8-max, qwen3.8-flash, qwen3-vl-plus, qwen3.5-omni-plus 및 kimi-k3입니다. MiniMax-M3은(는) 내용은 인식하지만 타임스탬프가 올바르지 않습니다. glm-5.3 및 deepseek-v4-flash-vision-exp은(는) 동영상을 지원하지 않습니다.모델을 변경하면 동일한 코드에서 400 오류가 반환됩니까?
모델을 변경하면 동일한 코드에서 400 오류가 반환됩니까?
image_url + data:video/mp4 형식을 사용하고 계실 가능성이 높습니다. {"type": "video_url", "video_url": {"url": ...}}(으)로 변경하면 모든 제공업체에서 정상 작동합니다.Gemini가 동영상에 없는 내용을 설명합니까?
Gemini가 동영상에 없는 내용을 설명합니까?
공개 동영상 URL에서 Request contains an invalid argument / fetch failed 오류가 반환되는 경우
공개 동영상 URL에서 Request contains an invalid argument / fetch failed 오류가 반환되는 경우
https://example.com/video.mp4), 이는 APIYI의 차단이 아닙니다. Gemini에서는 인라인 base64(20MB 미만) 또는 YouTube 링크를 대신 사용하거나, 공개 URL을 직접 가져올 수 있는 Seed / Qwen으로 전환하십시오. /v1/chat/completions에서는 항상 오류가 발생하는 것은 아닙니다. 200을 반환하면서 모델이 검은 화면이 보인다고 주장할 수 있으며, 이 경우 prompt_tokens은(는) 수십 개에 불과하여 결과를 사용할 수 없습니다.Gemini는 왜 요청 크기를 20MB로 제한합니까? 이전에는 작동했습니다.
Gemini는 왜 요청 크기를 20MB로 제한합니까? 이전에는 작동했습니다.
대용량 동영상에 files.upload를 사용할 수 있습니까?
대용량 동영상에 files.upload를 사용할 수 있습니까?
client.files.upload())는 서드파티 엔드포인트에서 지원되지 않으며, Google 자체 엔드포인트에서만 지원됩니다. 대용량 동영상의 경우 YouTube 링크를 사용하거나, base64용으로 20MB 미만으로 압축하거나, 공개 URL과 함께 Seed / Qwen으로 전환하십시오.20MB를 초과하는 동영상은 어떻게 처리합니까?
20MB를 초과하는 동영상은 어떻게 처리합니까?