개요
동영상 이해는 모델이 동영상 프레임과 텍스트 지시를 분석하고 설명, 타임스탬프 또는 구조화된 결과를 반환하는 기능입니다. 주요 용도는 다음과 같습니다.- 장면 및 인물 행동 설명
- 동영상 요약 및 내용에 대한 질의응답
- 이벤트 시작 및 종료 시점 찾기
- JSON 형식의 정보 추출
qwen3.7-plus를 예로 들어 Chat Completions와 Responses API의 MP4 입력 방법을 설명합니다.
API 및 입력 형식
Responses의
video_url은 AIHubMix 확장 필드입니다. 아래 예제에서는 HTTP 요청으로 전달합니다.
Gemini 모델의 멀티미디어 입력 방법은 Gemini 가이드를 참조하세요.
빠른 시작
다음 예제는 Node.js 22의 내장fetch를 사용하므로 SDK 설치가 필요하지 않습니다. 실행 전에 환경 변수 AIHUBMIX_API_KEY를 설정하세요. 예제 URL은 Alibaba 공식 문서의 공개 MP4입니다. 실제 서비스에서는 url을 모델 프로바이더가 접근할 수 있는 동영상 주소로 바꾸세요.
.mjs 파일로 저장한 뒤 Node.js로 실행하세요. 성공 결과는 choices[0].message.content에 있으며 JSON으로 한 번 더 파싱해야 합니다. 예제는 콘솔에서 확인할 수 있도록 요청 ID와 사용량도 출력합니다.
로컬 동영상 입력
로컬 파일을 Base64로 인코딩한 뒤data:video/mp4;base64, 데이터 URL로 전달합니다. 다음 예제는 첫 번째 명령줄 인수에서 파일 경로를 읽으며, 인수가 없으면 현재 디렉터리의 video.mp4를 읽습니다. HTTP 요청의 동영상 URL에 로컬 파일 경로를 직접 사용할 수 없습니다.
Responses API
Responses 요청에서도video_url 객체를 사용하며 텍스트 블록에는 input_text를 지정합니다. JSON 출력 설정은 text.format 아래에 둡니다. 이 예제도 첫 번째 명령줄 인수 또는 현재 디렉터리의 video.mp4에서 동영상을 읽습니다.
output에는 추론 항목과 메시지 항목이 함께 포함될 수 있습니다. 결과를 읽을 때는 message의 output_text를 선택하세요. 출력 사용량에는 추론 토큰이 포함될 수 있으므로 최종 JSON 길이만으로 비용을 추정할 수 없습니다.
구조화된 출력
예제는 JSON 모드로scenes 배열을 반환합니다. 각 장면에는 다음 필드가 포함됩니다.
애플리케이션 요구 사항에 맞게 프롬프트와 필드를 조정할 수 있습니다. JSON 모드는 JSON 출력을 보장하며, 필드 유형, 필수 항목, 시간 범위는 애플리케이션에서 검증해야 합니다.
파일 및 길이 제한
Alibaba 공식 시각 이해 문서에 명시된 Qwen3.7 시리즈의 동영상 제한은 다음과 같습니다.- 동영상 형식에는 MP4, AVI, MKV, MOV, FLV, WMV가 포함됩니다.
- 동영상 길이는 2초부터 2시간까지입니다.
- Base64로 인코딩된 문자열은 10MB 미만이어야 하며, 원본 파일은 7MB 미만을 권장합니다.
- 공개 URL 방식의 프로바이더 파일 크기 상한은 2GB입니다.
요금 및 토큰
Qwen은 동영상 프레임을 입력 토큰으로 변환하여 프롬프트와 함께 입력 사용량에 포함합니다. 모델이 생성한 콘텐츠는 출력 사용량에 포함됩니다. 동영상 길이, 해상도, 프레임 추출 방식이 사용량에 영향을 주므로 MP4 파일 크기나 초 단위 길이만으로 비용을 계산할 수 없습니다. Qwen3.7 Plus의 동영상 입력에는 모델의 입력 토큰 단가가, 생성 콘텐츠에는 출력 토큰 단가가 적용됩니다. 가격은 Qwen3.7 Plus 모델 페이지를 참조하세요.- Chat Completions 사용량 필드는
usage.prompt_tokens와usage.completion_tokens입니다. - Responses 사용량 필드는
usage.input_tokens와usage.output_tokens입니다. - 추론 토큰은 출력 토큰에 이미 포함되므로 다시 더하지 않습니다.
- 캐시 적중 부분에는 해당 캐시 요금이 적용됩니다.
x-aihubmix-request-id를 보관하세요.
사용 권장 사항
- 동영상과 텍스트 지시를 함께 보내고 추출할 내용과 출력 형식을 명확히 지정하세요.
- 공개 동영상 링크는 요청 중 유효해야 하며 모델 프로바이더가 접근할 수 있어야 합니다.
- 작은 로컬 파일에는 Base64를, 큰 파일에는 공개 URL을 우선 사용하세요.
- 애플리케이션에서 JSON 필드, 장면 순서, 시간 범위를 검증하세요.
- 타임스탬프는 이벤트 위치 파악과 콘텐츠 검색에 적합합니다. 정밀 편집이 필요하면 동영상 처리 도구로 경계를 보정하세요.
업데이트: 2026-10-13