API Reference

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

호출 규격

생성 / 조회 액션

요청 실행

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

python3 tencent-api.py mps CreateAigcImageTask request.json

python3 tencent-api.py mps CreateAigcVideoTask request.json

python3 tencent-api.py mps CreateAigcAudioTask request.json

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 목록과 요청 파라미터

입력 규격

공통 필드

응답과 실행 흐름

태스크 조회

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

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

python3 tencent-api.py mps DescribeAigcImageTask query.json

python3 tencent-api.py mps DescribeAigcVideoTask query.json

python3 tencent-api.py mps DescribeAigcAudioTask query.json

query.json:

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

접수 응답

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

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

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

응답 예시

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

{
  "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>"
  }
}

{
  "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>"
  }
}

{
  "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>"
  }
}

오류와 호출 제한

호출 빈도 제한

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

응답 코드

요청 예제

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

결과·리소스 관리

결과 저장

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

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

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

해상도와 업스케일 출력

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

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

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

가드레일 해제

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

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

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

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

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

모델 추가 설정

Seed

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

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

import json

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

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

엔진 카탈로그·관련 문서

Image

Wan 2.2

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

엔진 목록

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

공통 파라미터

입력 규격

VOD 경로와의 차이

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

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

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

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

호출 빈도 제한

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

Video

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

엔진 목록

SceneType

공통 파라미터

VOD 경로와의 차이

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

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

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

호출 빈도 제한

응답 코드

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

Music

Mureka / EL 음악 / 음향 효과

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

VOD 경로와의 차이

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

오디오 확장 파라미터

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

지원 엔진

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

요청 파라미터

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

3D

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