API Reference

VOD의 인증, 요청 구조, 태스크 조회와 저장 규격입니다. 모델별 값과 예시는 왼쪽 엔진 메뉴에서 확인합니다.

호출 규격

텍스트 모델은 Bearer 인증과 https://mmu.vod-qcloud.com을 사용합니다. Text 호출 규격을 참조하세요.

생성 / 조회 액션

MPS와 달리 조회 액션이 하나로 통합되어 있습니다.

요청 실행

TC3 호출 스크립트를 tencent-api.py로 저장합니다. Python 3 표준 라이브러리만 사용하며, 매 요청마다 현재 시각과 본문으로 서명을 계산합니다. TENCENT_SECRET_ID / TENCENT_SECRET_KEY 환경변수를 설정한 뒤 엔진 페이지의 JSON을 request.json으로 저장하세요.

python3 tencent-api.py vod CreateAigcImageTask request.json

python3 tencent-api.py vod CreateAigcVideoTask request.json

python3 tencent-api.py vod CreateAigcAudioTask request.json

POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAigcImageTask
X-TC-Version: 2018-07-17
X-TC-Timestamp: <unix-timestamp>
X-TC-Region: ap-guangzhou
Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/vod/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=<Signature>

생성 요청에는 실제 사용 요금이 발생합니다. 타임아웃으로 접수 여부가 불명확하면 중복 생성 전에 태스크 상태를 확인합니다. 임시 자격 증명은 TENCENT_TOKEN, 리전은 --region으로 지정할 수 있습니다.

API 목록과 요청 파라미터

공통 필드

FileInfos.N의 Usage는 참조 목적을 나타냅니다.

끝 프레임 지원 모델은 FileInfos.N.Usage=LastFrame을 사용합니다. LastFrameUrl / LastFrameFileId는 이전 연동과의 호환 필드입니다.

응답과 실행 흐름

태스크 조회

DescribeTaskDetail로 조회합니다. Status="FINISH"와 ErrCode=0을 함께 확인합니다.

python3 tencent-api.py vod DescribeTaskDetail query.json

query.json:

{
  "SubAppId": 0,
  "TaskId": "<task-id>"
}

접수 응답

{
  "Response": {
    "TaskId": "<task-id>",
    "RequestId": "<request-id>"
  }
}

TaskId는 후속 조회에 사용하고, RequestId는 요청 추적에 사용합니다.

응답 예시

{
  "AigcImageTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Progress": 100,
    "Output": {
      "FileInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcImageGenFile.png",
          "ExpireTime": "2026-08-01T10:29:48Z",
          "MetaData": {
            "Width": 1024,
            "Height": 1024,
            "Container": "png"
          }
        }
      ]
    }
  }
}

{
  "AigcVideoTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Progress": 100,
    "Output": {
      "FileInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcVideoGenFile.mp4",
          "ExpireTime": "2026-08-01T10:29:48Z",
          "MetaData": {
            "Width": 1920,
            "Height": 1080,
            "Duration": 5.07,
            "Container": "mov,mp4,m4a",
            "Bitrate": 9494850
          }
        }
      ]
    }
  }
}

{
  "AigcAudioTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Output": {
      "AudioInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcAudioGenFile.mp3"
        }
      ]
    }
  }
}

오류와 호출 제한

응답의 HTTP 상태, 오류 코드 및 요청 식별자를 함께 확인하십시오. 인증·권한 오류는 설정을 확인한 뒤 다시 요청하고, 작업 또는 리소스가 생성된 경우에는 재제출 전에 현재 상태를 조회하십시오. API별 제한과 오류 코드는 아래 관련 문서를 참조하십시오.

요청 예제

호출할 모델 또는 프로토콜의 요청 예제를 사용하십시오. 서로 다른 경로의 인증 방식과 요청 필드를 한 요청에 혼합하지 마십시오. 아래 엔진 문서와 프로토콜별 파라미터를 함께 확인하십시오.

결과·리소스 관리

결과 저장

MPS 경로의 12시간보다 길고, Permanent를 사용하면 VOD 미디어로 그대로 관리할 수 있습니다.

{
  "OutputConfig": {
    "StorageMode": "Permanent"
  }
}

가드레일 해제

영상에서는 Kling / Vidu / Wan / Happyhorse / Hailuo H3에 적용할 수 있습니다. Hailuo의 다른 버전에는 적용하지 않습니다. Vega Video의 지원 범위는 해당 엔진 문서를 참조하세요. VS에는 적용되지 않습니다. Hy Image에는 적용되지 않습니다.

가드레일 해제 파라미터를 사용하려면 먼저 영업담당자에게 연락해 사용 권한을 확인해야 합니다. 지원 엔진에서도 해당 파라미터를 명시적으로 전달하는 경우에만 가드레일 해제가 적용됩니다. 파라미터를 생략하면 해제되지 않습니다.

다음 설정을 기존 생성 요청에 병합합니다. 입력과 출력 심사를 모두 해제하려면 두 필드를 함께 전달합니다.

{
  "OutputConfig": {
    "InputComplianceCheck": "Disabled",
    "OutputComplianceCheck": "Disabled"
  }
}

MPS는 ExtraParameters의 Boolean 값을 사용합니다. VOD의 OutputConfig와 문자열 Disabled를 그대로 MPS에 전달하지 마세요. MPS API Reference를 참조하세요.

엔진 카탈로그·관련 문서

Image

VOD 경로로 호출하는 이미지 생성입니다. 액션은 CreateAigcImageTask, 결과 조회는 DescribeTaskDetail입니다. MPS 경로(mps-image)와 액션 이름은 같지만 파라미터 구조가 다릅니다.

Vega Image 연동

Vega Image의 VOD 요청 규격과 생성 예시는 Vega Image를 참조하세요.

MPS 경로와의 차이

지원 엔진

Seedream 5.0-pro는 MPS 전용

5.0-pro는 MPS 경로에서만 허용됩니다. VOD 경로에서는 5.0-lite / 4.5 / 4.0을 사용하세요.

공통 요청 파라미터

OutputConfig

ExtInfo

이미지 생성도 영상과 같은 2중 JSON 인코딩을 사용합니다.

{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\":\\\"1536x1024\\\"}\"}"
}

Video

VOD 경로로 호출하는 영상 생성입니다. 액션은 CreateAigcVideoTask, 결과 조회는 DescribeTaskDetail입니다.

MPS 경로와의 차이

같은 엔진 이름을 쓰더라도 파라미터를 넣는 자리가 다릅니다.

지원 엔진

공통 요청 파라미터

FileInfos.N

참조 입력을 모두 FileInfos 하나로 처리합니다. Category로 종류를, Usage로 역할을 구분합니다.

Usage는 참조마다 붙입니다

다중 참조에서는 모든 항목에 Usage를 지정해야 합니다. 일부만 지정하면 나머지 항목이 무시될 수 있습니다.

OutputConfig

ExtInfo

엔진 전용 파라미터는 ExtInfo에 2중 JSON 인코딩으로 지정합니다. ExtInfo 자체가 JSON 문자열이고, 그 안의 AdditionalParameters 값도 JSON 문자열입니다.

{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true}\"}"
}

생성 순서는 다음과 같습니다.

import json
params = {"multi_shot": True}
inner = json.dumps(params, ensure_ascii=False)              # 1차 직렬화
ext = json.dumps({"AdditionalParameters": inner}, ensure_ascii=False)  # 2차 직렬화

서비스별 확장 파라미터

MPS는 최상위 AdditionalParameters에 JSON 문자열을 넣고, VOD는 ExtInfo 안에 인코딩합니다.

후처리: 업스케일 출력

생성 결과를 Permanent로 저장해 FileId를 확보한 뒤 VOD 업스케일 출력 템플릿 또는 워크플로로 후처리합니다.

신규 안내와 호출 범위

GV의 3.1-lite는 VOD 상세 호출 규격 확인이 필요한 버전입니다. VOD GV 상세를 확인하세요.

Music

Mureka / EL 음악 / 음향 효과

VOD 경로로 호출하는 오디오 생성입니다. 액션은 CreateAigcAudioTask, 결과 조회는 DescribeTaskDetail입니다. 씬은 sfx(음향 효과)와 music(음악) 두 가지이며, 씬과 엔진은 고정 매핑을 따릅니다.

MPS 경로와의 차이

오디오 확장 파라미터

오디오 확장 파라미터는 VOD / MPS 모두 최상위 AdditionalParameters에 지정합니다.

지원 엔진

요청 파라미터

OutputConfig

AdditionalParameters

모델별 옵션을 담은 JSON 문자열입니다. Kling, MiniMaxMusic, Tme, Mureka의 상세 필드를 확인합니다.

3D

3D 전용 모델 / 모드 / 입출력 사양은 Hy 3D Panorama와 Hy World Model에서 확인합니다. 인증 / 태스크 상태 / 저장 정책은 이 문서의 공통 규격을 따릅니다.