메인 콘텐츠로 건너뛰기
APIYI의 여러 모델 제품군은 동영상을 “시청”할 수 있습니다. 단일 prompt만으로 모델이 장면, 동작, 화면 텍스트를 인식하고 타임스탬프별로 주요 순간을 참조할 수 있습니다. Gemini 외에도 Seed (Doubao) 전 제품군, Qwen의 비전 및 omni 모델, Kimi K3가 모두 테스트를 통과했습니다. 이 페이지에서는 지원 목록, 범용 요청 형식, 그리고 혼동하기 쉬운 제한 사항을 다룹니다.
먼저 다음 세 가지 사항을 확인하십시오:
  1. 범용 형식은 video_url입니다: {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,..."}} 형식은 Seed, Qwen, Kimi, MiniMax 및 Gemini에서 작동합니다. 이 페이지의 이전 버전에 안내되었던 기존 image_url + data:video/mp4 형식은 Gemini에서만 작동하며, 그 외 다른 모든 모델에서는 400을 반환합니다.
  2. GPT, Grok, Claude, GLM 및 DeepSeek는 동영상 입력을 지원하지 않습니다. GPT와 GLM은 동영상을 자동으로 제외한 채 200을 반환하며, GPT는 그럴듯한 답변을 지어낼 수도 있습니다 — “동영상을 지원하지 않는 모델”을 참조하십시오.
  3. Gemini는 일반 공개 동영상 URL을 직접 지원하지 않습니다: Request contains an invalid argument을 반환하거나, 동영상이 자동으로 제외된 채(prompt_tokens가 수십 개에 불과함) 200을 반환하여 동영상을 볼 수 없다고 답변하거나 검은 화면으로 묘사할 수 있습니다. 반면 Seed, Qwen, Kimi는 공개 https URL을 직접 수신할 수 있습니다.

시각적 API 테스트

iCover 시각적 테스트 도구에서 동영상을 업로드하고 이해 엔드포인트를 테스트해 보십시오.

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 페 … 도 읽으십시오.

  1. 엔드포인트 및 형식: OpenAI 호환 POST https://api.apiyi.com/v1/chat/completions을(를) 사용하고 항상 비디오를 다음과 같이 전달하십시오 …

총 9가지 요구사항이 있습니다. 아래 버튼을 사용하여 전체 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배 차이가 날 수 있습니다.
모델 가격은 공식 사이트와 연동되어 변동될 수 있습니다. 위 표는 참고용일 뿐이며 상단 내비게이션의 모델 가격 탭을 기준으로 합니다: 모델 가격.

동영상을 지원하지 않는 모델

동영상이 누락된 후 GPT가 답변을 지어낼 수 있습니다: 테스트 결과 gpt-6-sol 모델은 3회 테스트 모두 동영상에 없는 숫자 시퀀스를 지어냈으며, 런던 거리 풍경을 “튜브가 있는 수영장”으로 묘사하기도 했습니다. 이러한 모델을 꼭 사용해야 한다면 아래의 “프레임을 이미지로 변환” 방식을 사용하십시오.

동영상 입력 방식

Gemini의 20 MB 제한: Base64를 사용할 경우 인코딩된 동영상을 포함한 전체 요청 본문 크기가 20 MB 미만이어야 합니다. 용량이 더 큰 동영상의 경우 ① YouTube 링크를 사용하거나, ② 인코딩 전 로컬에서 동영상을 압축 또는 트리밍하여 20 MB 이하로 줄이거나, ③ Seed / Qwen으로 전환하여 공개 URL을 직접 전달하십시오.
제공업체가 URL을 가져올 수 있어야 합니다: 동영상은 모델 제공업체에서 다운로드하므로 해당 주소는 제공업체 측에서 접근할 수 있어야 합니다. 테스트 결과 Volcengine 오브젝트 스토리지의 URL은 Seed, Qwen, Kimi 및 MiniMax에서 정상 작동했으나, Google Cloud Storage URL은 Seed에서 403을 반환했습니다. 확실하지 않은 경우 먼저 Base64가 정상 작동하는지 확인한 다음 URL 방식으로 전환하십시오.

빠른 시작: 범용 형식 (video_url)

Seed, Qwen, Kimi, MiniMax 및 Gemini에서 작동합니다.
동일한 curl 호출 예시입니다(<BASE64_VIDEO>을 동영상의 base64 문자열로 대체하거나, url 전체를 공개 주소로 대체하십시오):
Seed에서는 샘플링 레이트를 조정할 수 있습니다: 빠른 움직임을 더 자세히 살펴보려면 video_url 내부에 "fps": 2을 추가하십시오(자체 테스트 결과, 10초 분량의 클립에서 입력 tokens가 약 4,900개에서 약 6,200개로 증가했습니다). Qwen과 Kimi는 이 필드를 무시합니다.

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 미만을 유지해야 합니다.
REST 방식: Base64 문자열은 길이가 길기 때문에 명령줄 인수에 직접 붙여넣지 마십시오. 먼저 JSON 파일로 저장한 다음 -d @req.json(으)로 전송하십시오.
네이티브 형식을 사용하면 동영상이 모델에 도달했는지 확인하기가 더 쉽습니다: 응답의 usageMetadata.promptTokensDetails은(는) 입력을 모달리티별로 구분하여 표시합니다. 당사의 10초짜리 테스트 클립은 OpenAI 호환 형식과 동일한 총합인 VIDEO 660과 소수의 TEXT tokens로 반환되었습니다. VIDEO 항목이 없다면 동영상이 수신되지 않은 것입니다.

YouTube 링크 (Gemini 네이티브 형식)

YouTube 링크는 다운로드가 필요하지 않으며 20 MB 제한의 적용을 받지 않지만, Gemini 네이티브 형식을 통해서만 작동합니다(google-genai SDK, 엔드포인트 https://api.apiyi.com).
네이티브 형식의 추가 기능(스트리밍, thinking budget, 함수 호출 등)에 대해서는 Gemini 네이티브 형식을 참조하십시오.

동영상을 지원하지 않는 모델: 프레임을 이미지로 전송

GPT 및 Grok과 같은 이미지 전용 모델의 경우, 로컬에서 일정한 간격으로 프레임을 추출하여 여러 이미지로 전송합니다. 자체 테스트 결과 gpt-6-sol, gpt-6-luna, gpt-5.6-terra, grok-4.7 및 grok-4.5 모두 4개의 프레임에서 내용과 순서를 정확하게 설명했습니다. 트레이드오프: 오디오와 프레임 간의 움직임이 손실되며, 프롬프트에 시간 정보를 직접 명시해야 합니다.

고급 팁

타임스탬프 참조

MM:SS를 사용하여 prompt에서 세그먼트를 직접 참조할 수 있습니다. 이는 순수한 프롬프팅 기법이며 동영상을 지원하는 모든 모델에서 작동합니다:
정확한 타임스탬프가 중요한 경우 Seed 또는 Qwen을 사용하는 것이 좋습니다. 자체 테스트 결과 MiniMax-M3의 타임스탬프는 신뢰할 수 없었습니다.

답변을 신뢰할 수 없는 두 가지 경우

① 동영상이 모델에 도달하지 않은 경우: 응답의 usage.prompt_tokens를 확인하십시오. 10초 분량의 클립은 Seed / Qwen에서 약 5,000 tokens, Gemini에서 약 700 tokens입니다. 단 수십 tokens에 불과하다면 동영상이 누락된 것이며(GPT 및 GLM에서 발생하거나 Gemini에 공개 URL을 제공했을 때 발생하는 현상입니다), 이 답변은 신뢰할 수 없습니다. 모델이 아무것도 볼 수 없다고 반드시 말하는 것은 아닙니다. 공개 URL이 제공된 경우 Gemini는 누락된 동영상을 “완전히 검은 화면”으로 설명하고, GPT는 존재하지 않는 콘텐츠를 지어냅니다. ② 입력이 잘못되었고 prompt가 특정 내용을 전제하는 경우: 예를 들어 잘못된 파일이 전송되었거나, 동영상이 검은색 또는 회색 화면으로 디코딩되었거나, 연동 과정에서 플레이스홀더 이미지가 사용된 경우입니다. 이 경우 prompt_tokens는 완전히 정상적으로 보이므로 token 수로는 이를 감지할 수 없습니다.
Gemini 모델은 ②의 경우 질문의 의도에 맞춰 답변을 지어내는 경향이 있습니다. 자체 테스트에서 동영상을 빈 이미지로 대체해 보았습니다:
  • 중립적으로 질문했을 때(“받은 내용을 설명하세요”), Gemini 3.8 Flash / 3.5 Flash / 3.1 Pro / 3.1 Flash Lite는 12회 실행 모두에서 빈 이미지라고 올바르게 답변했습니다. 즉, 이미지 이해 자체에는 문제가 없습니다;
  • 그러나 질문이 특정 내용을 전제하는 순간(“동영상에 어떤 숫자가 순서대로 나타납니까”, 또는 심지어 “숫자가 있습니까? 없다면 없다고 말하세요”), 3.5 Flash / 3.1 Pro / 3.1 Flash Lite는 18회 중 12회에서 존재하지 않는 숫자를 지어냈습니다;
  • 더 최신인 gemini-3.8-flash는 분명히 개선되었지만 완전히 해결되지는 않았습니다. 동일한 유도 질문에 대해 7회 중 2회에서 여전히 답변을 지어냈습니다;
  • 동일한 질문을 받았을 때 Seed, Qwen 및 Kimi는 모두 보이지 않는다거나 아무것도 없다고 올바르게 답변했습니다.
실제 동영상에 대한 인식에는 영향이 없습니다. 입력을 직접 제어할 수 없는 배치 파이프라인의 경우, 먼저 중립적인 질문을 던져 모델이 무엇을 보고 있는지 설명하게 함으로써 입력이 올바른지 확인한 후 구체적인 질문을 하거나, Seed / Qwen을 사용하십시오.

일반적인 작업을 위한 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로 변환하면 가장 뛰어난 호환성을 제공합니다.

자주 묻는 질문

불가능합니다. Claude와 Grok은 즉시 오류를 반환하며, GPT의 chat 엔드포인트는 동영상을 알림 없이 누락한 채 200을 반환하므로 모델이 답변을 지어낼 수 있습니다. 해당 모델들을 사용해야 하는 경우 먼저 프레임을 추출하여 이미지로 전송하십시오. 자세한 내용은 “동영상을 지원하지 않는 모델: 프레임을 이미지로 변환”을 참고하시기 바랍니다.
테스트를 통과한 모델: 전체 Seed 제품군(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은(는) 동영상을 지원하지 않습니다.
Gemini만 지원하는 기존 image_url + data:video/mp4 형식을 사용하고 계실 가능성이 높습니다. {"type": "video_url", "video_url": {"url": ...}}(으)로 변경하면 모든 제공업체에서 정상 작동합니다.
먼저 입력 자체에 문제가 없는지 확인하십시오(검은 화면, 빈 프레임, 잘못된 파일이 아닌지 확인). 테스트 결과, 입력이 잘못되었는데 질문에서 특정 내용을 전제하는 경우 Gemini는 질문에 맞춰 답변을 지어내는 경향이 있었습니다. 문제를 해결하려면 “수신한 내용을 설명해 주세요”와 같은 중립적인 prompt로 변경하여 해당 동영상을 설명하는지 확인하십시오. 자세한 내용은 “답변을 신뢰할 수 없는 두 가지 경우”를 참고하시기 바랍니다.
Gemini는 임의의 공개 URL을 지원하지 않으며(예: https://example.com/video.mp4), 이는 APIYI의 차단이 아닙니다. Gemini에서는 인라인 base64(20MB 미만) 또는 YouTube 링크를 대신 사용하거나, 공개 URL을 직접 가져올 수 있는 Seed / Qwen으로 전환하십시오. /v1/chat/completions에서는 항상 오류가 발생하는 것은 아닙니다. 200을 반환하면서 모델이 검은 화면이 보인다고 주장할 수 있으며, 이 경우 prompt_tokens은(는) 수십 개에 불과하여 결과를 사용할 수 없습니다.
인라인 base64를 사용할 경우, Gemini는 항상 전체 요청 본문을 20MB로 제한해 왔습니다(Google의 공식 제한과 동일). “이전에는 작동했다”고 한 것이 공개 URL이었다면, 이는 한 번도 공식 지원된 방식이 아니었습니다. 일부 경우에 우연히 오류가 발생하지 않았을 뿐이며, 현재는 명시적으로 거부됩니다.
불가능합니다. Gemini의 공식 Files API(client.files.upload())는 서드파티 엔드포인트에서 지원되지 않으며, Google 자체 엔드포인트에서만 지원됩니다. 대용량 동영상의 경우 YouTube 링크를 사용하거나, base64용으로 20MB 미만으로 압축하거나, 공개 URL과 함께 Seed / Qwen으로 전환하십시오.
세 가지 방법이 있습니다: ① YouTube에 업로드하고 링크를 전달합니다(Gemini 네이티브 형식). ② ffmpeg 등의 도구를 사용하여 핵심 구간을 20MB 미만으로 압축하거나 잘라낸 후 base64로 인코딩합니다. ③ 공개적으로 접근 가능한 객체 스토리지에 동영상을 호스팅하고 Seed / Qwen에 URL을 전달합니다.

관련 리소스

모델 요금 안내

모든 모델 및 최신 요금 정보

Gemini 네이티브 포맷

YouTube 링크, 스트리밍, thinking budget 및 다양한 네이티브 기능

비전 이해 API

이미지 콘텐츠 인식 및 멀티모달 분석

Qwen3.8-Max

네이티브 이미지 및 동영상 입력을 지원하는 Qwen 플래그십 모델