Vega-VLHOT
On this page
Endpoint: https://mmu.vod-qcloud.com/v1
인증: VOD ApiToken / Bearer
Vega-VL은 텍스트, 이미지, 오디오, 파일, 영상을 분석하고 질문에 대한 답변을 텍스트 또는 JSON으로 반환하는 WAND의 멀티모달 이해 모델입니다. VL은 Vision-Language를 뜻하며, Vega-VL은 시각 정보와 언어뿐 아니라 음성 및 문서 입력도 함께 처리합니다.
분석할 자료와 지시문을 전달하면 내용을 요약하거나, 필요한 정보를 추출하고, 분류 결과를 얻을 수 있습니다. 영상 분석에서는 장면의 흐름과 음성 내용을 바탕으로 챕터, 하이라이트, 시간 구간을 정리할 수 있습니다.
지원 입력과 활용
API는 Text / Image / Audio / File / Video 입력 형식을 제공합니다. 자료를 분석할 때는 질문과 해당 입력을 함께 전달합니다. 텍스트 단독 요청과 파일 전달 방식은 아래 버전별 입력 구성을 따릅니다.
| 입력 형식 | 분석 대상 | 활용 예 |
|---|---|---|
Text |
질문, 지시문, 본문 텍스트 | 질의응답, 요약, 정보 추출, 분류 |
Image |
사진, 상품 이미지, 화면 캡처 | 이미지 설명, 화면 문자 인식, 상품 정보 추출, 태깅 |
Audio |
음성 및 녹음 자료 | 발화 내용 분석, 음성 내용 요약, 질의응답 |
File |
PDF 등 문서 자료 | 문서 요약, 핵심 정보 추출, 문서 기반 질의응답 |
Video |
강의, 상품 소개, 숏폼, 장편 영상 | 내용 요약, 장면 분할, 하이라이트 추출, 시간 구간 라벨링 |
결과는 서비스에서 필요한 형식으로 지정합니다. 예를 들어 강의에서는 핵심 개념을 추출하고, 상품 소개에서는 상품 정보와 특징을 정리하며, 영상 편집에서는 장면별 시작과 종료 시점을 반환하도록 요청할 수 있습니다.
기본 정보
| 항목 | 값 |
|---|---|
| 서비스 | Tencent VOD AIGC 멀티모달 이해 |
| 엔드포인트 | POST https://mmu.vod-qcloud.com/v1/chat/completions |
| 인증 | Authorization: Bearer {VOD AIGC Token} |
| 토큰 발급 | DescribeAigcApiTokens / CreateAigcApiToken (VOD API) |
| 모델 | wand-vega-vl-1.0-lite / wand-vega-vl-1.0-flash / wand-vega-vl-1.0-pro |
| 입력 형식 | Text / Image / Audio / File / Video |
| 스트리밍 | stream: false 고정 |
| JSON 출력 | response_format: {"type":"json_object"} 지원 |
| 응답 형태 | OpenAI 호환 choices[0].message.content |
버전별 입력 구성
| 버전 | 텍스트 단독 요청 | 분석 입력 예시 |
|---|---|---|
1.0 Pro |
미지원 / 분석 자료와 함께 전달 | 이미지, 오디오, PDF, 영상 URL |
1.0 Flash |
지원 | 텍스트, 이미지, 오디오, 영상 |
1.0 Lite |
지원 | 텍스트, 이미지, 오디오, 영상 |
1.0 Pro
모델 ID: wand-vega-vl-1.0-pro
이미지, 오디오, PDF 문서 또는 영상과 분석 지시문을 함께 전달합니다. 텍스트는 질문과 출력 규칙을 지정하는 용도로 사용하며, 분석 자료를 최소 1개 포함합니다.
| 입력 | 전달 필드 |
|---|---|
| 이미지 URL | image_url.url |
| 오디오 URL | input_audio.url |
| PDF URL | file.file_url |
| 영상 URL | video_url.url |
PDF 문서 분석
문서에서 특정 항목을 추출하는 요청입니다.
{
"model": "wand-vega-vl-1.0-pro",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "문서에 기재된 참조 코드와 청구 금액을 추출하세요."
},
{
"type": "file",
"file": {
"file_url": "https://wand.tencentpoc.com/api/media/vega-vl-sample.pdf"
}
}
]
}
]
}예시 문서의 참조 코드는 MAVORA, 청구 금액은 42 USD입니다. 분석 결과는 choices[0].message.content에서 확인합니다.
1.0 Flash
모델 ID: wand-vega-vl-1.0-flash
텍스트 단독 요청과 이미지, 오디오, 영상 분석에 사용할 수 있습니다. 텍스트만 보낼 때는 content를 문자열로 지정하고, 자료를 함께 보낼 때는 Part 배열로 구성합니다.
텍스트 요청
{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"messages": [
{
"role": "user",
"content": "17 + 26을 계산하고 숫자만 답하세요."
}
]
}응답 본문은 43입니다. 영상 분석 요청은 아래의 영상 분석 예시를 참고하세요.
1.0 Lite
모델 ID: wand-vega-vl-1.0-lite
텍스트 단독 요청과 이미지, 오디오, 영상 분석에 사용할 수 있습니다. 오디오는 input_audio.url에 접근 가능한 파일 URL을 전달합니다.
오디오 분석
{
"model": "wand-vega-vl-1.0-lite",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "녹음에서 말한 코드 단어와 숫자를 추출하세요."
},
{
"type": "input_audio",
"input_audio": {
"url": "https://wand.tencentpoc.com/api/media/vega-vl-sample.wav"
}
}
]
}
]
}예시 오디오의 코드 단어는 lantern, 숫자는 43입니다. 오디오 URL 입력은 Flash와 Pro에서도 같은 Part 형식을 사용합니다.
영상 분석 예시
요청
curl -sS https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer $AIGC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"response_format": {
"type": "json_object"
},
"messages": [
{
"role": "system",
"content": "영상에서 확인되는 내용만 분석하고 유효한 JSON으로 응답합니다."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 주요 장면을 요약하고 짧은 클립으로 사용할 구간 1개를 선택하세요. 시작과 종료는 초 단위입니다. 응답 형식: {\"summary\":\"장면 요약\",\"highlights\":[{\"start\":0,\"end\":5,\"score\":80,\"reason\":\"선정 이유\"}]}. score는 0부터 100 사이의 정수입니다."
},
{
"type": "video_url",
"video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
}
}
]
}
]
}'분석 결과
{
"summary": "영상은 초콜릿 강의 수면을 따라 카메라가 이동하며 점점 상승해, 사탕 지팡이, 공중에 떠다니는 마카롱, 사탕으로 만들어진 거대한 투명 건물이 가득한 환상적인 디저트 세계의 풍경을 보여주고, 쿠키와 사탕 장식이 달린 특별한 의상을 입은 소녀가 웃으며 걸어가 주변 풍경에 감탄하는 모습을 담는다.",
"highlights": [
{
"start": 0,
"end": 10,
"score": 90,
"reason": "영상의 전체 판타지 디저트 세계 풍경과 소녀의 즐거운 반응이 모두 포함되어 이 영상의 독특한 동화적인 분위기를 짧은 클립 하나로 완벽하게 전달할 수 있기 때문"
}
]
}분석 작업
messages에 분석 지시문과 텍스트 또는 분석할 자료를 전달합니다. 응답은 텍스트 또는 JSON으로 받을 수 있습니다.
| 입력 | 분석 요청 | 응답 형식 |
|---|---|---|
| 영상 URL | 영상 요약 | 요약 문단. 장면마다 대략적인 타임스탬프가 붙습니다 |
| 영상 URL | 하이라이트 구간 추출 | highlights JSON. 시작과 끝, 점수, 이유가 담깁니다 |
| 영상 URL | 장면별 챕터 분할 | chapters JSON. 구간별 제목과 요약이 담깁니다 |
| 이미지 URL | 화면 텍스트 인식 | texts JSON. 시간, 텍스트, 종류(자막, 간판, UI 등)가 담깁니다 |
| 이미지 URL | 이미지 태깅 | tags / categories / keywords JSON |
| 텍스트 | 본문 요약, 정보 추출 | 요약 문단 또는 지정한 JSON |
| 오디오 | 음성 내용 요약 | 요약 문단 또는 지정한 JSON |
| 파일 | 문서 요약, 문서 기반 질의응답 | 답변 문단 또는 지정한 JSON |
JSON 응답은 response_format={"type":"json_object"}로 지정하고 프롬프트에 필요한 필드를 정의합니다.
요청 예시
필수 필드는 model과 messages입니다. 아래는 영상 요약 요청과 응답입니다.
요청:
{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 전체 내용을 요약해줘."
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/clip.mp4"
}
}
]
}
]
}응답:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "6초 분량의 클립으로, ..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1285,
"completion_tokens": 1211,
"total_tokens": 2496
}
}분석 결과는 choices[0].message.content에 반환됩니다. 종료 사유와 사용량을 함께 확인합니다.
공통 요청 규격
VOD AIGC 토큰을 Bearer 인증에 사용합니다. 텍스트 게이트웨이와 같은 토큰 풀을 사용하므로 기존 토큰을 재사용할 수 있습니다.
토큰 발급 절차는 VOD Text의 토큰 발급 섹션과 동일합니다.
토큰은 SubApp당 최대 50개이며 유효 기간은 무기한입니다. DescribeAigcApiTokens로 기존 토큰을 조회할 수 있습니다.
요청 헤더
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
Authorization |
필수 | Bearer {TOKEN} 형식 |
Content-Type |
필수 | application/json |
Tx-User-Session-Id |
선택 | 같은 값을 유지하면 프리픽스 캐시가 적용되어 비용과 지연이 줄어듭니다. 같은 영상에 후속 질문을 반복하는 구조라면 세션 ID를 고정해 사용하세요 |
요청 파라미터
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
model |
필수 | String | 모델 ID. wand-vega-vl-1.0-lite / wand-vega-vl-1.0-flash / wand-vega-vl-1.0-pro |
messages |
필수 | Array | 모델에 전달하는 대화 목록. 원소마다 role과 content를 담습니다. 아래 messages 배열 항목 참고 |
stream |
필수 | Boolean | false로 지정합니다 |
response_format |
선택 | Object | JSON으로 받을 때 사용합니다. {"type":"json_object"} |
temperature |
선택 | Float | 출력 무작위성. 0.0 ~ 2.0, 예시 0.2 |
max_tokens |
선택 | Integer | 최대 생성 토큰 수, 예시 4096 |
thinking_enabled |
선택 | Boolean | 추론(CoT) 모드 활성화 |
reasoning_effort |
선택 | String | 추론 강도. 생략하면 서버 기본값이 적용됩니다 |
model, messages, stream을 지정합니다. Vega-VL은 stream=false를 사용합니다.
messages 배열
messages는 모델에게 전달하는 대화 목록입니다. 원소 하나가 메시지 하나이고, 각 메시지는 role과 content 두 필드를 가집니다.
"messages": [
{ "role": "system", "content": "답변 규칙" },
{ "role": "user", "content": "질문과 미디어" }
]| 필드 | 필수 | 타입 | 설명 |
|---|---|---|---|
role |
필수 | String | 이 메시지가 누구의 것인지 정합니다. 미디어 분석에서는 system과 user 두 개면 충분합니다 |
content |
필수 | String 또는 Array | 메시지 본문. 텍스트만 보내면 문자열, 이미지, 오디오, 파일, 영상을 함께 보내면 Part 배열입니다 |
role
role은 메시지의 역할을 지정합니다. 기본 분석 요청은 system과 user로 구성합니다.
system은 모델이 어떤 방식으로 답할지 정하는 규칙입니다. 답변 언어, 말투, 출력 형식을 여기에 적습니다.user는 실제 요청입니다. 질문과 분석할 자료를 함께 전달합니다.
나머지 값과 대화 이력을 쓰는 방법은 Messages 내 Role 설정을 참고하세요.
content
content는 텍스트만 보낼 때와 미디어를 함께 보낼 때 형식이 다릅니다. 텍스트 입력은 문자열로 전달합니다.
{
"role": "user",
"content": "이 영상에 대해 설명해줘."
}멀티모달 입력은 분석 지시문과 자료를 Part 배열로 구성합니다.
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 전체 내용을 요약해줘."
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/clip.mp4"
}
}
]
}content Part
content가 배열일 때 각 원소를 Part라고 부릅니다. type 값으로 무엇을 넣는지 구분합니다.
| Part type | 필수 필드 | 설명 |
|---|---|---|
text |
text |
질문 또는 지시문 |
image_url |
image_url.url |
이미지 한 장 |
video_url |
video_url.url |
영상 하나 |
input_audio |
input_audio.url |
오디오 URL |
file |
file.file_url |
PDF URL / Pro 요청 예시 참고 |
텍스트, 이미지, 영상을 함께 전달하는 요청 예시입니다.
{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"messages": [
{
"role": "system",
"content": "You are a professional video analyst."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 전체 내용을 요약해줘."
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/frame.jpg"
}
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/clip.mp4"
}
}
]
}
]
}파일 크기는 100MB 미만을 권장합니다.
미디어 입력
이미지와 영상을 합쳐 요청당 최대 10개까지 전달할 수 있습니다.
| 구분 | 전달 형식 |
|---|---|
| 이미지 | 공개 http(s) URL 또는 data URL(data:image/...;base64,...). 최소 크기 14px |
| 영상 | API 서버가 접근할 수 있는 HTTP(S) URL |
| 오디오 | input_audio.url에 HTTP(S) URL 지정 |
file.file_url에 HTTP(S) URL 지정 / Pro |
https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4?q-sign-algorithm=...버전별 요청 구성
텍스트 단독 요청은 Lite 또는 Flash를 사용합니다. Pro 요청에는 이미지, 오디오, PDF 문서 또는 영상 URL을 분석 지시문과 함께 전달합니다. PDF 문서 요청 형식은 1.0 Pro 절을 참고하세요.
URL로 전달하는 자료는 API 서버에서 접근할 수 있어야 합니다. 접근이 제한된 스토리지의 자료에는 요청 처리 중 유효한 서명 URL을 사용합니다.
처리 시간
| 입력 | 처리 시간 |
|---|---|
짧은 클립 (6초) |
10초 ~ 50초 |
| 긴 영상 | 수 분 |
응답은 생성 완료 후 한 번에 반환됩니다. HTTP 타임아웃은 600초로 설정하세요.
응답 구조
{
"choices": [
{
"message": {
"role": "assistant",
"content": "...",
"reasoning_content": "..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1285,
"completion_tokens": 1211,
"total_tokens": 2496,
"completion_tokens_details": {
"reasoning_tokens": 858
},
"prompt_tokens_details": {
"audio_tokens": 36,
"cache_read_tokens": 0,
"cached_tokens": 0
}
},
"request_id": "..."
}파싱 규칙
- 본문은
choices[0].message.content입니다. - 추론 내용은
choices[0].message.reasoning_content에서 읽습니다. usage.completion_tokens_details.reasoning_tokens에 추론 토큰 수가 집계됩니다.video_tokens는 응답 형태에 따라usage또는usage.prompt_tokens_details아래에 위치할 수 있으므로 아래처럼 폴백 체인을 사용하세요.
video_tokens = usage.get("video_tokens") or (usage.get("prompt_tokens_details") or {}).get("video_tokens")JSON 응답 파싱
JSON task의 응답은 코드펜스로 감싸인 형태로 반환될 수 있습니다. 아래 파서를 사용하면 두 형태를 모두 처리할 수 있습니다.
def extract_json(text):
if not text:
return None
s = text.strip()
if s.startswith("```"):
s = s.strip("`")
if s.lower().startswith("json"):
s = s[4:]
s = s.strip()
try:
return json.loads(s)
except Exception:
start, end = s.find("{"), s.rfind("}")
if start == -1 or end <= start:
return None
try:
return json.loads(s[start:end + 1])
except Exception:
return None파싱 결과와 함께 원문(content)도 보관하면 후속 처리에 활용할 수 있습니다.
분석 작업별 요청
작업별 입력 지시문과 응답 형식은 다음과 같습니다. {q} 자리에 사용자 질문이 들어가고, 질문이 비어 있으면 기본 질문을 사용합니다. JSON task는 response_format={"type":"json_object"}를 함께 보내고 instruction 끝에 Respond with JSON only.를 덧붙입니다.
텍스트 응답
| task | 라벨 | 시스템 프롬프트 | 출력 형식 |
|---|---|---|---|
qa |
자유 질의 | You are a precise multimodal analyst. Answer factually and cite timestamps (mm:ss) when you refer to a moment in a video. |
{q}를 그대로 전달합니다 |
summary |
영상 요약 | You are a professional video analyst. Answer in Korean unless the user writes in another language. |
{q} 뒤에 출력 형식을 지정합니다1) LOGLINE 한 문장2) KEY POINTS 3~5개 불릿, 각 항목에 대략적인 타임스탬프(mm:ss)3) SUMMARY 짧은 단락 |
transcript |
음성 트랜스크립트 | You are a transcription engine. Transcribe spoken content faithfully. |
{q} 뒤에 출력 형식을 지정합니다. 발화당 한 줄 [mm:ss] speaker: text. 무음 입력에서는 NO_SPEECH를 반환하고 오디오를 대신 묘사합니다 |
JSON 응답
| task | 라벨 | 시스템 프롬프트 | 반환 스키마 |
|---|---|---|---|
chapters |
타임라인 챕터 | You are a video chaptering engine. Return strictly valid JSON, no prose. |
{"duration_sec": <int>, "chapters":[{"start":"mm:ss","end":"mm:ss","title":"","summary":""}]} |
highlights |
하이라이트 | You are a highlight detection engine for short-form clipping. Return strictly valid JSON, no prose. |
{"highlights":[{"start":"mm:ss","end":"mm:ss","score":<0-100>,"reason":""}]} |
storyboard |
샷 분석 | You are a shot-breakdown engine. Return strictly valid JSON, no prose. |
{"shots":[{"start":"mm:ss","end":"mm:ss","shot_type":"","camera":"","action":"","description":""}]} |
tagging |
태깅, 분류 | You are a content tagging engine for a media catalogue. Return strictly valid JSON, no prose. |
{"categories":[],"tags":[],"keywords":[],"mood":[],"objects":[],"safe_for_work":<true|false>} |
ocr |
화면 텍스트 | You are an OCR engine for video frames. Return strictly valid JSON, no prose. |
{"texts":[{"time":"mm:ss","text":"","kind":"subtitle|signage|ui|other"}]} |
moderation |
콘텐츠 리뷰 | You are a content moderation reviewer. Return strictly valid JSON, no prose. |
{"risk_level":"low|medium|high","categories":[],"evidence":[{"time":"mm:ss","reason":""}],"verdict":""} |
metadata |
배포 메타데이터 | You are a publishing metadata generator for a VOD catalogue. Return strictly valid JSON, no prose. |
{"title":"","logline":"","description":"","tags":[],"category":"","thumbnail_timecode":"mm:ss"} |
기본 지시문은 분석 작업에 맞춰 설정합니다. qa는 "이 영상에 대해 설명해줘.", summary는 "이 영상의 전체 내용을 요약해줘.", chapters는 "이 영상을 장면 단위로 챕터 분할해줘."를 사용합니다.
시스템 프롬프트에 응답 언어와 형식을 지정합니다. JSON task에서는 반환 스키마를 instruction 쪽에 유지하는 편이 안정적입니다.
영상 요약 (flash)
curl -sS -X POST https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer $AIGC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"messages": [
{
"role": "system",
"content": "You are a professional video analyst. Answer in Korean unless the user writes in another language."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 전체 내용을 요약해줘."
},
{
"type": "video_url",
"video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4?q-sign-algorithm=..."
}
}
]
}
]
}'
import requests
ENDPOINT = "https://mmu.vod-qcloud.com/v1/chat/completions"
TOKEN = "<VOD AIGC Token>"
body = {
"model": "wand-vega-vl-1.0-flash",
"stream": False,
"messages": [
{"role": "system", "content": "You are a professional video analyst. Answer in Korean unless the user writes in another language."},
{"role": "user", "content": [
{"type": "text", "text": "이 영상의 전체 내용을 요약해줘."},
{"type": "video_url", "video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"}},
]},
],
}
r = requests.post(ENDPOINT, json=body,
headers={"Authorization": f"Bearer {TOKEN}"}, timeout=600)
msg = r.json()["choices"][0]["message"]
print(msg.get("content") or "")
하이라이트 추출, JSON (flash)
curl -sS -X POST https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer $AIGC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wand-vega-vl-1.0-flash",
"stream": false,
"response_format": {
"type": "json_object"
},
"messages": [
{
"role": "system",
"content": "You are a highlight detection engine for short-form clipping. Return strictly valid JSON, no prose."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "숏폼 클립으로 쓸 만한 하이라이트 구간을 뽑아줘.\n\nReturn ONLY valid JSON:\n{\"highlights\":[{\"start\":\"mm:ss\",\"end\":\"mm:ss\",\"score\":<0-100>,\"reason\":\"\"}]}\nRespond with JSON only."
},
{
"type": "video_url",
"video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
}
}
]
}
]
}'
import json, requests
ENDPOINT = "https://mmu.vod-qcloud.com/v1/chat/completions"
TOKEN = "<VOD AIGC Token>"
instruction = (
"숏폼 클립으로 쓸 만한 하이라이트 구간을 뽑아줘.\n\n"
"Return ONLY valid JSON:\n"
'{"highlights":[{"start":"mm:ss","end":"mm:ss","score":<0-100>,"reason":""}]}\n'
"Respond with JSON only."
)
body = {
"model": "wand-vega-vl-1.0-flash",
"stream": False,
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "You are a highlight detection engine for short-form clipping. Return strictly valid JSON, no prose."},
{"role": "user", "content": [
{"type": "text", "text": instruction},
{"type": "video_url", "video_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"}},
]},
],
}
r = requests.post(ENDPOINT, json=body,
headers={"Authorization": f"Bearer {TOKEN}"}, timeout=600)
content = r.json()["choices"][0]["message"]["content"]
print(json.dumps(extract_json(content), ensure_ascii=False, indent=2))
이미지 태깅, JSON (pro)
curl -sS -X POST https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer $AIGC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "wand-vega-vl-1.0-pro",
"stream": false,
"response_format": {
"type": "json_object"
},
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 이미지의 태그를 뽑아줘. Respond with JSON only."
},
{
"type": "image_url",
"image_url": {
"url": "https://<cdn>/frame.jpg"
}
}
]
}
]
}'
import json, requests
ENDPOINT = "https://mmu.vod-qcloud.com/v1/chat/completions"
TOKEN = "<VOD AIGC Token>"
body = {
"model": "wand-vega-vl-1.0-pro",
"stream": False,
"response_format": {"type": "json_object"},
"messages": [
{"role": "user", "content": [
{"type": "text", "text": "이 이미지의 태그를 뽑아줘. Respond with JSON only."},
{"type": "image_url", "image_url": {"url": "https://<cdn>/frame.jpg"}},
]},
],
}
r = requests.post(ENDPOINT, json=body,
headers={"Authorization": f"Bearer {TOKEN}"}, timeout=600)
content = r.json()["choices"][0]["message"]["content"]
print(json.dumps(extract_json(content), ensure_ascii=False, indent=2))
메시지 역할 설정
Messages 구조
Vega-VL 호출에서 messages는 모델에게 전달하는 대화 목록입니다. 각 메시지는 role과 content를 중심으로 구성합니다.
role은 메시지의 성격을 나타냅니다. 일반적인 Vega-VL 호출에서는 system과 user만 사용해도 충분합니다. system에는 모델이 어떤 방식으로 답변해야 하는지에 대한 기본 규칙을 넣고, user에는 실제 질문과 분석할 자료를 지정합니다.
예를 들어 영상 요약 요청에서는 system에 “전문 영상 분석가처럼 답변하고 한국어로 답변하라”는 규칙을 넣고, user에 “이 영상의 전체 내용을 요약해줘”라는 질문과 영상 URL을 함께 지정합니다.
messages 필드
| 필드 | 타입 | 설명 |
|---|---|---|
role |
String | 메시지의 성격을 나타냅니다. system / developer / user / assistant / tool 값을 사용할 수 있습니다. 일반적인 이미지/영상 분석 요청에서는 주로 system과 user를 사용합니다. |
content |
String 또는 Array<Part> | 메시지의 실제 내용입니다. 텍스트만 보낼 때는 문자열로 입력할 수 있고, 이미지, 오디오, 파일, 영상을 함께 보낼 때는 Part 배열로 구성합니다. |
tool_calls |
Array | role=assistant의 도구 호출 및 파라미터 정보 |
tool_call_id |
String | role=tool일 때 어떤 도구 호출 결과인지 연결하는 ID입니다. 도구 호출 기능을 사용할 때만 필요합니다. |
role 설명
| role | 설명 | 사용 예 |
|---|---|---|
system |
모델의 기본 역할과 답변 규칙을 정합니다. 답변 언어, 출력 형식, 분석 방식 등을 지정할 때 사용합니다. | You are a professional video analyst. Answer in Korean. |
developer |
서비스 개발자가 내부 규칙을 별도로 지정할 때 사용합니다. 일반적인 호출에서는 생략할 수 있습니다. | Return timestamps in mm:ss format. |
user |
실제 사용자의 질문이나 분석 요청을 담습니다. 이미지, 오디오, 파일, 영상도 user 메시지의 content에 함께 지정합니다. |
이 영상의 전체 내용을 요약해줘. |
assistant |
모델의 이전 답변을 대화 이력으로 전달 | 이전 답변에 이어 후속 질문을 할 때 |
tool |
외부 도구의 실행 결과를 모델에 전달 | 도구 호출 결과 전달 |
role 사용 예시
가장 기본적인 Vega-VL 호출은 system과 user로 구성합니다.
{
"model": "wand-vega-vl-1.0-flash",
"messages": [
{
"role": "system",
"content": "You are a professional video analyst. Answer in Korean unless the user writes in another language."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 전체 내용을 요약해줘."
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/video.mp4"
}
}
]
}
],
"stream": false
}위 예시에서 system은 모델의 답변 방식을 정합니다.user는 실제 요청과 분석할 영상을 전달합니다.
메시지별 역할은 다음과 같습니다.
system: 전문 영상 분석가처럼 답변하고, 한국어로 답변한다.user: 전달된 영상을 보고 전체 내용을 요약한다.
content 구성 방식
content는 텍스트만 보낼 때와 멀티모달 입력을 보낼 때 형식이 다릅니다.
텍스트만 보낼 때는 문자열을 사용할 수 있습니다.
{
"role": "user",
"content": "이 영상에 대해 설명해줘."
}이미지, 오디오, 파일, 영상을 함께 보낼 때는 Part 배열을 사용합니다.
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 영상의 전체 내용을 요약해줘."
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/video.mp4"
}
}
]
}Part 객체
content가 배열일 때 각 요소는 Part 객체입니다. Part는 type 값으로 입력 종류를 구분합니다.
| type | 필수 필드 | 설명 |
|---|---|---|
text |
text |
질문 또는 지시문을 전달합니다. |
image_url |
image_url.url |
이미지 URL 또는 data URL을 전달합니다. |
video_url |
video_url.url |
영상 URL을 전달합니다. |
input_audio |
input_audio.url |
오디오 URL을 전달합니다. |
file |
file.file_url |
PDF URL을 전달합니다. Pro 요청 예시를 참고하세요. |
일반적인 작성 방식
영상 요약, 하이라이트 추출, OCR, 태깅처럼 Vega-VL을 사용하는 대부분의 요청은 아래 구조를 사용하면 됩니다.
{
"role": "system",
"content": "You are a professional video analyst. Answer in Korean unless the user writes in another language."
}{
"role": "user",
"content": [
{ "type": "text", "text": "이 영상의 전체 내용을 요약해줘." },
{ "type": "video_url", "video_url": { "url": "https://example.com/video.mp4" } }
]
}assistant / tool / tool_calls / tool_call_id는 대화 이력 / 도구 호출에 사용합니다. 기본 분석 요청은 system과 user로 구성합니다.
