API Reference

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

호출 규격

항목	값
요청	`POST https://mps.intl.tencentcloudapi.com`
API 버전	`2019-06-12`
인증	`TC3-HMAC-SHA256` / SecretId / SecretKey
Content-Type	`application/json; charset=utf-8`
공통 헤더	`X-TC-Action` / `X-TC-Version` / `X-TC-Timestamp` / `X-TC-Region`

생성 / 조회 액션

구분	액션	용도
생성	`CreateAigcImageTask`	이미지 생성
생성	`CreateAigcVideoTask`	영상 생성, 3D 씬 생성
생성	`CreateAigcAudioTask`	음향 효과, 음악 생성
조회	`DescribeAigcImageTask`	이미지 태스크 조회
조회	`DescribeAigcVideoTask`	영상 태스크 조회
조회	`DescribeAigcAudioTask`	오디오 태스크 조회

요청 실행

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

bash

python3 tencent-api.py mps CreateAigcImageTask request.json

bash

python3 tencent-api.py mps CreateAigcVideoTask request.json

bash

python3 tencent-api.py mps CreateAigcAudioTask request.json

http

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

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

API 목록과 요청 파라미터

입력 규격

항목	제약
이미지 URL	외부 접근 가능. 이미지 생성은 `7MB` 이하, 영상 생성은 `10MB` 이하 권장
이미지 포맷	jpeg, png, webp
프롬프트 길이	이미지 `1000`자, 영상 `2000`자
오디오 동시 생성	`EnableAudio`는 지원 버전에서만 반영
길이	엔진별 `Duration` 지원 범위에 맞춰 지정

공통 필드

필드	용도
`Operator`	호출자 식별 문자열
`StoreCosParam`	COS 저장 위치
`AdditionalParameters`	모델 전용 옵션을 담는 JSON 문자열

응답과 실행 흐름

태스크 조회

생성 액션 호출 → TaskId 수신
조회 액션 폴링 → Status가 DONE이면 결과 URL 수신
결과 다운로드 또는 자체 스토리지로 전송

권장 폴링 간격은 3초입니다. 조회 API에는 호출 빈도 제한이 있으니 아래 표를 참고하세요.

Status	의미	처리
`WAIT`	대기 중	계속 폴링
`RUN`	실행 중	계속 폴링
`DONE`	완료	결과 URL 수신
`FAIL`	결과 확인	`Message`를 확인하고 후속 요청 결정

bash

python3 tencent-api.py mps DescribeAigcImageTask query.json

bash

python3 tencent-api.py mps DescribeAigcVideoTask query.json

bash

python3 tencent-api.py mps DescribeAigcAudioTask query.json

query.json:

json

{
  "TaskId": "<task-id>"
}

접수 응답

json

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

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

영상 조회 응답의 CoverUrl은 대표 프레임 URL입니다.

응답 예시

json

{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "ImageUrls": [
      "https://aigc-output-image-<id>.cos.<region>.myqcloud.com/<file>.png?q-sign-algorithm=sha1&..."
    ],
    "RequestId": "<request-id>"
  }
}

json

{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "Resolution": "1920x1080",
    "VideoUrls": [
      "https://aigc-output-video-<id>.cos.<region>.myqcloud.com/<file>.mp4?q-sign-algorithm=sha1&..."
    ],
    "RequestId": "<request-id>"
  }
}

json

{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "AudioInfos": [
      {
        "Url": "https://aigc-output-audio-file-<id>.cos.<region>.myqcloud.com/<file>.mp3?q-sign-algorithm=sha1&..."
      }
    ],
    "VideoInfos": ,
    "RequestId": "<request-id>"
  }
}

json

{
  "Response": {
    "Status": "DONE",
    "TaskId": "<task-id>",
    "VideoUrl": "https://<bucket>.cos.<region>.myqcloud.com/<file>.mp4",
    "CoverUrl": "https://<bucket>.cos.<region>.myqcloud.com/<cover>.jpg",
    "RequestId": "<request-id>"
  }
}

오류와 호출 제한

호출 빈도 제한

대상	제한
이미지 생성 / 조회	초당 `20`회
영상 생성	초당 `10`회
영상 조회	초당 `20`회

배치 처리는 동시 실행 수를 제한하는 큐를 두는 것이 안전합니다.

응답 코드

응답 코드	확인 항목	설정 방법
`InvalidParameter`	요청 파라미터	모델명 / 버전 / 입력 규격 확인
`InvalidParameter.ViolationContent`	입력 심사에서 차단. 프롬프트 또는 이미지가 정책 위반	프롬프트 또는 이미지 수정
`AuthFailure`	인증	SecretId, SecretKey, 타임스탬프, 서명 확인
`RequestLimitExceeded`	호출 빈도 초과	요청 속도를 낮추거나 큐 적용
`FailedOperation`	처리 결과	응답 `Message` 확인

요청 예제

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

결과·리소스 관리

결과 저장

기본 임시 결과 URL은 12시간 유효합니다. 결과를 자체 버킷에 보관하려면 생성 요청에 StoreCosParam을 지정합니다. 자체 버킷의 결과 URL은 해당 버킷의 접근 권한을 따르며, 비공개 객체는 COS SDK 또는 서명 URL로 내려받습니다.

json

{
  "StoreCosParam": {
    "CosBucketName": "<bucket>",
    "CosBucketRegion": "<region>",
    "CosBucketPath": "aigc/video/"
  }
}

COS 저장을 쓰려면 대상 버킷에 MPS_QcsRole 역할이 위임되어 있어야 합니다.

해상도와 업스케일 출력

ExtraParameters.Resolution으로 720P / 1080P / 2K / 4K를 지정합니다. 모델이 직접 출력할 수 있는 해상도를 넘어서는 값은 플랫폼 강화 단계를 거쳐 만들어집니다. 이미 만들어진 영상의 화질을 올리려면 MPS 트랜스코딩 및 강화 템플릿을 사용합니다.

모드	입력	출력
URL 모드	API에 URL을 넘겨 태스크 실행	COS, VOS, S3 등
File 모드	COS에 이미 저장된 파일 대상	COS

내장 강화 템플릿은 애니메이션 씬과 실사 씬으로 나뉘며, 720P / 1080P / 2K / 4K 출력에 프레임레이트는 소스를 따릅니다. 노이즈 제거, 업스케일 출력, 종합 강화가 함께 적용됩니다.

업스케일 출력 처리를 적용할 때는 COS 영구 저장을 먼저 설정하는 편이 안전합니다. 12시간 URL이 만료되면 강화 태스크의 입력이 사라집니다.

가드레일 해제

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

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

파라미터	해제 값	적용 대상
`ExtraParameters.EnablelnputComplianceCheck`	`false`	입력 심사 해제
`ExtraParameters.EnableOutputComplianceCheck`	`false`	출력 심사 해제

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

json

{
  "ExtraParameters": {
    "EnablelnputComplianceCheck": false,
    "EnableOutputComplianceCheck": false
  }
}

VOD는 OutputConfig.InputComplianceCheck / OutputConfig.OutputComplianceCheck에 문자열 Disabled를 전달합니다. MPS의 Boolean false와 혼용하지 마세요. VOD API Reference를 참조하세요.

모델 추가 설정

Seed

seed는 최상위 AdditionalParameters의 JSON 문자열 안에 지정합니다. ExtraParameters 객체와 별도 필드입니다. 같은 요청에 다른 모델 옵션이 있으면 하나의 JSON 객체로 합쳐 직렬화합니다.

json

{
  "AdditionalParameters": "{\"seed\":12312}"
}

python

import json

additional_parameters = json.dumps({"seed": 12312})

공통 입력 필드는 이미지 생성 API와 영상 생성 API를 참고합니다. 옵션의 적용 범위는 모델별로 다릅니다.

엔진 카탈로그·관련 문서

Image

Wan 2.2

CreateAigcImageTask로 이미지를 생성합니다. 공통 요청 필드와 모델별 출력 옵션을 구분하여 지정합니다. 지원 버전과 전용 옵션은 각 엔진 문서에서 확인합니다.

엔진 목록

엔진	ModelName	ModelVersion	특징
Nano Banana	`GEM`	`3.1` / `3.1-lite` / `3.0` / `2.5`	참조 이미지 최대 `14장`
Hunyuan	`Hunyuan`	`3.5-preview` / `3.0`	범용 생성, 이미지 편집, 참조 최대 `6장`
WAND-Vega-Image	`wand-vega-image`	`1.0-pro` / `1.0-flash` / `1.0-lite`	이미지 생성 / 참조 이미지 편집
Qwen	`Qwen`	`0925`	범용 생성
Seedream	`Seedream`	`5.0-pro` / `5.0-lite` / `4.5` / `4.0`	범용 생성
Kling	`Kling`	`3.0-Omni` / `3.0` / `O1` / `2.1`	실사 이미지 생성
Jimeng	`Jimeng`	`4.0`	범용 생성
Midjourney	`MJ`	`v8.2` / `v8.1` / `v7` / `niji_7`	애니/일러스트 튜닝
Vidu	`Vidu`	`q2`	범용 생성
Image2	`OG`	`image2_` / `image2.5_sunburst_` / `image2.5_flare_*`	참조 이미지, 커스텀 해상도, 마스크 편집

WAND-Vega-Image의 출력 크기는 AdditionalParameters의 size에 지정합니다. 상세 구성은 WAND-Vega-Image를 참조하세요.

공통 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	고정값 `<ModelName>`
`ModelVersion`	선택	String	엔진별 지원 버전
`Prompt`	필수	String	생성 프롬프트. 모델별 제한은 상세 문서 참조
`EnhancePrompt`	선택	Boolean	프롬프트 자동 보정. 기본값 `false`
`ImageInfos.N`	선택	Array	참조 이미지 배열. image-to-image 및 참조 생성에 사용
`ExtraParameters`	선택	Object	`Resolution` / `AspectRatio` 등 출력 옵션
`AdditionalParameters`	선택	String	모델 전용 옵션을 담은 JSON 문자열
`StoreCosParam`	선택	Object	COS 영구 저장 설정
`Operator`	선택	String	호출자 식별용 문자열

입력 규격

항목	제약
이미지 URL	외부 접근 가능, `7MB` 이하 권장
포맷	jpeg, png, webp
프롬프트 길이	모델별 제한 참조

VOD 경로와의 차이

같은 CreateAigcImageTask 액션 이름을 쓰지만, VOD와 MPS는 호출 대상과 파라미터 구조가 다릅니다.

항목	VOD (`vod.intl.tencentcloudapi.com`)	MPS (`mps.intl.tencentcloudapi.com`)
API 버전	`2018-07-17`	`2019-06-12`
첫 프레임 / 원본 이미지	`FileInfos.N` (`Usage`로 구분)	`ImageInfos.N`
엔진 전용 옵션	`ExtInfo` (JSON 문자열이 두 번 중첩)	`AdditionalParameters` (JSON 문자열 `1`회)
저장 방식	`OutputConfig.StorageMode` = `Temporary` / `Permanent`	결과는 COS 프리사인 URL, `StoreCosParam`으로 영구 저장
조회 액션	`DescribeTaskDetail`	`DescribeAigcImageTask`
상태 값	`Status="FINISH"` + `ErrCode=0`	`WAIT` / `RUN` / `DONE` / `FAIL`
결과 유효 기간	임시 저장 `7일`	프리사인 URL `12시간`

OG의 커스텀 해상도는 전달 위치가 다릅니다

OG(Image2)의 커스텀 size는 두 경로 모두 AdditionalParameters 안의 size 필드로 전달하지만, VOD는 이 값이 ExtInfo 안에 한 번 더 중첩됩니다. MPS에서는 AdditionalParameters 문자열 안에 바로 지정합니다.

json

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

필드	설명
`CosBucketName`	저장할 버킷 이름
`CosBucketRegion`	버킷 리전
`CosBucketPath`	버킷 내 저장 경로

호출 빈도 제한

작업	제한
이미지 생성	초당 `20`회
이미지 조회	초당 `20`회

왼쪽 메뉴에서 엔진을 선택하면 그 엔진의 버전, 전용 옵션, 요청 예시를 볼 수 있습니다.

Video

CreateAigcVideoTask로 영상을 생성합니다. 해상도와 비율은 ExtraParameters에, 길이는 최상위 Duration에 지정합니다. 엔진 전용 기능은 SceneType과 AdditionalParameters로 지정합니다.

엔진 목록

엔진	ModelName	ModelVersion	특징
WAND-Vega-Video	`wand-vega-video`	`1.5-pro` / `1.0-pro` / `1.0-lite`	텍스트 / 이미지 기반 영상 생성
Wan	`Wan`	`3.0` / `3.0-prime`	텍스트 및 첫/끝 프레임 생성
Kling	`Kling`	`3.0-Omni` / `3.0` / `2.6` / `2.5` / `2.1` / `2.0` / `1.6` / `O1`	동작 제어, 립싱크. 상세 문서
Hailuo	`Hailuo`	`H3` / `2.3` / `2.3-fast` / `02`
Vidu	`Vidu`	`q3-ad` / `q3-drama` / `q3` / `q3-pro` / `q3-turbo` / `q3-mix` / `q2` 계열	멀티 이미지 참조, 등록한 참조 대상
Veo	`GV`	`3.1` / `3.1-fast` / `3.1-lite` / `omni`	영상 참조, 상태 유지 편집, 오디오 네이티브
PixVerse	`PixVerse`	`c1` / `v6` / `v5.6`	해상도 `4`단계, 참조 생성
Hunyuan	`Hunyuan`	`1.5`	첫/끝 프레임
Happyhorse	`H2`	`1.1` / `1.0`	멀티 이미지 참조, 참조 영상(`1.0`만)
Mingmou	`Mingmou`	`1.0`	`land2port` 가로 세로 변환
VS	`VS`	`2.5` / `2.0` / `2.0-fast` / `2.0-mini`	고비트레이트, 오디오 동시 생성
SV	`Seedance`	`1.5-pro` / `1.0-pro` / `1.0-pro-fast`	—

SceneType

SceneType	엔진	용도
`motion_control`	Kling	동작 제어
`lip_sync`	Kling	립싱크
`avatar_i2v`	Kling	디지털 휴먼
`multi_elements`	Kling	다중 요소 편집
`template_effect`	Vidu	이펙트 템플릿
`land2port`	Mingmou	가로 영상을 세로 구도로 재구성
`3d_scene`	Hunyuan	3D 씬

공통 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	고정값 `<ModelName>`
`ModelVersion`	선택	String	엔진별 지원 버전
`Prompt`	필수	String	생성 프롬프트. 모델별 제한 참조
`NegativePrompt`	선택	String	결과에서 제외할 요소. 지원 모델에서 적용
`EnhancePrompt`	선택	Boolean	프롬프트 자동 보정. 기본값 `false`
`ImageUrl`	선택	String	첫 프레임 이미지 URL. 외부 접근 가능해야 하고 `10MB` 이하
`LastImageUrl`	선택	String	끝 프레임 이미지 URL. `ImageUrl`과 함께 사용
`ImageInfos.N`	선택	Array	참조 이미지 배열. `Category` / `Url` / `ReferenceType` 등
`Duration`	선택	Integer	생성 길이(초). 모델별 허용값만 반영
`ExtraParameters`	선택	Object	`Resolution` / `AspectRatio` / `EnableAudio`
`AdditionalParameters`	선택	String	모델 전용 옵션을 담은 JSON 문자열
`StoreCosParam`	선택	Object	COS 영구 저장. `CosBucketName` / `CosBucketRegion` / `CosBucketPath`
`Operator`	선택	String	호출자 식별용 문자열
`ExtraParameters.` `EnablelnputComplianceCheck`	선택	Boolean	`false`를 명시적으로 전달하면 입력 심사 해제. 사용 전 영업담당자 문의
`ExtraParameters.` `EnableOutputComplianceCheck`	선택	Boolean	`false`를 명시적으로 전달하면 출력 심사 해제. 사용 전 영업담당자 문의

VOD 경로와의 차이

VOD와 MPS는 각각의 엔드포인트와 파라미터 구조를 사용합니다. 다음 표에서 MPS 요청 필드를 확인하세요.

항목	VOD (`vod.intl.tencentcloudapi.com`)	MPS (`mps.intl.tencentcloudapi.com`)
API 버전	`2018-07-17`	`2019-06-12`
첫 프레임	`FileInfos.N.Usage=FirstFrame`	`ImageUrl`
끝 프레임	`FileInfos.N.Usage=LastFrame` 또는 `LastFrameUrl`	`LastImageUrl`
참조 이미지	`FileInfos.N`	`ImageInfos.N`
참조 영상	`FileInfos.N` (`Category=Video`)	`VideoInfos.N`
영상 길이	`OutputConfig.Duration`	최상위 `Duration`
해상도 / 비율	`OutputConfig.Resolution` / `AspectRatio`	`ExtraParameters.Resolution` / `AspectRatio`
오디오 생성	`OutputConfig.AudioGeneration`	`ExtraParameters.EnableAudio`
엔진 전용 옵션	`ExtInfo` (JSON 문자열이 두 번 중첩)	`AdditionalParameters` (JSON 문자열 `1`회)
저장 방식	`OutputConfig.StorageMode` = `Temporary` / `Permanent`	결과는 COS 프리사인 URL, `StoreCosParam`으로 영구 저장
조회 액션	`DescribeTaskDetail`	`DescribeAigcVideoTask`
상태 값	`Status="FINISH"` + `ErrCode=0`	`WAIT` / `RUN` / `DONE` / `FAIL`
결과 유효 기간	임시 저장 `7일`	프리사인 URL `12시간`

경로를 바꿀 때는 파라미터를 다시 매핑해야 합니다

MPS는 최상위 Duration과 JSON 문자열 AdditionalParameters를 사용합니다. VOD의 대응 항목은 OutputConfig.Duration과 ExtInfo입니다.

필드	설명
`CosBucketName`	저장할 버킷 이름
`CosBucketRegion`	버킷 리전
`CosBucketPath`	버킷 내 저장 경로

호출 빈도 제한

작업	제한
영상 생성	초당 `10`회
영상 조회	초당 `20`회

응답 코드

코드	설명
`InvalidParameter.ViolationContent`	입력 또는 출력이 콘텐츠 정책에 위반됨
`InvalidParameter`	입력 필드와 파라미터 규격 확인
`AuthFailure`	인증 설정 확인
`RequestLimitExceeded`	호출 빈도 초과
`FailedOperation`	처리 결과 확인

왼쪽 메뉴에서 엔진을 선택하면 그 엔진의 버전별 지원 능력, 전용 옵션, 요청 예시를 볼 수 있습니다.

Music

Mureka / EL 음악 / 음향 효과

MPS 경로로 호출하는 오디오 생성입니다. 액션은 CreateAigcAudioTask, 결과 조회는 DescribeAigcAudioTask입니다. 씬을 사용하는 모델은 sfx(음향 효과) 또는 music(음악)을 지정합니다. Mureka / EL은 모델 상세의 요청 구조를 따릅니다.

VOD 경로와의 차이

같은 CreateAigcAudioTask 액션을 쓰지만 엔드포인트와 결과 조회 방식이 다릅니다.

구분	VOD (`vod.intl.tencentcloudapi.com`)	MPS (`mps.intl.tencentcloudapi.com`)
API 버전	`2018-07-17`	`2019-06-12`
오디오 길이	`OutputConfig.Duration`	최상위 `Duration`
출력 포맷	`OutputConfig.OutputAudioFormat`	최상위 `OutputAudioFormat`
엔진 확장 파라미터	최상위 `AdditionalParameters` (JSON 문자열)	최상위 `AdditionalParameters` (JSON 문자열)
MiniMaxMusic 가사 필드	`lyrics`	`lyric`
MiniMaxMusic 보컬 제거 필드	`instrumental`	`is_instrumental`
Tme 참조 음원	`AudioInfos.N`의 `Type` + `Url`	`AudioInfos.N`의 `AudioUrl`
Tme 리소스 지정	`AdditionalParameters`의 `ResourceId`	`ExtraParameters`의 `ResourceId`
결과 조회	`DescribeTaskDetail`	`DescribeAigcAudioTask`
상태 값	`FINISH` + `ErrCode=0`	`WAIT` / `RUN` / `DONE` / `FAIL`
결과 URL	`Output.AudioInfos.FileUrl` + `ExpireTime` (임시 URL, `7일`)	`AudioInfos.Url` (서명 포함 임시 URL, `12시간`)
영구 저장	`OutputConfig.StorageMode=Permanent` → VOD `FileId`	`StoreCosParam`으로 자체 COS 버킷에 저장

오디오 확장 파라미터

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

지원 엔진

씬 (`SceneType`)	엔진 (`ModelName`)	ModelVersion	비고
`sfx`	`Kling`	기본값 사용	text-to-sfx, video-to-sfx
`music`	`MiniMaxMusic`	`3.0` / `2.6` / `2.5` / `2.0`	가사 입력 지원
`music`	`GL` (Google Lyria)	`3.0-clip` / `3.0-pro`	가사는 프롬프트에 포함
`music`	`Tme`	기본값 사용	커버 음원 생성

ModelName=GL을 사용합니다. 콘솔의 Google Lyria 3은 3.0-clip / 3 Pro는 3.0-pro에 대응합니다.

항목	MiniMaxMusic	GL (Google Lyria)
가사 입력	`AdditionalParameters`의 `lyric` 필드로 전달	인터페이스가 `Prompt` 하나만 받으므로 스타일과 가사를 한 프롬프트에 합쳐서 작성
인스트루멘털	`{"is_instrumental": true}` 또는 가사 생략	연주곡 생성
출력 포맷	MP3, WAV	MP3
길이	모델이 결정	`3`은 약 `30초` 클립, `3 Pro`는 완결된 곡 구조

요청 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	`Kling` / `MiniMaxMusic` / `GL` / `Tme`
`ModelVersion`	선택	String	생략 시 안정 버전 사용
`SceneType`	조건부	String	Kling 등 해당 모델의 씬 지정. Mureka / EL은 모델 상세 참조
`Prompt`	선택	String	생성할 오디오 설명. 최대 `2000`자
`VideoInfos.N`	선택	Array	참조 영상. 영상 기반 음향 효과에 사용
`AudioInfos.N`	선택	Array	참조 오디오. 커버 음원 생성에 사용. MPS는 `AudioUrl` 필드
`Duration`	선택	Integer	오디오 길이(초). `0~60`
`OutputAudioFormat`	선택	String	`mp3` 또는 `wav`
`ExtraParameters`	선택	Object	모델별 추가 옵션. `Tme`는 `ResourceId` 필요
`AdditionalParameters`	선택	String	모델 전용 옵션 JSON 문자열. `lyric` / `is_instrumental` / `bgm_prompt` / `asmr_mode` 등

필드	타입	설명
`Status`	String	`WAIT` / `RUN` / `DONE` / `FAIL`
`Message`	String	처리 결과 메시지. 성공 시 `ok`
`AudioInfos`	Array	생성된 오디오 목록
`AudioInfos.Url`	String	오디오 다운로드 URL. 서명이 포함된 임시 링크
`VideoInfos`	Array	음악 생성에서는 빈 배열

왼쪽 메뉴에서 엔진을 선택하면 그 엔진의 가사 전달 방식, 전용 옵션, 요청 예시를 볼 수 있습니다.

3D

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

API Reference ​

호출 규격 ​

생성 / 조회 액션 ​

요청 실행 ​

API 목록과 요청 파라미터 ​

입력 규격 ​

공통 필드 ​

응답과 실행 흐름 ​

태스크 조회 ​

접수 응답 ​

응답 예시 ​

오류와 호출 제한 ​

호출 빈도 제한 ​

응답 코드 ​

요청 예제 ​

결과·리소스 관리 ​

결과 저장 ​

해상도와 업스케일 출력 ​

가드레일 해제 ​

모델 추가 설정 ​

Seed ​

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

Image ​

엔진 목록 ​

공통 파라미터 ​

입력 규격 ​

VOD 경로와의 차이 ​

호출 빈도 제한 ​

Video ​

엔진 목록 ​

SceneType ​

공통 파라미터 ​

VOD 경로와의 차이 ​

호출 빈도 제한 ​

응답 코드 ​

Music ​

VOD 경로와의 차이 ​

지원 엔진 ​

요청 파라미터 ​

3D ​

API Reference

호출 규격

생성 / 조회 액션

요청 실행

API 목록과 요청 파라미터

입력 규격

공통 필드

응답과 실행 흐름

태스크 조회

접수 응답

응답 예시

오류와 호출 제한

호출 빈도 제한

응답 코드

요청 예제

결과·리소스 관리

결과 저장

해상도와 업스케일 출력

가드레일 해제

모델 추가 설정

Seed

엔진 카탈로그·관련 문서

Image

엔진 목록

공통 파라미터

입력 규격

VOD 경로와의 차이

호출 빈도 제한

Video

엔진 목록

SceneType

공통 파라미터

VOD 경로와의 차이

호출 빈도 제한

응답 코드

Music

VOD 경로와의 차이

지원 엔진

요청 파라미터

3D