Media AI Agent API Reference
Endpoint: https://smartmedia.vod-qcloud.com/agui인증: VOD ApiToken / Bearer
VOD Media AI Agent의 인증, 메시지, 스트리밍 응답과 실행 관리 규격입니다. 영상 제작과 미디어 질의응답에 공통으로 적용합니다.
호출 규격
기본 정보
| 항목 | 값 |
|---|---|
| 호스트 | smartmedia.vod-qcloud.com |
| 인증 | Authorization: Bearer $VOD_API_TOKEN |
| 요청 형식 | application/json |
| 실행 응답 | SSE / AG-UI 이벤트 |
| 실행 / 재개 | POST /agui/chat |
| 메시지 이력 | POST /agui/history |
| 실행 취소 | POST /agui/cancel |
호출 준비
VOD 애플리케이션의 SubAppId를 지정해 API 키를 먼저 발급합니다. 키 발급은 vod.intl.tencentcloudapi.com의 CreateAigcApiToken을 TC3 서명으로 호출합니다.
{
"SubAppId": 123456789
}응답의 ApiToken을 Agent 요청의 Bearer 키로 사용합니다. 키는 선택한 애플리케이션에 연결되며, fileId로 전달하는 VOD 소재도 같은 애플리케이션에 있어야 합니다. 외부 소재는 URL로 전달할 수 있습니다.
키 발급과 관리는 VOD API 키 발급을 참고하세요. 키 발급용 TC3 서명은 Agent 요청 본문에 넣지 않습니다.
API 목록과 요청 파라미터
요청 파라미터
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
threadId | 필수 | String | 대화 ID. 같은 대화의 문맥 공유 |
runId | 필수 | String | 현재 실행의 고유 ID |
messages | 필수 | Array | 사용자 메시지 또는 외부 도구 결과 |
forwardedProps | 필수 | Object | 시나리오, 모델 및 실행 옵션 |
tools | 선택 | Array | 클라이언트에서 실행할 외부 도구 |
resume | 선택 | Array | 승인 대기 중인 도구의 승인 / 거절 결과 |
실행 옵션
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
forwardedProps.model | 선택 | String | Vega Agent 모델 ID |
forwardedProps.scenario_name | 필수 | String | video-mixcut / video-qa |
forwardedProps.approval_mode | 선택 | String | never / level:high. 기본값 never |
forwardedProps.database | 선택 | String | video-qa의 지식베이스 이름. 기본값 default |
메시지
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
messages.role | 필수 | String | 사용자 입력 user / 외부 도구 결과 tool |
messages.content | 필수 | String / Array | 텍스트 또는 ContentPart 배열 |
messages.toolCallId | 조건부 필수 | String | role: tool일 때 원래 도구 호출 ID |
소재 입력
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
type | 필수 | String | text / mixcut_assets |
text | 조건부 필수 | String | type: text의 제작 지시 |
metadata | 조건부 필수 | Object | type: mixcut_assets의 소재 정보 |
metadata.attachments | 조건부 필수 | Array | 소재 목록 |
metadata.attachments.url | 조건부 필수 | String | 외부 소재 URL. 같은 항목의 fileId와 택일 |
metadata.attachments.fileId | 조건부 필수 | String | VOD 파일 ID. 같은 항목의 url과 택일 |
응답과 실행 흐름
응답 이벤트
| 이벤트 | 설명 |
|---|---|
RUN_STARTED | 실행 시작 |
TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END | 답변 메시지 시작 / 텍스트 추가 / 종료 |
REASONING_START / REASONING_END | 추론 단계 시작 / 종료 |
REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENT / REASONING_MESSAGE_END | 추론 메시지 시작 / 내용 추가 / 종료 |
TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END | 도구 호출 시작 / 인수 추가 / 호출 정보 전달 완료 |
TOOL_CALL_RESULT | 도구 실행 결과 |
RUN_FINISHED | 현재 실행 종료 또는 승인 / 외부 도구 결과 대기 |
RUN_ERROR | 실행 오류 |
MESSAGES_SNAPSHOT | 이력 조회의 전체 메시지 스냅샷 |
이벤트 데이터 예시
SSE의 data 필드를 JSON으로 파싱합니다. 다음은 실행 시작 이벤트의 데이터입니다.
{
"type": "RUN_STARTED",
"timestamp": 1784102011155,
"threadId": "thread-001",
"runId": "run-001"
}텍스트는 messageId별로 delta를 누적합니다.
{
"type": "TEXT_MESSAGE_CONTENT",
"timestamp": 1784102019050,
"messageId": "msg-002",
"delta": "선택한 소재를 바탕으로 편집 구성을 준비합니다."
}도구 인수는 toolCallId별로 TOOL_CALL_ARGS.delta를 누적한 뒤 JSON으로 파싱합니다. TOOL_CALL_END는 호출 정보 전달의 종료이며, 도구 실행 결과는 TOOL_CALL_RESULT에서 확인합니다.
실행 상태 구분
| 수신 상태 | 처리 |
|---|---|
RUN_FINISHED + outcome.type: interrupt | 승인 대기 항목을 표시하고 resume으로 결정 전달 |
외부 도구 호출 후 RUN_FINISHED | 클라이언트에서 도구 실행 후 결과 전달 |
처리할 승인 / 외부 도구 호출이 없는 RUN_FINISHED | 현재 실행 종료. 메시지와 도구 결과에서 최종 산출물 확인 |
RUN_ERROR | 오류 내용과 실행 식별자를 기록하고 실패 상태 표시 |
이력 조회
curl -N -sS https://smartmedia.vod-qcloud.com/agui/history \
-H "Authorization: Bearer $VOD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"threadId": "thread-001",
"runId": "history-001",
"forwardedProps": {
"scenario_name": "video-mixcut"
}
}'threadId와 조회 요청의 runId를 전달합니다. 응답은 SSE이며, MESSAGES_SNAPSHOT 이벤트의 messages에 대화의 전체 메시지가 포함됩니다. 재접속 시 이 스냅샷으로 화면을 복원합니다. 이력 조회 응답의 RUN_FINISHED는 조회 종료를 뜻합니다.
실행 취소
curl -sS https://smartmedia.vod-qcloud.com/agui/cancel \
-H "Authorization: Bearer $VOD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"threadId": "thread-001",
"runId": "cancel-001",
"forwardedProps": {
"scenario_name": "video-mixcut"
}
}'브라우저를 닫거나 SSE 연결을 끊는 동작만으로 실행이 취소되지는 않습니다. 중단하려면 취소 API를 호출합니다.
오류와 호출 제한
응답의 HTTP 상태, 오류 코드 및 요청 식별자를 함께 확인하십시오. 인증·권한 오류는 설정을 확인한 뒤 다시 요청하고, 작업 또는 리소스가 생성된 경우에는 재제출 전에 현재 상태를 조회하십시오. API별 제한과 오류 코드는 아래 관련 문서를 참조하십시오.
요청 예제
요청 예시
curl -N -sS https://smartmedia.vod-qcloud.com/agui/chat \
-H "Authorization: Bearer $VOD_API_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.json두 영상 연결 요청 JSON을 request.json으로 저장합니다. 전체 구성은 Vega Agent 요청 예시를 참고하세요.
결과·리소스 관리
선택 기능
영상 연결 예제는 아래 설정 없이 실행할 수 있습니다. 승인 단계나 외부 시스템 연동이 필요할 때 사용합니다.
승인과 재개 approval_mode: level:high에서는 고위험 도구 실행 전 승인을 요청합니다. 승인 대기 이벤트의 데이터 예시입니다. { "type": "RUN_FINISHED", "threadId": "thread-001", "runId": "run-001", "outcome": { "type": "interrupt", "interrupts": [ { "id": "interrupt-001", "reason": "tool_call", "message": "편집안을 적용해 완성 영상을 렌더링합니다.", "toolCallId": "call-001", "responseSchema": { "type": "object", "properties": { "feedback": { "type": "string" } } } } ] } } 재개 파라미터 파라미터 필수 타입 설명 resume.interruptId 필수 String 승인 요청의 interrupts.id resume.status 필수 String 승인 resolved / 거절 cancelled resume.payload 선택 Object 결정에 대한 추가 정보 resume.payload.feedback 선택 String 수정 요청 또는 거절 이유 같은 threadId에서 새 runId로 재개합니다. 처음 요청한 approval_mode와 scenario_name을 유지하고, 각 승인 대기 ID는 한 번씩만 지정합니다. { "threadId": "thread-001", "runId": "run-002", "messages": [ { "role": "user", "content": "" } ], "forwardedProps": { "model": "wand-vega-agent-1.0-pro", "scenario_name": "video-mixcut", "approval_mode": "level:high" }, "resume": [ { "interruptId": "interrupt-001", "status": "resolved" } ] } 외부 도구 외부 도구는 Agent가 호출을 결정하고 클라이언트가 실행하는 함수입니다. tools에 이름, 설명과 JSON Schema를 등록합니다. { "name": "lookup_product", "description": "상품 코드로 승인된 상품 설명을 조회합니다.", "parameters": { "type": "object", "properties": { "productCode": { "type": "string" } }, "required": [ "productCode" ] } } 이 객체를 요청의 tools 배열에 넣습니다. 도구 호출을 받으면 등록된 함수의 입력을 검증하고 실행한 뒤, 아래 형식으로 결과를 전달합니다. 같은 threadId와 도구 정의, 시나리오를 유지합니다. { "threadId": "thread-001", "runId": "run-003", "messages": [ { "role": "tool", "toolCallId": "call-ext-001", "content": "상품 코드 P100: 휴대용 무선 스피커. 색상은 검정." } ], "forwardedProps": { "model": "wand-vega-agent-1.0-pro", "scenario_name": "video-mixcut", "approval_mode": "never" }, "tools": [ { "name": "lookup_product", "description": "상품 코드로 승인된 상품 설명을 조회합니다.", "parameters": { "type": "object", "properties": { "productCode": { "type": "string" } }, "required": [ "productCode" ] } } ] } 외부 도구 결과 대기는 outcome 없는 RUN_FINISHED로도 전달됩니다. 미처리 외부 도구 호출이 있는지 함께 확인합니다.