Media AI AgentLast Updated 2026-09-30

Media AI Agent API Reference

On this page

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 서명으로 호출합니다.

LANGUAGE
{
  "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으로 파싱합니다. 다음은 실행 시작 이벤트의 데이터입니다.

LANGUAGE
{
  "type": "RUN_STARTED",
  "timestamp": 1784102011155,
  "threadId": "thread-001",
  "runId": "run-001"
}

텍스트는 messageId별로 delta를 누적합니다.

LANGUAGE
{
  "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`	오류 내용과 실행 식별자를 기록하고 실패 상태 표시

이력 조회

LANGUAGE
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는 조회 종료를 뜻합니다.

실행 취소

LANGUAGE
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별 제한과 오류 코드는 아래 관련 문서를 참조하십시오.

요청 예제

요청 예시

LANGUAGE
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에서는 고위험 도구 실행 전 승인을 요청합니다. 승인 대기 이벤트의 데이터 예시입니다.

LANGUAGE
{
  "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는 한 번씩만 지정합니다.

LANGUAGE
{
  "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를 등록합니다.

LANGUAGE
{
  "name": "lookup_product",
  "description": "상품 코드로 승인된 상품 설명을 조회합니다.",
  "parameters": {
    "type": "object",
    "properties": {
      "productCode": {
        "type": "string"
      }
    },
    "required": [
      "productCode"
    ]
  }
}

이 객체를 요청의 tools 배열에 넣습니다. 도구 호출을 받으면 등록된 함수의 입력을 검증하고 실행한 뒤, 아래 형식으로 결과를 전달합니다. 같은 threadId와 도구 정의, 시나리오를 유지합니다.

LANGUAGE
{
  "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로도 전달됩니다. 미처리 외부 도구 호출이 있는지 함께 확인합니다.