Moonheart Docs

简体中文

English
ไทย

简体中文

English
ไทย

主题

API Reference ​

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

호출 규격 ​

항목값
요청POST https://vod.intl.tencentcloudapi.com
API 버전2018-07-17
인증TC3-HMAC-SHA256 / SecretId / SecretKey
Content-Typeapplication/json; charset=utf-8
공통 헤더X-TC-Action / X-TC-Version / X-TC-Timestamp / X-TC-Region

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

생성 / 조회 액션 ​

구분액션용도
생성CreateAigcImageTask이미지 생성
생성CreateAigcVideoTask영상 생성, 3D 씬 생성
생성CreateAigcAudioTask음향 효과, 음악 생성
조회DescribeTaskDetail모든 AIGC 태스크 공통 조회

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

요청 실행 ​

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

bash
python3 tencent-api.py vod CreateAigcImageTask request.json
bash
python3 tencent-api.py vod CreateAigcVideoTask request.json
bash
python3 tencent-api.py vod CreateAigcAudioTask request.json
http
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 목록과 요청 파라미터 ​

공통 필드 ​

파라미터필수타입설명
SubAppId선택IntegerVOD Application ID. 신규 Application은 실제 ID를 지정합니다.
ModelName필수String엔진 이름
ModelVersion선택String엔진 버전. 생략 시 기본 버전
Prompt필수String생성 프롬프트
SceneType선택String특수 모드 지정
FileInfos.N선택Array참조 입력. Type / Category / Usage / Url
OutputConfig선택ObjectResolution / Duration / AspectRatio / StorageMode 등
ExtInfo선택String고급 옵션. 2중 JSON 인코딩 문자열

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

Usage의미
FirstFrame첫 프레임
Reference참조 입력
LastFrame끝 프레임

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

응답과 실행 흐름 ​

태스크 조회 ​

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

bash
python3 tencent-api.py vod DescribeTaskDetail query.json

query.json:

json
{
  "SubAppId": 0,
  "TaskId": "<task-id>"
}
Status처리
WAITING / PROCESSING폴링 계속
FINISHErrCode=0이면 성공. 오류 시 Message 확인
유형상태결과 URL
ImageAigcImageTask.StatusAigcImageTask.Output.FileInfos.FileUrl
VideoAigcVideoTask.StatusAigcVideoTask.Output.FileInfos.FileUrl
MusicAigcAudioTask.StatusAigcAudioTask.Output.AudioInfos.FileUrl

접수 응답 ​

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

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

응답 예시 ​

json
{
  "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"
          }
        }
      ]
    }
  }
}
json
{
  "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
          }
        }
      ]
    }
  }
}
json
{
  "AigcAudioTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Output": {
      "AudioInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcAudioGenFile.mp3"
        }
      ]
    }
  }
}

오류와 호출 제한 ​

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

요청 예제 ​

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

결과·리소스 관리 ​

결과 저장 ​

StorageMode유효 기간
Temporary7일
Permanent영구. VOD 미디어 자산으로 등록

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

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

가드레일 해제 ​

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

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

파라미터해제 값적용 대상
OutputConfig.InputComplianceCheckDisabled입력 심사 해제
OutputConfig.OutputComplianceCheckDisabled출력 심사 해제

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

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

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

엔진 카탈로그·관련 문서 ​

Image ​

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

WAND-Vega-Image 연동

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

MPS 경로와의 차이 ​

구분VOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API 버전2018-07-172019-06-12
참조 이미지FileInfos.N (Type + Url)ImageInfos.N (ImageUrl)
해상도 / 비율OutputConfig.Resolution / OutputConfig.AspectRatioExtraParameters.Resolution / ExtraParameters.AspectRatio
출력 장수OutputConfig.OutputImageCountOutputImageCount (최상위)
엔진 전용 파라미터ExtInfo = {"AdditionalParameters": "<JSON 문자열>"} (2중 인코딩)AdditionalParameters (JSON 문자열, 1중)
결과 조회DescribeTaskDetailDescribeAigcImageTask
상태 값FINISH + ErrCode=0WAIT / RUN / DONE / FAIL
결과 URLOutput.FileInfos.FileUrl + ExpireTimeImageInfos.Url (COS 프리사인, 12시간)

지원 엔진 ​

엔진ModelNameModelVersion
Nano BananaGEM3.1 / 3.1-lite / 3.0 / 2.5
HunyuanHunyuan3.5-preview / 3.0
WAND-Vega-Imagewand-vega-image1.0-pro / 1.0-flash / 1.0-lite
QwenQwen0925
SeedreamSeedream5.0-lite / 4.5 / 4.0
KlingKling3.0-Omni / 3.0 / O1 / 2.1
JimengJimeng4.0
MidjourneyMJv8.2 / v8.1 / v7 / niji_7
ViduViduq2
Image2OGimage2_* / image2.5_sunburst_* / image2.5_flare_*

Seedream 5.0-pro는 MPS 전용

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

공통 요청 파라미터 ​

파라미터필수타입설명
SubAppId선택IntegerVOD 애플리케이션 ID
ModelName필수String엔진 이름
ModelVersion선택String엔진 버전
Prompt선택String생성 프롬프트. 텍스트 입력 모드에서는 필수
NegativePrompt선택String네거티브 프롬프트
SceneType선택String3d_panorama(Hunyuan 파노라마), image_expand(Kling 확장) 등
FileInfos.N선택Array참조 이미지. ReferenceType=mask로 마스크 지정
OutputConfig선택Object출력 설정
ExtInfo선택String엔진 전용 확장 파라미터
SessionId선택String중복 제거용 키
SessionContext선택String콜백 투과 값. 최대 1000자
OutputConfig ​
필드설명
Resolution1K / 2K / 4K 등. 엔진별 허용 값이 다름
AspectRatio1:1 / 16:9 / 9:16 / 4:3 / 3:4 등
OutputImageCount출력 장수. 모델별 허용 범위는 상세 문서 참조
OutputFormatjpeg / png / webp. 미지정 시 모델 기본값
StorageModeTemporary(7일) / Permanent
MediaNameStorageMode=Permanent일 때 미디어 이름
PersonGenerationAllowAdult / Disallowed. 인물 생성 허용 여부
InputComplianceCheckDisabled 시 지원 엔진의 입력 심사 해제. Hy Image 제외. 사용 전 영업담당자 문의
OutputComplianceCheckDisabled 시 지원 엔진의 출력 심사 해제. Hy Image 제외. 사용 전 영업담당자 문의
ExtInfo ​

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

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

Video ​

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

MPS 경로와의 차이 ​

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

구분VOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API 버전2018-07-172019-06-12
첫 프레임FileInfos.N + Usage=FirstFrameImageUrl
끝 프레임FileInfos.N + Usage=LastFrame, 또는 LastFrameUrlLastImageUrl
다중 참조 이미지FileInfos.N (Category + Usage)ImageInfos.N
참조 영상FileInfos.N + Category=VideoVideoInfos.N
영상 길이OutputConfig.Duration최상위 Duration
해상도 / 비율OutputConfig.Resolution / OutputConfig.AspectRatioExtraParameters.Resolution / ExtraParameters.AspectRatio
음성 동시 생성OutputConfig.AudioGenerationExtraParameters.EnableAudio
엔진 전용 파라미터ExtInfo = {"AdditionalParameters": "<JSON 문자열>"} (2중 인코딩)AdditionalParameters (JSON 문자열, 1중)
결과 조회DescribeTaskDetailDescribeAigcVideoTask
상태 값FINISH + ErrCode=0WAIT / RUN / DONE / FAIL
결과 URLOutput.FileInfos.FileUrl + ExpireTimeVideoInfos.Url (COS 프리사인, 12시간)

지원 엔진 ​

엔진ModelName대표 ModelVersion
Vegawand-vega-video1.5-pro / 1.0-pro / 1.0-lite
KlingKling3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6
ViduViduq3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 / 2.0
PixVersePixVersec1 / v6 / v5.6
HailuoHailuoH3 / H3-Max / H3_regen / 2.3 / 2.3-fast / 02
GV
HunyuanHunyuan1.5 / 3d_2.0 (SceneType=3d_scene)
WanWan3.0 / 3.0-prime
MingmouMingmou1.0
VSVS2.5 / 2.0 / 2.0-fast / 2.0-mini
SVSV1.5-pro / 1.0-pro / 1.0-pro-fast
HappyhorseH21.1 / 1.0

공통 요청 파라미터 ​

파라미터필수타입설명
SubAppId선택IntegerVOD 애플리케이션 ID. 2023-12-25 이후 개통 계정은 필수
ModelName필수String엔진 이름
ModelVersion선택String엔진 버전. 미지정 시 안정 버전
Prompt선택String생성 프롬프트. 텍스트 입력 모드에서는 필수
NegativePrompt선택String네거티브 프롬프트
EnhancePrompt선택StringEnabled / Disabled. 프롬프트 자동 보강
SceneType선택String엔진별 특수 모드(motion_control / lip_sync / avatar_i2v / template_effect / 3d_scene / image_expand 등)
FileInfos.N선택Array참조 입력(이미지, 영상, 오디오)
SubjectInfos.N선택Array등록한 참조 대상 지정
LastFrameUrl / LastFrameFileId선택String끝 프레임
OutputConfig선택Object출력 설정
ExtInfo선택String엔진 전용 확장 파라미터
SessionId선택String중복 제거용 키. 같은 값의 재요청은 기존 요청을 기준으로 처리
SessionContext선택String콜백 투과 값. 최대 1000자
FileInfos.N ​

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

필드설명
TypeUrl(외부 URL) 또는 File(VOD FileId)
UrlType=Url일 때 주소
FileIdType=File일 때 VOD 미디어 파일 ID
CategoryImage / Video / Audio
UsageFirstFrame(첫 프레임) / LastFrame(끝 프레임) / Reference(참조)
ReferenceType참조 성격. 허용값과 조합은 모델 상세 참조
ObjectId참조 생성에 사용할 임시 참조 대상 이름
Text이미지 이름. 프롬프트에서 @이름 형태로 참조 (PixVerse 다중 이미지 모드)

Usage는 참조마다 붙입니다

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

OutputConfig ​
필드설명
Resolution480P / 720P / 1080P / 2K / 4K
Duration영상 길이(초). 엔진과 버전별 허용 범위가 다름
AspectRatio16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 등
AudioGenerationEnabled / Disabled. 음성 동시 생성
StorageModeTemporary(7일) / Permanent(FileId 발급)
MediaNameStorageMode=Permanent일 때 저장될 미디어 이름
InputComplianceCheckDisabled 시 지원 엔진의 입력 심사 해제. Hy Image 제외. 사용 전 영업담당자 문의
OutputComplianceCheckDisabled 시 지원 엔진의 출력 심사 해제. Hy Image 제외. 사용 전 영업담당자 문의
ExtInfo ​

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

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

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

python
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 (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API 버전2018-07-172019-06-12
영상 길이OutputConfig.Duration최상위 Duration
출력 포맷OutputConfig.OutputAudioFormatOutputConfig.OutputAudioFormat 또는 최상위
엔진 확장 파라미터최상위 AdditionalParameters (JSON 문자열, 1중)최상위 AdditionalParameters (JSON 문자열, 1중)
결과 조회DescribeTaskDetailDescribeAigcAudioTask
상태 값FINISH + ErrCode=0WAIT / RUN / DONE / FAIL

오디오 확장 파라미터

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

지원 엔진 ​

씬 (SceneType)엔진 (ModelName)ModelVersion비고
sfxKling기본값 사용text-to-sfx, video-to-sfx
musicMiniMaxMusic3.0 / 2.6 / 2.5 / 2.0가사 입력 지원
musicGL (Google Lyria)3.0-clip / 3.0-pro가사는 프롬프트에 포함
musicTme기본값 사용커버 음원 생성

요청 파라미터 ​

파라미터필수타입설명
SubAppId선택IntegerVOD 애플리케이션 ID
ModelName선택StringKling / MiniMaxMusic / GL / Tme. 기본값 Kling
ModelVersion조건부StringMiniMaxMusic / GL은 선택. 지정 시 지원 버전만 허용
SceneType선택Stringsfx / music
Prompt선택String오디오 설명. 텍스트 입력 모드에서는 필수
VideoInfos.N선택Arrayvideo-to-sfx용 참조 영상
AudioInfos.N선택Array참조 오디오
OutputConfig선택Object출력 설정
AdditionalParameters선택String엔진 확장 파라미터 (JSON 문자열)
OutputConfig ​
필드설명
StorageModeTemporary(7일) / Permanent
MediaNameStorageMode=Permanent일 때 미디어 이름
Duration길이(초). text-to-sfx는 [3, 10]. video-to-sfx에서는 무시됨
OutputAudioFormat출력 포맷. 예: mp3 / wav. 미지정 시 모델 기본값
AdditionalParameters ​

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

3D ​

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

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages

© 2026 Moonheart