Tencent Cloud Media PaaS

AIGC Product Guide

통합된 AI 생성 제품 포털 — Text, Image, Video, Music, 3D, MPS, VOD를 하나의 가이드에서

시작하기 → WAND 체험하기 →

Text Generation

GPT, Claude, Gemini, Kimi, DeepSeek 등 최신 LLM 모델을 통합 API로 호출

Image Generation

Hunyuan, Kling, GEM, MJ, OG, Seedream 등 다양한 이미지 생성 모델

Video Generation

Kling, PixVerse, Vidu, Hailuo, GV 등 영상 생성 및 립싱크·모션 컨트롤

Music Generation

음악·효과음 생성을 위한 Kling SFX, MiniMaxMusic, Google Lyria

3D Generation

3D 모델 생성 및 편집을 위한 AI 기반 파이프라인

MPS AIGC

미디어 처리 서비스와 통합된 AIGC 이미지·비디오·오디오 생성

VOD Integration

VOD 플랫폼과 연계된 AIGC 미디어 파이프라인

1. Text Generation Overview

첫 호출 시 아래의 단계를 따라 진행해주십시오. 각 step은 아래 상세 섹션으로 연결되어 있습니다.

⚠

Important

전체 흐름: 서비스 개통 → CreateAigcApiToken으로 Token 발급 → Token을 사용해 LLM 모델 호출.

1.1 Step 1 — Token 발급

CreateAigcApiToken으로 AIGC API Token을 발급받습니다. 발급된 Token이 곧 LLM 호출 시 $YOUR_API_TOKEN입니다.

1.2 Step 2 — Endpoint 선택

사용할 모델에 맞춰 endpoint($ENDPOINT)를 선택합니다. 자세한 매핑은 5.2 프로토콜 매트릭스 참조.

프로토콜	Endpoint ($ENDPOINT)	주 사용 모델
OpenAI Completions	`https://text-aigc.vod-qcloud.com/v1/chat/completions`	GPT, Gemini, Kimi, GK, GLM, DeepSeek
OpenAI Responses	`https://text-aigc.vod-qcloud.com/v1/responses`	GPT (공식 권장)
Anthropic Messages	`https://text-aigc.vod-qcloud.com/v1/messages`	CD (Claude), MiniMax

1.3 Step 3 — Headers 준비

최소 2개 헤더만 있으면 호출 가능합니다. 자세한 헤더 옵션은 5.1 Request Headers 참조.

Header	Value
Content-Type	`application/json`
Authorization	`Bearer $YOUR_API_TOKEN` (Anthropic Messages는 `x-api-key: $YOUR_API_TOKEN` 사용 가능)

1.4 Step 4 — 첫 호출

아래 cURL 1개를 그대로 실행하면 첫 응답이 돌아옵니다.

$YOUR_API_TOKEN과 $ENDPOINT를 앞 단계에서 얻은 값으로 치환합니다. 최소 헤더는 Content-Type과 Authorization 두 개입니다.

Body 파라미터의 의미는 5.4 Request Parameters를, 다른 프로토콜 예시는 6. 호출 예시를 참조합니다.

Bash Quickstart cURL

curl -X POST $ENDPOINT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_API_TOKEN" \
  -d '{
    "model": "gpt-5.1",
    "messages": [
      {"role": "user", "content": "Hi, who are you?"}
    ]
  }'

2. API 정보

POSTtext-aigc.vod-qcloud.com

항목	값
Base URL	`https://text-aigc.vod-qcloud.com`
Method	`POST`
Endpoint (OpenAI Completions)	`/v1/chat/completions`
Endpoint (OpenAI Responses)	`/v1/responses`
Endpoint (Anthropic Messages)	`/v1/messages`
Auth	`Authorization: Bearer ${TOKEN}` 또는 `x-api-key: ${TOKEN}`

3. 인증 & Token 관리

Token 관리 API는 Tencent Cloud API (vod.intl.tencentcloudapi.com)를 통해 호출합니다. 인증은 Tencent Cloud 공통 파라미터(SecretId/SecretKey 서명)를 사용합니다.

3.1 CreateAigcApiToken

POSTvod.intl.tencentcloudapi.com

AIGC API Token을 생성합니다. 생성 후 약 30초간 동기화 시간이 필요하며, 이후 조회/삭제가 가능합니다.

📎 공식 API 문서: CreateAigcApiToken

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID

Response Parameters

Parameter	Type	Description
ApiToken	String	생성된 AIGC API Token
RequestId	String	요청 고유 ID

Python SDK Example

from tencentcloud.common import credential
from tencentcloud.vod.v20180717 import vod_client, models

cred = credential.Credential("YOUR_SECRET_ID", "YOUR_SECRET_KEY")
client = vod_client.VodClient(cred, "")

req = models.CreateAigcApiTokenRequest()
req.SubAppId = 1500000000

resp = client.CreateAigcApiToken(req)
print(resp.ApiToken)  # 생성된 Token

JSON Response

200

💡

Tip

Token은 만료되지 않습니다. 계정당 최대 50개까지 생성 가능합니다.

3.2 DescribeAigcApiTokens

POSTvod.intl.tencentcloudapi.com

현재 계정에 생성된 AIGC API Token 목록을 조회합니다.

📎 공식 API 문서: DescribeAigcApiTokens

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID

Response Parameters

Parameter	Type	Description
TokenSet	Array of Object	Token 목록
TokenSet[].TokenId	String	Token ID
TokenSet[].TokenName	String	Token 이름 (선택 입력한 경우)
TokenSet[].ApiToken	String	API Token 값 (마스킹)
TokenSet[].CreateTime	String	생성 시간 (ISO 8601)
RequestId	String	요청 고유 ID

Python SDK Example

from tencentcloud.common import credential
from tencentcloud.vod.v20180717 import vod_client, models

cred = credential.Credential("YOUR_SECRET_ID", "YOUR_SECRET_KEY")
client = vod_client.VodClient(cred, "")

req = models.DescribeAigcApiTokensRequest()
req.SubAppId = 1500000000

resp = client.DescribeAigcApiTokens(req)
for token in resp.TokenSet:
    print(f"{token.TokenId} | {token.ApiToken} | {token.CreateTime}")

JSON Response

200

3.3 DeleteAigcApiToken

POSTvod.intl.tencentcloudapi.com

지정한 AIGC API Token을 삭제합니다. 삭제된 Token으로는 더 이상 API를 호출할 수 없습니다.

📎 공식 API 문서: DeleteAigcApiToken

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID
TokenId	required	String	삭제할 Token의 ID

Python SDK Example

from tencentcloud.common import credential
from tencentcloud.vod.v20180717 import vod_client, models

cred = credential.Credential("YOUR_SECRET_ID", "YOUR_SECRET_KEY")
client = vod_client.VodClient(cred, "")

req = models.DeleteAigcApiTokenRequest()
req.SubAppId = 1500000000
req.TokenId = "token-xxxxxxxxxxxx"

resp = client.DeleteAigcApiToken(req)
print(resp.RequestId)  # 성공 시 RequestId 반환

JSON Response

200

3.4 서브계정 권한 설정 (CAM)

서브계정에서 Token API를 호출하려면 주 계정에서 다음 CAM 정책을 부여해야 합니다.

정책 1: 모든 SubAppId에 대한 권한

JSON CAM Policy

{
  "statement": [
    {
      "action": [
        "vod:CreateAigcApiToken",
        "vod:DeleteAigcApiToken"
      ],
      "effect": "allow",
      "resource": "*"
    }
  ],
  "version": "2.0"
}

정책 2: 특정 SubAppId에 대한 권한

JSON CAM Policy (specific SubAppId)

{
  "statement": [
    {
      "action": [
        "vod:CreateAigcApiToken",
        "vod:DeleteAigcApiToken"
      ],
      "effect": "allow",
      "resource": "qcs::vod::uin/*:subAppId/1500050693"
    }
  ],
  "version": "2.0"
}

4. AIGC Quota 관리

AIGC API Token 단위(Text) 또는 SubAppId 단위(Image, Video)로 사용 한도를 설정·조회·수정·삭제할 수 있습니다. 한도를 초과하면 LLM 호출이 HTTP 429 + insufficient_quota로 거부됩니다.

⚠

중요 — 호출 환경 제약

Endpoint: https://vod.tencentcloudapi.com 와 인터내셔널 도메인(https://vod.intl.tencentcloudapi.com) 모두 지원합니다. (과거 intl 도메인에서 InvalidAction을 반환하던 제약은 해소되어, 두 도메인 모두 정상 동작합니다.)
Tencent Cloud Python SDK 3.1.111 기준으로 본 4종 API는 SDK 모델에 미반영 상태입니다. 따라서 raw signed POST (TC3-HMAC-SHA256) 방식으로만 호출 가능합니다.

개요

Action	설명	필수 파라미터
DescribeAigcQuotas	Quota 조회	SubAppId, QuotaType
CreateAigcQuota	Quota 생성	SubAppId, QuotaType, QuotaLimit (Text는 ApiToken 추가 필수)
ModifyAigcQuota	Quota 수정	SubAppId, QuotaType, QuotaLimit (Text는 ApiToken 추가 필수)
DeleteAigcQuota	Quota 삭제	SubAppId, QuotaType (Text는 ApiToken 추가 필수)

공통 규약

항목	값
Endpoint	`https://vod.tencentcloudapi.com` 또는 `https://vod.intl.tencentcloudapi.com` (둘 다 동일 동작)
Service	`vod`
Version	`2018-07-17`
인증 방식	`TC3-HMAC-SHA256` 서명 (SecretId / SecretKey)
호출 방식	Raw signed POST (Python SDK 미반영)

QuotaType 차원

QuotaType	차원	ApiToken 필요 여부
Text	ApiToken 단위	필수
Image	SubAppId 단위	불필요
Video	SubAppId 단위	불필요

운영 가이드 — 실전 시나리오

예시: 신규 고객의 Text API Token에 "월 100콜 상당" 한도를 적용하는 표준 절차입니다. 비동기 집계 over-shoot(+38%)을 고려해 안전 마진을 적용한 흐름입니다.

단계	Action	목적 / 설정값
① 현재 상태 확인	`DescribeAigcQuotas`	해당 Token에 기존 Quota가 있는지 조회. 없으면 생성, 있으면 수정으로 분기.
② 한도 생성	`CreateAigcQuota`	의도 한도 100콜 → over-shoot 보정으로 `QuotaLimit=65`(약 65%)로 설정. `QuotaType=Text` + `ApiToken` 지정 필수.
③ 모니터링	`DescribeAigcQuotas`	주기적으로 `QuotaUsed` / `QuotaLimit` 비교. 한도 근접 시 ④ 또는 ⑤로.
④ 한도 증액	`ModifyAigcQuota`	고객 증설 요청 시 `QuotaLimit`만 상향. 차원(SubAppId/QuotaType/ApiToken)은 동일하게 유지.
⑤ 누적값 리셋	`DeleteAigcQuota` → `CreateAigcQuota`	자동 리셋이 없으므로, 새 청구주기 진입 시 삭제 후 재생성(= disable→enable 효과)으로 누적 0 초기화.

💡

권장 설정 요약

QuotaLimit = 의도 한도 × 0.6~0.7 — over-shoot(+38%)을 흡수하여 실효 한도를 의도치에 맞춥니다.
Token 단위 격리 — 고객/환경마다 별도 ApiToken을 발급해 Token 단위로 한도를 독립 관리하십시오.
리셋은 삭제→재생성 — ModifyAigcQuota는 한도만 바꿀 뿐 누적값을 0으로 만들지 않습니다.
모니터링 자동화 — DescribeAigcQuotas를 주기 폴링하여 QuotaUsed/QuotaLimit ≥ 0.8일 때 알림을 권장합니다.

4.1 DescribeAigcQuotas

설정된 Quota 정보를 조회합니다.

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID
QuotaType	required	String	`Text` \| `Image` \| `Video`
ApiToken	conditional	String	QuotaType이 `Text`일 때만 사용. 특정 Token만 조회

JSON Request Body Example (Text)

{
  "Action": "DescribeAigcQuotas",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "QuotaType": "Text",
  "ApiToken": "aOmFOhCsDoqKsSo9BMvwv81o8nd1vzSe"
}

JSON Response Example

200

{
  "Response": {
    "QuotaSet": [
      {
        "SubAppId": 1500000000,
        "QuotaType": "Text",
        "ApiToken": "aOmFOhCsDoqKsSo9BMvwv81o8nd1vzSe",
        "QuotaLimit": 100,
        "Used": 0,
        "Status": "Enabled"
      }
    ],
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

4.2 CreateAigcQuota

새 Quota를 생성합니다. 동일 차원에 이미 Quota가 존재하면 FailedOperation.QuotaExist를 반환합니다.

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID
QuotaType	required	String	`Text` \| `Image` \| `Video`
QuotaLimit	required	Integer	Quota 한도(누적 호출 수)
ApiToken	conditional	String	QuotaType이 `Text`일 때 필수

JSON Request Body Example (Text)

{
  "Action": "CreateAigcQuota",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "QuotaType": "Text",
  "ApiToken": "aOmFOhCsDoqKsSo9BMvwv81o8nd1vzSe",
  "QuotaLimit": 100
}

4.3 ModifyAigcQuota

기존 Quota의 한도를 수정합니다. 자동 리셋은 지원되지 않으므로, 누적값을 0으로 되돌리려면 disable → enable로 토글해야 합니다(아래 caveat 참조).

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID
QuotaType	required	String	`Text` \| `Image` \| `Video`
QuotaLimit	required	Integer	새 Quota 한도
ApiToken	conditional	String	QuotaType이 `Text`일 때 필수

JSON Request Body Example (Text)

{
  "Action": "ModifyAigcQuota",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "QuotaType": "Text",
  "ApiToken": "aOmFOhCsDoqKsSo9BMvwv81o8nd1vzSe",
  "QuotaLimit": 200
}

4.4 DeleteAigcQuota

설정된 Quota를 삭제합니다. 삭제 후 해당 차원은 한도 없이 호출 가능 상태가 됩니다.

Request Parameters

Parameter		Type	Description
SubAppId	required	Integer	VOD 애플리케이션 ID
QuotaType	required	String	`Text` \| `Image` \| `Video`
ApiToken	conditional	String	QuotaType이 `Text`일 때 필수

JSON Request Body Example (Text)

{
  "Action": "DeleteAigcQuota",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "QuotaType": "Text",
  "ApiToken": "aOmFOhCsDoqKsSo9BMvwv81o8nd1vzSe"
}

4.5 한도 초과 시 LLM 응답

설정한 Quota를 초과한 상태에서 Text Generation을 호출하면 LLM endpoint에서 HTTP 429와 함께 다음 본문을 반환합니다:

JSON 429 Response

429

{
  "error": {
    "type": "insufficient_quota",
    "message": "Text quota exceeded.",
    "code": null
  }
}

4.6 누적 · 리셋 · over-shoot 주의사항

⚠

주의사항

자동 리셋 없음: 시간/일자 기반 자동 리셋은 제공되지 않습니다. 누적값 0 초기화는 disable → enable 토글로만 가능합니다.
비동기 집계로 인한 over-shoot: 사용량 집계가 비동기로 처리되어 over-shoot이 +38%까지 관측되었습니다(예: QuotaLimit=100 설정 시 138 호출까지 통과).
안전 마진: 실효 한도를 보장하려면 의도한 값의 60~70%로 QuotaLimit을 설정하길 권장합니다.

Code	Scope	Description
insufficient_quota	LLM endpoint (HTTP 429)	설정된 Quota 초과 — Text 호출 거부
MissingParameter	vod / vod.intl	필수 파라미터 누락(`QuotaType`, `SubAppId` 등) — 요청 본문 확인
InvalidParameterValue	vod / vod.intl	QuotaType 값 오류 또는 Text에서 ApiToken 누락

4.7 Python raw signed POST 예제

Tencent Cloud Python SDK 3.1.111 기준으로 본 API는 SDK 모델에 미반영 상태입니다. 아래는 TC3-HMAC-SHA256 서명을 직접 만들어 호출하는 예제입니다.

Python raw signed POST (DescribeAigcQuotas)

import hashlib, hmac, json, time
import requests

SECRET_ID  = "YOUR_SECRET_ID"
SECRET_KEY = "YOUR_SECRET_KEY"

ENDPOINT = "vod.tencentcloudapi.com"
SERVICE  = "vod"
VERSION  = "2018-07-17"
ACTION   = "DescribeAigcQuotas"

payload = {
    "SubAppId": 1500000000,
    "QuotaType": "Text",
    "ApiToken": "aOmFOhCsDoqKsSo9BMvwv81o8nd1vzSe",
}
body = json.dumps(payload, separators=(",", ":"))

ts   = int(time.time())
date = time.strftime("%Y-%m-%d", time.gmtime(ts))

# Step 1: CanonicalRequest
hashed_body = hashlib.sha256(body.encode("utf-8")).hexdigest()
canonical_request = "\n".join([
    "POST",
    "/",
    "",
    f"content-type:application/json\nhost:{ENDPOINT}\n",
    "content-type;host",
    hashed_body,
])

# Step 2: StringToSign
credential_scope = f"{date}/{SERVICE}/tc3_request"
string_to_sign = "\n".join([
    "TC3-HMAC-SHA256",
    str(ts),
    credential_scope,
    hashlib.sha256(canonical_request.encode("utf-8")).hexdigest(),
])

# Step 3: Signature
def _hmac(k, m): return hmac.new(k, m.encode("utf-8"), hashlib.sha256).digest()
secret_date    = _hmac(("TC3" + SECRET_KEY).encode("utf-8"), date)
secret_service = _hmac(secret_date, SERVICE)
secret_signing = _hmac(secret_service, "tc3_request")
signature      = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()

# Step 4: Authorization Header
authorization = (
    f"TC3-HMAC-SHA256 "
    f"Credential={SECRET_ID}/{credential_scope}, "
    f"SignedHeaders=content-type;host, "
    f"Signature={signature}"
)

resp = requests.post(
    f"https://{ENDPOINT}/",
    headers={
        "Authorization": authorization,
        "Content-Type": "application/json",
        "Host": ENDPOINT,
        "X-TC-Action":    ACTION,
        "X-TC-Version":   VERSION,
        "X-TC-Timestamp": str(ts),
    },
    data=body,
    timeout=10,
)
print(resp.status_code, resp.json())

FAQ

질문	답변
인터내셔널 도메인(vod.intl)으로 호출하면?	정상 동작합니다. `vod.tencentcloudapi.com` 와 `vod.intl.tencentcloudapi.com` 모두 동일하게 사용 가능합니다. (과거 `InvalidAction` 제약은 해소됨)
Python SDK로 호출 가능한가?	SDK 3.1.111 기준 미반영. raw signed POST만 가능.
설정한 한도와 다르게 더 많이 통과되는데?	비동기 집계 over-shoot으로 +38% 관측. 안전 마진 60~70%로 설정.
월/일 단위 자동 리셋 가능한가?	지원되지 않음. disable → enable 토글로만 누적값 0 초기화.
QuotaLimit 단위는?	호출 횟수 기반으로 동작합니다.

5. Request 작성 가이드

Text Generation은 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 3가지 프로토콜을 지원합니다.

5.1 Request Headers

Header	Required	Description
Content-Type	Yes	`application/json`
Authorization	Yes (x-api-key 미사용 시)	`Bearer ${TOKEN}`
x-api-key	Yes (Authorization 미사용 시)	`${TOKEN}` (Anthropic 방식)
X-Request-Id	No	사용자 정의 Request ID
Tx-User-Session-Id	No	동일 세션 매핑으로 캐시 히트율 향상

5.2 프로토콜 매트릭스

모델별 사용 가능한 프로토콜과 권장 endpoint입니다.

모델	프로토콜	Endpoint Path
GPT	OpenAI Completions (gpt-5.4-pro, gpt-5.3-codex 제외)	`/v1/chat/completions`
GPT	OpenAI Responses (공식 권장)	`/v1/responses`
Gemini	OpenAI Completions	`/v1/chat/completions`
CD (Claude)	Anthropic Messages (공식)	`/v1/messages`
CD (Claude)	OpenAI Completions	`/v1/chat/completions`
MiniMax	Anthropic Messages (공식 권장)	`/v1/messages`
MiniMax	OpenAI Completions	`/v1/chat/completions`
Kimi	OpenAI Completions	`/v1/chat/completions`
GK (Grok)
GLM
DeepSeek

어떤 프로토콜을 골라야 하나?

유스케이스	권장 프로토콜	이유
여러 벤더 모델을 한 코드로 호출하고 싶다	OpenAI Completions	거의 모든 모델이 지원하는 공통분모
GPT-5 reasoning, multi-turn state 활용	OpenAI Responses	GPT 공식 권장 — `previous_response_id`로 멀티턴 상태 유지
Claude / MiniMax를 공식 SDK로 사용	Anthropic Messages	두 모델의 공식 권장 프로토콜
단일 cURL로 빠른 검증	OpenAI Completions	요청 body 가장 단순

5.3 지원 모델

모델 제공사	모델명 (model value)	지원 입력	출력 형태
OpenAI	gpt-5.5	Text, Image	Text
	gpt-5.4-pro
	gpt-5.4
	gpt-5.4-nano
	gpt-5.4-mini
	gpt-5.3-codex
	gpt-5.3-chat
	gpt-5.2-chat
	gpt-5.2
	gpt-5.1
	gpt-5.1-chat
	gpt-5
	gpt-5-mini
	gpt-5-chat
	gpt-5-nano
	gpt-chat-latest
	gpt-4.1
	gpt-4o
Gemini	gemini-3.5-flash	Text, Code, Image, Audio, Video	Text
	gemini-3.1-pro-preview
	gemini-3.1-flash-lite
	gemini-3.1-flash-lite-preview
	gemini-3-flash-preview
	gemini-2.5-pro
	gemini-2.5-flash
CD (Claude)	cd-opus-4.8	Text, Image	Text
	cd-opus-4.7
	cd-opus-4.6
	cd-opus-4.5
	cd-sonnet-4.6
	cd-sonnet-4.5
cd-haiku-4.5
GK (Grok)	gk-4.3	Text, Image	Text
	gk-4-20-reasoning
	gk-4-20-non-reasoning
	gk-4-1-fast-reasoning
	gk-4.1-fast-non-reasoning
DeepSeek	deepseek-v4-proNEW	Text	Text
DeepSeek	deepseek-v4-flashNEW	Text	Text
DeepSeek	deepseek-v3.2	Text	Text
GLM	glm-5.1NEW	Text	Text
GLM	glm-5 / glm-5-turbo	Text	Text
Kimi	kimi-k2.6NEW	Text	Text
Kimi	kimi-k2.5	Text	Text
MiniMax	minimax-m2.7	Text	Text
MiniMax	minimax-m2.5	Text	Text

✅

모델 목록 안내

위 표는 게이트웨이 GET /v1/models로 조회 가능한 호출 가능 모델을 정리한 것입니다. DeepSeek은 deepseek-v4-pro · deepseek-v4-flash 두 변종으로 제공되며, deepseek-v4(bare ID)로는 호출되지 않습니다. gpt-5.5-pro, hy3-preview는 현재 계정 리전에서 지원되지 않아 표에서 제외했습니다.

모델 스펙 · 호출 정책

💡

핵심 전제 — 게이트웨이 패스스루(passthrough) 구조

Text Generation은 OpenAI / Anthropic 호환 프로토콜을 그대로 전달(proxy)하는 게이트웨이입니다. 따라서 Context Window · Max Output · 입출력 모달리티 · reasoning 여부 등 모델 자체 스펙은 원본 제공사(OpenAI / Google / Anthropic / xAI 등)의 모델 스펙을 그대로 따릅니다. Tencent VOD 측은 이 값들을 별도로 재정의하거나 축소하지 않으며, /v1/models는 호출 가능한 model ID 목록만 반환할 뿐 스펙 메타데이터(context/caps)는 포함하지 않습니다.

B. 모델 스펙 (5~9번)

#	항목	기준 / 답변
5	Context Window (최대 입력 토큰)	원본 모델 스펙과 동일. 게이트웨이가 별도 캡을 두지 않습니다. 예: `gpt-5.x`·`cd-opus-4.x`·`gemini-3.x` 모두 각 제공사 공식 문서의 context window를 그대로 적용. 정확한 수치는 각 제공사 모델 카드 참조.
6	Max Output (최대 생성 토큰)	원본 모델 스펙과 동일. 요청 시 `max_tokens`로 상한 지정. 미지정 시 모델 기본 상한 적용.
7	Type (chat / reasoning)	요청 파라미터로 제어합니다. `thinking_enabled=true` 또는 `reasoning_effort`(`none`~`xhigh`)를 지원하는 모델이 reasoning(thinking) 계열입니다. 대표 reasoning 계열: `gpt-5.x`(reasoning), `gk-4-20-reasoning`·`gk-4-1-fast-reasoning`, `gemini--pro` thinking, `cd-opus-`(extended thinking), `deepseek-v3.2`. 나머지(`-chat`, `-nano`/`*-flash-lite` 등)는 chat 위주.
8	입력 지원 (Text/Image/Audio/Video/File)	위 5.3 표의 「지원 입력」 열로 확인. 요약: OpenAI·GK·CD = Text + Image, Gemini = Text + Image + Audio + Video + File(가장 넓음), MiniMax·Kimi·GLM·DeepSeek = Text. (멀티모달은 5.4 Part 객체의 `image_url`/`input_audio`/`file_url` 사용)
9	출력/기능 지원 (Tools/Code 등)	Tools(Function Calling): 전 모델 지원(`tools`/`tool_choice` 파라미터, 단 Gemini는 function 도구만). Code: 텍스트 출력의 일부로 전 모델 가능(`gpt-5.3-codex`는 코드 특화). 이미지 생성 출력은 미지원 — 본 Text Generation은 텍스트 출력 전용이며, 이미지 생성은 Image Generation API를 사용하십시오. JSON 강제 출력은 `response_format` 지원.

C. 호출 정책 (10~12번)

#	항목	기준 / 답변
10	Rate limit (RPM/TPM)	기본값: 30 RPM · 30만 TPM이 계정/Token 단위로 적용됩니다(모델별 차등이 아니라 게이트웨이 공통 기본값). 모델별 개별 RPM/TPM 차등표는 공개 제공되지 않으며, 더 높은 한도가 필요하면 정식 접속 후 담당자에게 상향 신청하십시오. (호출량 자체의 누적 한도는 4. AIGC Quota 관리로 별도 제어)
11	거부 파라미터 (temperature/top_p/top_k)	게이트웨이는 파라미터를 그대로 전달하므로, 거부 여부는 원본 모델 정책을 따릅니다. 특히 reasoning(thinking) 계열은 `temperature`·`top_p`·`top_k`를 무시하거나 거부하는 경우가 많습니다(예: OpenAI reasoning 계열은 `temperature` 고정, 일부는 1 이외 값 거부). reasoning 호출 시에는 `reasoning_effort`로 제어하고 샘플링 파라미터는 생략하는 것을 권장합니다. `top_k`는 OpenAI 프로토콜 표준 파라미터가 아니므로 Anthropic/Gemini 경로에서만 유효합니다.
12	별칭 ↔ 원본 스펙 대응	모델 ID는 단순 별칭(alias)일 뿐, 별도 캡 축소 없이 원본 모델 스펙을 그대로 사용합니다. 즉 `cd-opus-4.8` = Claude Opus 4.8과 동일한 context·output·기능 캡입니다(Tencent가 별도 캡을 두지 않음). 접두사 규칙: 아래 표 참조.

※ 12번 질문(별칭 대응) 명확화 — 모델 ID 접두사는 원본 제공사를 가리키는 별칭 규칙이며, 스펙은 원본과 동일합니다:

접두사	원본 제공사	예시 (게이트웨이 ID → 원본 모델)
gpt-	OpenAI	`gpt-5.5` → GPT-5.5 (스펙 동일)
gemini-	Google	`gemini-3.5-flash` → Gemini 3.5 Flash
cd-	Anthropic (Claude)	`cd-opus-4.8` → Claude Opus 4.8
gk-	xAI (Grok)	`gk-4.3` → Grok 4.3
deepseek-	DeepSeek	`deepseek-v4-pro` → DeepSeek V4 Pro
glm-	Zhipu	`glm-5.1` → GLM-5.1
kimi-	Moonshot	`kimi-k2.6` → Kimi K2.6
minimax-	MiniMax	`minimax-m2.7` → MiniMax M2.7

📌

스펙 정밀 수치가 필요할 때

Context Window·Max Output의 정확한 토큰 수, 모델별 RPM/TPM 차등표는 공개 문서로 일괄 제공되지 않습니다. (1) 모델 자체 스펙은 각 원본 제공사 공식 모델 카드를 기준으로 하고, (2) 게이트웨이 차원의 한도(기본 30 RPM·30만 TPM 상향 등)는 담당자에게 문의해 계정별로 확인하십시오.

5.4 Request Parameters (OpenAI Completions)

💡

Tip

Anthropic, Responses 프로토콜 파라미터는 각 공식 문서를 참조하십시오.

Parameter		Type	Description
model	required	String	AI 모델 지정 (예: `gpt-5.1`, `cd-sonnet-4.6`)
messages	required	Array	대화 메시지 목록. 각 메시지는 `role`과 `content`를 포함
stream	required	Boolean	스트리밍 여부. `true`: SSE 스트리밍 응답
thinking_enabled	optional	Boolean	추론(CoT) 모드 활성화. 지원 모델에서만 사용 가능
reasoning_effort	optional	String	추론 강도. 값: `none` / `minimal` / `low` / `medium` / `high` / `xhigh`. thinking_enabled와 동시 설정 시 reasoning_effort 우선 적용
temperature	optional	Float	출력 무작위성 (0~2, 기본 0.7)
max_tokens	optional	Integer	최대 생성 토큰 수
tools	optional	Array of ChatCompletionTool	도구 목록 (Function Calling). OpenAI 공식 문서 참조
tool_choice	optional	ChatCompletionToolChoiceOption	도구 선택 방식 (`"auto"` / `"none"` / `"required"` / 특정 도구 지정)
response_format	optional	Object	출력 형식 지정 (예: `{"type": "json_object"}`)

messages 배열 내 객체 구조

Field	Type	Description
role	String	`system`: 시스템 지시 \| `user`: 사용자 \| `assistant`: AI 응답 \| `tool`: 도구 결과
content	String \| Array of Part	String일 때: 텍스트 메시지. Array일 때: Part 객체 배열 (멀티모달). role이 tool일 때: 도구 출력 결과
tool_calls	Array	role이 assistant일 때: 모델이 요청하는 도구 호출 목록 (OpenAI 프로토콜 참조). Gemini는 function 도구만 지원
tool_call_id	String	role이 tool일 때: 응답 중 tool_calls에 포함된 도구 호출 ID
extra_content	ExtraContent	Gemini 모델: role이 assistant일 때 추론 서명(thought_signature) 포함 가능

Part 객체 구조

Field	Type	Description
type	String	`text`: 텍스트 \| `image_url`: 이미지 URL \| `input_audio`: 오디오 \| `file`: 파일/비디오
text	String	type이 text일 때 필수. 메시지 텍스트 내용
image_url	String	type이 image_url일 때 필수. 이미지 URL (data URL scheme 지원, 70MB 이내)
input_audio	Object	type이 input_audio일 때 필수
└ data	String	오디오 데이터 Base64 인코딩
└ format	String	오디오 포맷 (mp3 / wav)
file_name	String	파일/비디오 이름
file_url	String	type이 file일 때 필수. 파일/비디오 URL (70MB 이내)
extra_content	ExtraContent	Gemini 모델: 파일 분석 시 media_resolution, fps 제어 가능

ExtraContent 구조 (Gemini 전용)

Field	Type	Description
google	Object	Gemini 모델 전용 설정
└ fps	Float	비디오 프레임레이트 지정 (Gemini 비디오 분석 시)
└ media_resolution	String	입력 미디어 처리 해상도 제어
└ thought_signature	String	모델 출력: 추론 서명 (응답 시 자동 포함)

6. 호출 예시

각 프로토콜 묶음 내부 순서는 cURL → SDK 순으로 통일했습니다.

6.1 OpenAI Completions

URL: https://text-aigc.vod-qcloud.com/v1/chat/completions

POST/v1/chat/completions

cURL 예시

Bash cURL

curl -X POST https://text-aigc.vod-qcloud.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d '{
    "model": "gpt-5.1",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [
      {"role": "user", "content": "who are you?"}
    ]
  }'

OpenAI SDK 예시

Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://text-aigc.vod-qcloud.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5.1",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hi, how are you?"},
    ],
)
print(response.choices[0].message.content)

6.2 Anthropic Messages

URL: https://text-aigc.vod-qcloud.com/v1/messages

POST/v1/messages

지원 모델: CD 시리즈, MiniMax (MiniMax 공식 권장)

cURL 예시

Bash cURL

curl https://text-aigc.vod-qcloud.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $YOUR_API_KEY" \
  -d '{
    "max_tokens": 1024,
    "messages": [{"content": "Hello, world", "role": "user"}],
    "model": "cd-sonnet-4.6"
  }'

Anthropic SDK 예시

Python Anthropic SDK

import anthropic

client = anthropic.Anthropic(
    api_key="$YOUR_API_KEY",
    base_url="https://text-aigc.vod-qcloud.com/"
)

message = client.messages.create(
    model="cd-sonnet-4.6",
    max_tokens=1000,
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": [{"type": "text", "text": "Hi, how are you?"}]}
    ]
)
for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Text: {block.text}")

6.3 Responses API

URL: https://text-aigc.vod-qcloud.com/v1/responses

POST/v1/responses

지원 모델: GPT 시리즈

cURL 예시

Bash cURL

curl https://text-aigc.vod-qcloud.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.1",
    "instructions": "You are a helpful assistant.",
    "input": "Hello!",
    "stream": true
  }'

OpenAI SDK 예시

Python OpenAI SDK (Responses)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://text-aigc.vod-qcloud.com/v1"
)

response = client.responses.create(
    model="gpt-5.1",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Hello, how are you?"}
            ]
        }
    ],
    stream=True
)
for event in response:
    print(event)

7. Response 처리

7.1 Response Parameters

Parameter	Type	Description
id	String	응답 고유 ID
object	String	객체 유형 (예: `chat.completion`)
created	Integer	생성 타임스탬프 (Unix)
model	String	사용된 모델명
choices[].index	Integer	선택지 인덱스
choices[].message.role	String	응답 역할 (`assistant`)
choices[].message.content	String	응답 내용
choices[].message.reasoning_content	String	추론 과정 (thinking 모드 시)
choices[].finish_reason	String	종료 이유 (`stop`, `length`, `tool_calls`)
usage.prompt_tokens	Integer	입력 토큰 수
usage.completion_tokens	Integer	출력 토큰 수
usage.total_tokens	Integer	총 토큰 수
usage.prompt_tokens_details.cached_tokens	Integer	캐시된 입력 토큰 수 (캐시 hit 시)
usage.completion_tokens_details	Object	출력 토큰 상세 내역
usage.completion_tokens_details.reasoning_tokens	Integer	추론 토큰 수 (completion_tokens에 포함됨, 별도 가산 아님)

JSON Response Example

200

ℹ

Token 검산 공식

total_tokens = prompt_tokens + completion_tokens
reasoning_tokens ⊆ completion_tokens (reasoning은 completion 안에 포함, 별도 가산 없음)
일반 모델(gpt-5-mini 등)도 자동 reasoning이 발생할 수 있음 — reasoning_tokens > 0이 reasoning 전용 모델만의 특성은 아닙니다.

ℹ

취소(abort) 정책

별도 abort/cancel API는 제공되지 않습니다. 진행 중 요청 취소는 HTTP connection close로만 가능하며, 서버 측 inference 즉시 중단은 보장되지 않습니다. 정산은 DescribeAigcUsageData API 일자별 집계를 단일 진실 소스로 사용하십시오.

ℹ

reasoning_content 노출 차이

deepseek-v3.2만 choices[0].message.reasoning_content 본문이 노출됩니다. 다른 reasoning 모델(gpt-5.5, gk-4-1-fast-reasoning)은 hidden chain-of-thought로 token 카운트만 반환됩니다.

✓

Tx-User-Session-Id 캐시 확인

캐시 hit 시 usage.prompt_tokens_details.cached_tokens에 캐시된 토큰 수가 반환됩니다.

7.2 Error Codes

HTTP Code	Description
200	성공
400	요청 파라미터 오류
401	인증 실패
403	권한 부족 또는 서비스 정지
404	모델/엔드포인트 없음
429	Rate Limit 또는 Quota 초과 (`insufficient_quota`) — 자세한 동작은 4.5 한도 초과 시 LLM 응답 참조
5xx	서버/업스트림 오류

ℹ

Note

모든 에러 응답에 request_id 필드가 포함됩니다. 모든 요청은 X-Request-Id 헤더를 반환합니다.

7.3 사용량 조회 — DescribeAigcUsageData

POSTvod.intl.tencentcloudapi.com

지정한 기간의 AIGC 사용량 통계를 규격(Specification) 단위로 조회하는 VOD 액션입니다. AigcType으로 통계 대상(비디오/이미지/텍스트 등)을 선택하며, 규격별로 일자(또는 5분) 단위의 작업 수(Count)와 사용량(Usage)을 반환합니다.

ℹ

조회 범위 · 시간 단위

최근 365일 이내를 조회할 수 있고, 한 번의 조회 기간은 90일을 넘을 수 없습니다. 조회 기간이 1일을 초과하면 일(day) 단위, 그렇지 않으면 5분 단위로 집계됩니다.

Request Parameters

Parameter		Type	Description
StartTime	required	String	시작 일시 (ISO 8601, 예: `2026-06-25T00:00:00+08:00`)
EndTime	required	String	종료 일시. 시작 일시 이상이어야 함 (ISO 8601)
AigcType	required	String	AIGC 유형. `Video` / `Image` / `Text` / `Audio` / `SceneAigcVideo` / `SceneAigcImage` / `SceneAigcTime`
SubAppId	optional	Integer	VOD 애플리케이션 ID. 2023-12-25 이후 개통 계정은 필수
APIKey	optional	String	특정 API Key로 필터
APIKeys.N	optional	Array of String	여러 API Key로 필터

Response Parameters

Parameter	Type	Description
AigcUsageDataSet	Array of Object	규격별 AIGC 통계 목록
AigcUsageDataSet[].Specification	String	AIGC 규격. 모델·버전·해상도 조합으로 표기되며 라인업에 따라 값이 늘어납니다 (예: `H2_1.1_1080P`, `Kling3.0turbo_Voice_1080P`, `MJv81_1k`)
AigcUsageDataSet[].DataSet	Array of Object	해당 규격의 시간 구간별 사용량
AigcUsageDataSet[].DataSet[].Time	String	시간 구간 시작 시각 (ISO 8601). 일 단위일 때 `2026-07-01T00:00:00+08:00`은 7/1(포함)~7/2(미포함)
AigcUsageDataSet[].DataSet[].Count	Integer	작업 수
AigcUsageDataSet[].DataSet[].Usage	Integer	작업 사용량 (비디오=초, 이미지=장 등 유형별 상이)
RequestId	String	요청 고유 ID

JSON Request

{
  "StartTime": "2026-06-25T00:00:00+08:00",
  "EndTime": "2026-07-01T23:59:59+08:00",
  "AigcType": "Video",
  "SubAppId": 1500000000
}

JSON Response

200

{
  "Response": {
    "AigcUsageDataSet": [
      {
        "Specification": "H2_1.1_1080P",
        "DataSet": [
          { "Time": "2026-06-30T00:00:00+08:00", "Count": 0, "Usage": 0 },
          { "Time": "2026-07-01T00:00:00+08:00", "Count": 1, "Usage": 5 }
        ]
      }
    ],
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

해석	의미
Specification	규격(모델·버전·해상도) 단위 집계 키. 고정 enum이 아니므로 유연하게 파싱하는 것이 안전합니다
DataSet[].Count / Usage	해당 규격·해당 시간 구간의 작업 수 / 사용량. 빈 구간은 `0`으로 채워집니다
AigcType별 규격	`Video`는 `H2_1.1_1080P`·`Kling3.0turbo_Voice_1080P`, `Image`는 `MJv81_1k`, `Text`는 `{모델}_input`/`_output`/`_cacheinput`처럼 유형에 따라 규격 체계가 다릅니다

⚠

MPS의 DescribeUsageData와 구분

DescribeAigcUsageData는 VOD 전용 액션입니다. MPS에는 존재하지 않으며(InvalidAction), MPS는 별도의 DescribeUsageData(aigc-video.{ModelName} 형태)로 사용량을 집계합니다.

8. 과금 안내

💰

Pricing

Text Generation 상세 과금 정책은 담당자에게 문의해 주십시오.

9. 실천 튜토리얼

9.1 Claude Code 연동

VOD의 Claude 모델을 Anthropic Claude Code CLI에서 사용하는 방법입니다.

사전 준비

1. VOD 서비스 개통 완료
2. CreateAigcApiToken으로 API Token 발급 완료
3. 사용 가능 모델: CD 시리즈 (cd-opus-4.8, cd-opus-4.7, cd-sonnet-4.6, cd-opus-4.5)

설치

Bash Install

npm install -g @anthropic-ai/claude-code
claude --version

설정: settings.json

경로: ~/.claude/settings.json (파일/폴더 없으면 생성)

JSON ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_TOKEN",
    "ANTHROPIC_BASE_URL": "https://text-aigc.vod-qcloud.com",
    "ANTHROPIC_MODEL": "cd-sonnet-4.6"
  },
  "model": "cd-sonnet-4.6"
}

💡

Tip

ANTHROPIC_BASE_URL에 /v1을 붙이지 않습니다. 모델 변경 시 ANTHROPIC_MODEL과 model 값을 동시에 수정 후 재시작하십시오.

Onboarding 스킵

경로: ~/.claude/.claude.json

JSON ~/.claude/.claude.json

{
  "hasCompletedOnboarding": true
}

실행 및 확인

Bash Launch

claude
# "Yes, I trust this folder" 선택
# /model 입력하여 현재 모델 확인

주의사항

⚠

Limitations

• Token 생성 후 약 1분간 동기화 필요 (401 발생 시 대기)
• 기본 Rate Limit: RPM 10, TPM 10만. 고빈도 사용 시 SubAppId와 함께 조정 요청
• VOD AIGC 기본 콘텐츠 컴플라이언스 검수가 활성화되어 있으며, 민감어 감지 시 400 에러 반환

9.2 Codex 설정

OpenAI Codex CLI에서 VOD 모델을 사용하는 설정 방법입니다.

config.toml 설정

경로:

• Linux/macOS: ~/.codex/config.toml
• Windows: C:\Users\{username}\.codex\config.toml

TOML ~/.codex/config.toml

model = "gpt-5.4-mini"
model_provider = "vod"

[model_providers.vod]
name = "vod"
base_url = "https://text-aigc.vod-qcloud.com/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

auth.json 설정

경로:

• Linux/macOS: ~/.codex/auth.json
• Windows: C:\Users\{username}\.codex\auth.json

JSON ~/.codex/auth.json

{
  "OPENAI_API_KEY": "YOUR_VOD_API_TOKEN"
}

💡

Tip

auth.json에는 OPENAI_API_KEY 필드만 남기고 불필요한 필드는 삭제하십시오. 설정 저장 후 Codex를 재시작하면 적용됩니다.

10. 용량 조회

전체 Text Generation 사용량은 API 또는 콘솔 화면에서 조회 가능합니다.

10.1 API 조회

📎 DescribeAigcUsageData — 기간별 토큰 사용량 및 호출 횟수를 조회합니다.

10.2 콘솔 전체 조회

콘솔 → VOD → 데이터센터 → 용량 통계 → AIGC 탭에서 AI Text Generation 필터를 선택하여 전체 사용량을 확인합니다.

10.3 SubAppId별 조회

콘솔 → VOD → 애플리케이션 관리 → 해당 앱 진입 → 데이터센터 → 용량 통계 → AIGC 탭에서 개별 SubAppId 사용량을 확인합니다.

10.4 실시간 통계 API (Query Statistics)

모델별 · API Key별 호출 통계(요청 수, 에러율, 토큰, 캐시 적중률, 첫 토큰 지연)를 분 단위까지 세밀하게 조회하는 셀프서비스 API입니다. DescribeAigcUsageData(10.1)가 토큰 사용량 중심의 집계라면, 이 API는 성능·품질 모니터링(에러율 · TTFT · 캐시 효율)에 적합합니다.

GET/v1/statistics

항목	값
Base URL	`https://text-aigc.vod-qcloud.com`
Method	`GET`
Path	`/v1/statistics`
Auth	`Authorization: Bearer <api-key>` 또는 `x-api-key: <api-key>`
Content-Type	`application/json`
Rate Limit	`owner_app_id`당 기본 2 req/s

🔐

쿼리 권한 (테넌트 격리)

API Key에서 파싱한 OwnerAppid가 Query의 owner_app_id와 반드시 일치해야 합니다. 불일치 시 403 permission_denied를 반환하여 테넌트 간 무단 조회를 차단합니다.

Query 파라미터

파라미터		타입	기본값	설명
owner_app_id	required	uint64	-	테넌트 APPID. token이 귀속된 OwnerAppid와 일치해야 함
granularity	required	String	-	시간 단위. `1m` / `5m` / `1h` 중 택1
start_time	required	String	-	시작 시각(RFC3339, 닫힌구간). 예: `2026-05-26T10:00:00Z`
end_time	required	String	-	종료 시각(RFC3339, 닫힌구간)
api_key	optional	String	-	지정 API Key로 필터링
model	optional	String	-	지정 모델명으로 필터링
merge_api_key	optional	Bool	false	`true`면 `(owner_app_id, model, timestamp)` 기준으로 모든 API Key를 한 행으로 집계. 테넌트 총괄 뷰에 적합
page	optional	Int	1	페이지 번호(1부터). 잘못된 값은 1로 보정
page_size	optional	Int	100	페이지 크기. 최대 1000(초과 시 1000으로 절삭)

데이터 보존 기간 (TTL)

Granularity	Collection	TTL
1m	`coll1m`	31일
5m	`coll5m`	31일
1h	`coll1h`	90일

응답 구조

Top Level — data는 timestamp 내림차순으로 정렬됩니다.

JSON Response

{
  "total": 1234,
  "page": 1,
  "page_size": 100,
  "data": [ /* StatQueryRecord[] */ ]
}

필드	타입	설명
total	int64	조건을 만족하는 레코드 총 개수(`merge_api_key=true`면 집계 후 그룹 수)
page	int	현재 페이지 번호
page_size	int	페이지 크기
data	array	레코드 배열(StatQueryRecord), timestamp 내림차순

StatQueryRecord

필드	타입	설명
timestamp	String	시간 윈도우 시작점(RFC3339)
model	String	모델명
owner_app_id	uint64	테넌트 APPID
api_key	String	API Key. `merge_api_key=true`면 빈 문자열
total_requests	int64	총 요청 수
error_requests	int64	에러 요청 수(4XX + 5XX)
error_rate	float64	에러율(%) = error_requests / total_requests × 100
cache_input_tokens	int64	캐시 적중 입력 토큰 수
cache_hit_rate	float64	캐시 적중률(%) = cache_input_tokens / input_tokens × 100
total_tokens	int64	총 토큰 수
input_tokens	int64	입력 토큰 수
output_tokens	int64	출력 토큰 수
first_token_count	int64	첫 토큰 지연 샘플 수(실제로 첫 토큰을 생성한 요청만 집계)
first_token_avg_ms	float64	첫 토큰 지연 평균(ms, TTFT)

에러 응답

에러는 공통 JSON 포맷으로 반환됩니다.

JSON Error

{
  "error": {
    "message": "...",
    "type": "invalid_request_error"
  },
  "request_id": "..."
}

HTTP	type	발생 조건
400	`invalid_request_error`	owner_app_id 누락/비정상, granularity 누락/비정상, start_time/end_time 누락 또는 포맷 오류
401	`invalid_request_error`	Authorization 헤더 누락 또는 비어있음
403	`permission_denied`	token의 OwnerAppid와 owner_app_id 불일치
405	`invalid_request_error`	GET 이외의 메서드
429	`rate_limit_exceeded`	단일 owner_app_id 한도 초과(기본 2 req/s)
500	`server_error`	DB 쿼리/디코딩 실패
503	`server_error`	통계 서비스 미초기화(statCollector == nil)

요청 예시

① 특정 APPID · 특정 모델의 최근 1시간 분 단위 데이터

Bash 1m · model filter

curl -G 'https://text-aigc.vod-qcloud.com/v1/statistics' \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  --data-urlencode 'owner_app_id=1234567890' \
  --data-urlencode 'granularity=1m' \
  --data-urlencode 'model=gpt-5.1' \
  --data-urlencode 'start_time=2026-06-09T17:00:00+08:00' \
  --data-urlencode 'end_time=2026-06-09T18:00:00+08:00' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=100'

② 특정 APPID 전체를 테넌트 단위로 API Key 합산한 시간 단위 데이터

Bash 1h · merge_api_key

curl -G 'https://text-aigc.vod-qcloud.com/v1/statistics' \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  --data-urlencode 'owner_app_id=1234567890' \
  --data-urlencode 'granularity=1h' \
  --data-urlencode 'start_time=2026-06-01T00:00:00Z' \
  --data-urlencode 'end_time=2026-06-09T00:00:00Z' \
  --data-urlencode 'merge_api_key=true'

③ 특정 API Key로 필터링(x-api-key 헤더 사용)

Bash 5m · api_key filter

curl -G 'https://text-aigc.vod-qcloud.com/v1/statistics' \
  -H 'x-api-key: sk-xxxxxxxx' \
  --data-urlencode 'owner_app_id=1234567890' \
  --data-urlencode 'api_key=sk-aaa' \
  --data-urlencode 'granularity=5m' \
  --data-urlencode 'start_time=2026-06-09T00:00:00Z' \
  --data-urlencode 'end_time=2026-06-09T12:00:00Z'

응답 예시

JSON 200 OK

{
  "total": 2,
  "page": 1,
  "page_size": 100,
  "data": [
    {
      "timestamp": "2026-06-09T17:59:00+08:00",
      "model": "gpt-5.1",
      "owner_app_id": 1234567890,
      "api_key": "sk-aaa",
      "total_requests": 120,
      "error_requests": 3,
      "error_rate": 2.5,
      "cache_input_tokens": 5400,
      "cache_hit_rate": 30.0,
      "total_tokens": 36000,
      "input_tokens": 18000,
      "output_tokens": 18000,
      "first_token_count": 117,
      "first_token_avg_ms": 432.5
    },
    {
      "timestamp": "2026-06-09T17:58:00+08:00",
      "model": "gpt-5.1",
      "owner_app_id": 1234567890,
      "api_key": "sk-aaa",
      "total_requests": 105,
      "error_requests": 0,
      "error_rate": 0,
      "cache_input_tokens": 4200,
      "cache_hit_rate": 28.0,
      "total_tokens": 31500,
      "input_tokens": 15000,
      "output_tokens": 16500,
      "first_token_count": 105,
      "first_token_avg_ms": 410.2
    }
  ]
}

📌

동작 세부 사항

• 시간 구간: start_time / end_time은 닫힌구간($gte / $lte)입니다.
• 정렬·페이징: 기본 timestamp 내림차순. skip = (page-1) × page_size.
• 첫 토큰 지연 샘플: first_token_count는 실제로 첫 토큰을 생성한 요청만 누적합니다. 첫 토큰 전에 실패한 순수 에러는 분모에서 제외되므로, first_token_avg_ms는 첫 토큰 출력에 성공한 요청의 평균 지연을 의미합니다.
• cache_hit_rate는 클램핑 없이 공식대로 계산되므로, 캐시 입력 토큰이 입력 토큰보다 많은 윈도우에서는 100%를 초과할 수 있습니다.

10.5 Request Logs 조회 (Request Logs)

개별 요청 단위의 로그를 조회하는 API입니다. 통계(10.4)가 집계값이라면, 이 API는 요청 하나하나(모델 · 상태코드 · 토큰 · TTFT · TPS · 총 지연)를 최신순으로 반환합니다. 특정 req_id로 단건 추적하거나, 에러 요청만 필터링할 때 사용합니다. 웹 UI는 https://text-aigc.vod-qcloud.com/v1/stat-ui/logs.html에서 제공됩니다.

GET/v1/request-logs

항목	값
Base URL	`https://text-aigc.vod-qcloud.com`
Method	`GET`
Path	`/v1/request-logs`
Auth	`Authorization: Bearer <api-key>` 또는 `x-api-key: <api-key>`
Rate Limit	기본 2 req/s
페이징	Keyset 커서 페이징(`scroll_token`, total 없음)
정렬	`timestamp DESC, _id DESC` (최신 우선)

🔐

쿼리 권한 (테넌트 격리)

API Key의 OwnerAppid가 Query의 app_id와 반드시 일치해야 합니다. 불일치 시 403 permission_denied를 반환합니다. 메인 앱 호출자는 해당 app_id의 모든 sub_app_id를 조회할 수 있으며(sub_app_id는 선택적 필터), 서브 앱 호출자의 sub_app_id는 자신의 값으로 강제 대체됩니다.

Query 파라미터

파라미터		타입	설명
app_id	required	uint64	메인 App ID. token의 OwnerAppid와 일치해야 함
start_time	required	RFC3339	시간 창 시작(예: `2026-06-22T00:00:00+08:00`). `req_id` 제공 시 선택
end_time	required	RFC3339	시간 창 종료. `req_id` 제공 시 선택
req_id	optional	String	요청 ID 정확 조회. 제공 시 `start_time`/`end_time` 선택으로 전환
sub_app_id	optional	uint64	서브 App ID 필터(서브 앱 호출자는 무시·강제 대체)
api_key	optional	String	완전한 api_key 정확 매칭(마스킹된 값 불가)
model	optional	String	모델명 정확 매칭
api_type	optional	String	`completions` / `responses` / `anthropic`
is_error	optional	Bool	에러 요청만 조회
min_status_code / max_status_code	optional	Int	상태코드 하한/상한(포함)
page_size	optional	Int	페이지당 건수. 기본 50, 범위 [1, 200]
scroll_token	optional	String	이전 응답의 `scroll_token`. 다음 페이지 조회용

응답 필드

필드	타입	설명
page_size	Int	실제 적용된 페이지 크기
scroll_token	String	다음 페이지 커서. 빈 문자열이면 마지막 페이지
data[].timestamp	RFC3339	요청 시작 시각
data[].req_id	String	게이트웨이 요청 ID
data[].chat_id	String	백엔드 모델이 반환한 대화 ID
data[].status_code	Int	클라이언트에 반환된 HTTP 상태코드
data[].model	String	모델명
data[].app_id / sub_app_id	uint64	메인 / 서브 App ID
data[].api_key	String	마스킹된 api_key(앞 8자 + `****`)
data[].ip	String	클라이언트 IP
data[].api_type	String	입구 프로토콜: completions / responses / anthropic
data[].stream	Bool	스트리밍 응답 여부
data[].is_error	Bool	에러 요청 여부(status_code ≥ 400)
data[].input_tokens / output_tokens / cache_input_tokens / total_tokens	Int64	입력 / 출력 / 캐시 적중 / 총 토큰
data[].tps	Float	생성 단계 tokens/초
data[].ttft	Float	첫 토큰 지연(초, Time To First Token)
data[].total	Float	엔드투엔드 총 소요(초)

Shell 최근 하루 에러 요청 조회

curl -G 'https://text-aigc.vod-qcloud.com/v1/request-logs' \
  -H 'Authorization: Bearer $YOUR_API_TOKEN' \
  --data-urlencode 'app_id=100001' \
  --data-urlencode 'start_time=2026-06-21T00:00:00+08:00' \
  --data-urlencode 'end_time=2026-06-22T00:00:00+08:00' \
  --data-urlencode 'is_error=true' \
  --data-urlencode 'page_size=100'

JSON Response

200

{
  "page_size": 50,
  "scroll_token": "eyJ0cyI6IjIwMjYtMDYtMjJUMTA6MDA6MDBaIiwiaWQiOiI2NTc...",
  "data": [
    {
      "timestamp": "2026-06-22T14:05:32+08:00",
      "req_id": "abc123",
      "chat_id": "chatcmpl-xxx",
      "status_code": 200,
      "model": "gpt-5.1",
      "app_id": 100001,
      "sub_app_id": 200001,
      "api_key": "sk-vod-a****",
      "ip": "1.2.3.4",
      "api_type": "completions",
      "stream": true,
      "is_error": false,
      "input_tokens": 1234,
      "output_tokens": 567,
      "cache_input_tokens": 100,
      "total_tokens": 1801,
      "tps": 35.4,
      "ttft": 0.823,
      "total": 16.012
    }
  ]
}

HTTP	error	조건
400	`invalid_request_error`	파라미터 형식 오류(app_id/sub_app_id/is_error/status_code/time 파싱 실패, scroll_token 무효, req_id 없이 시간범위 미제공)
401	—	인증 헤더 누락 또는 비정상
403	`permission_denied`	app_id ≠ token의 OwnerAppid
405	`invalid_request_error`	GET 이외의 메서드
429	`rate_limit_exceeded`	조회 레이트리밋 초과
500 / 503	`server_error`	DB 조회/디코딩 실패 / 서비스 미준비

📌

동작 약정

• 시간 범위 필수: req_id를 주지 않으면 start_time·end_time 모두 필수(RFC3339).
• 커서 전용 페이징: 랜덤 점프·이전 페이지 이동 불가(total·page 없음). 이전 페이지가 필요하면 클라이언트가 토큰을 캐시해야 합니다. scroll_token이 빈 문자열이면 마지막 페이지입니다.
• 안정 정렬: 동일 timestamp도 _id를 tiebreaker로 사용해 중복/누락이 없습니다.
• api_key 마스킹: 응답의 api_key는 마스킹되지만, 필터 입력은 완전한 key여야 합니다.
• page_size 상한 200, 조회 타임아웃 20초, 데이터 TTL: 오래된 로그는 자동 정리되어 TTL 범위를 벗어난 시간 창은 빈 결과를 반환합니다.

11. Operation API

운영·모니터링을 위한 조회 API 모음입니다. 게이트웨이(text-aigc.vod-qcloud.com)가 제공하는 API는 Authorization: Bearer <api-key>로, VOD Cloud API는 TC3-HMAC-SHA256 서명으로 호출합니다. 응답 지연 모니터링 · 호출/감사 로그 · Quota 현황 · 모델별 토큰 사용량을 확인할 수 있습니다.

목적	API	제공
응답 지연 · 품질 통계	`/v1/statistics`	게이트웨이
호출 · 감사 로그	`/v1/request-logs`	게이트웨이
모델 카탈로그	`/v1/models`	게이트웨이
Quota 현황	`DescribeAigcQuotas`	VOD Cloud API
규격별 사용량 · 토큰	`DescribeAigcUsageData`	VOD Cloud API

11.1 /v1/statistics — 모델·API Key별 집계 통계

GETtext-aigc.vod-qcloud.com/v1/statistics

지정 기간을 시간 단위(granularity = 1m/5m/1h)로 나누어 모델 × API Key 단위로 요청 수·에러율·토큰·캐시 적중률·첫 토큰 지연(TTFT)을 집계합니다. 응답 속도/지연시간 및 오류 모니터링에 사용합니다.

파라미터		설명
owner_app_id	required	테넌트 APPID. 토큰의 OwnerAppid와 일치해야 함
granularity	required	시간 단위 `1m` / `5m` / `1h`
start_time / end_time	required	ISO 8601 시간 창

Shell Request

curl -G 'https://text-aigc.vod-qcloud.com/v1/statistics' \
  -H 'Authorization: Bearer $YOUR_API_TOKEN' \
  --data-urlencode 'owner_app_id=100000000' \
  --data-urlencode 'granularity=1h' \
  --data-urlencode 'start_time=2026-07-01T00:00:00+08:00' \
  --data-urlencode 'end_time=2026-07-02T00:00:00+08:00'

JSON Response

200

{
  "total": 1, "page": 1, "page_size": 100,
  "data": [
    {
      "timestamp": "2026-07-01T14:00:00Z",
      "model": "gpt-5.5",
      "owner_app_id": 100000000,
      "api_key": "sk-vod-x****",
      "total_requests": 2,
      "error_requests": 0,
      "error_rate": 0,
      "rate_limit_requests": 0,
      "cache_input_tokens": 0,
      "cache_hit_rate": 0,
      "total_tokens": 2652,
      "input_tokens": 2282,
      "output_tokens": 370,
      "first_token_count": 0,
      "first_token_avg_ms": 0
    }
  ]
}

📡

지연 · 상태 지표

first_token_avg_ms(첫 토큰 평균 지연) · error_rate(에러율) · rate_limit_requests(레이트리밋 건수)로 응답 속도와 서비스 상태를 모니터링합니다.

11.2 /v1/request-logs — 건별 호출 · 감사 로그

GETtext-aigc.vod-qcloud.com/v1/request-logs

개별 요청을 최신순으로 반환합니다. 요청 ID·모델·상태코드·IP·토큰과 함께 건별 지연(ttft·tps·total)을 제공합니다. 커서(scroll_token) 페이징이며 timestamp DESC, _id DESC로 정렬됩니다.

파라미터		설명
app_id	required	메인 App ID. 토큰의 OwnerAppid와 일치해야 함
start_time / end_time	required*	ISO 8601. `req_id` 제공 시 선택
req_id	optional	요청 ID 정확 조회
model / api_type / is_error	optional	모델 · 프로토콜(completions/responses/anthropic) · 에러 필터
min_status_code / max_status_code	optional	상태코드 범위 필터
page_size / scroll_token	optional	페이지 크기(1~200, 기본 50) · 다음 페이지 커서

Shell Request

curl -G 'https://text-aigc.vod-qcloud.com/v1/request-logs' \
  -H 'Authorization: Bearer $YOUR_API_TOKEN' \
  --data-urlencode 'app_id=100000000' \
  --data-urlencode 'start_time=2026-06-25T00:00:00+08:00' \
  --data-urlencode 'end_time=2026-06-27T00:00:00+08:00' \
  --data-urlencode 'is_error=true' \
  --data-urlencode 'page_size=100'

JSON Response

200

{
  "page_size": 1,
  "data": [
    {
      "timestamp": "2026-06-26T02:26:11Z",
      "req_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "chat_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status_code": 200,
      "model": "gpt-5.1",
      "app_id": 100000000,
      "sub_app_id": 200000000,
      "api_key": "sk-vod-x****",
      "ip": "1.2.3.4",
      "api_type": "completions",
      "stream": false,
      "is_error": false,
      "input_tokens": 8,
      "output_tokens": 11,
      "cache_input_tokens": 0,
      "total_tokens": 19,
      "tps": 8.2028,
      "ttft": 0,
      "total": 1.341
    }
  ]
}

📌

동작 약정

scroll_token이 빈 문자열이면 마지막 페이지입니다. 이전 페이지 이동은 지원하지 않으므로 필요 시 클라이언트가 토큰을 캐시합니다. 응답의 api_key는 마스킹되며, 필터 입력은 완전한 key여야 합니다. 오래된 로그는 TTL로 자동 정리됩니다.

11.3 /v1/models — 모델 카탈로그

GETtext-aigc.vod-qcloud.com/v1/models

호출 가능한 모델 목록을 OpenAI 호환 list 포맷으로 반환합니다.

Shell Request

curl 'https://text-aigc.vod-qcloud.com/v1/models' \
  -H 'Authorization: Bearer $YOUR_API_TOKEN'

JSON Response

200

{
  "object": "list",
  "data": [
    { "id": "glm-5",       "object": "model", "created": 1704067200, "owned_by": "zhipu" },
    { "id": "glm-5-turbo", "object": "model", "created": 1704067200, "owned_by": "zhipu" },
    { "id": "gpt-5.2",     "object": "model", "created": 1704067200, "owned_by": "openai" }
  ]
}

11.4 DescribeAigcQuotas — Quota 현황

POSTvod.intl.tencentcloudapi.com · Action=DescribeAigcQuotas

VOD Cloud API. QuotaType별(Text / Image / Video)로 설정된 AIGC quota 목록을 조회합니다.

파라미터		설명
QuotaType	required	`Text` / `Image` / `Video` 중 하나
SubAppId	optional	VOD 애플리케이션 ID

JSON Request

{
  "SubAppId": 1500000000,
  "QuotaType": "Text"
}

JSON Response

200

{
  "Response": {
    "TotalCount": 0,
    "QuotaSet": [],
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

ℹ️

Quota 관리

QuotaSet이 비어 있으면 해당 유형에 별도로 설정된 quota가 없다는 의미입니다. 생성/수정/삭제는 §4. AIGC Quota 관리를 참고하십시오.

11.5 DescribeAigcUsageData — 규격별 사용량 · 토큰

POSTvod.intl.tencentcloudapi.com · Action=DescribeAigcUsageData

VOD Cloud API. AigcType=Text로 조회하면 규격(Specification)이 {모델}_input / _output / _cacheinput로 분리 집계되어, 모델별 입력·출력·캐시 토큰 사용량을 확인할 수 있습니다. 상세 파라미터는 §7.3과 동일합니다.

JSON Request

{
  "StartTime": "2026-06-25T00:00:00+08:00",
  "EndTime": "2026-07-02T23:59:59+08:00",
  "AigcType": "Text",
  "SubAppId": 1500000000
}

JSON Response

200

{
  "Response": {
    "AigcUsageDataSet": [
      {
        "Specification": "Tog5.1_input",
        "DataSet": [
          { "Time": "2026-07-01T00:00:00+08:00", "Count": 0, "Usage": 0 }
        ]
      },
      {
        "Specification": "Tog5.1_output",
        "DataSet": [
          { "Time": "2026-07-01T00:00:00+08:00", "Count": 0, "Usage": 0 }
        ]
      },
      {
        "Specification": "Tog5.1_cacheinput",
        "DataSet": [
          { "Time": "2026-07-01T00:00:00+08:00", "Count": 0, "Usage": 0 }
        ]
      }
    ],
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

12. Q&A

분류	질문	답변
API 호출	tools (Function Calling) 지원 여부	지원합니다. Request Parameters의 tools/tool_choice 파라미터를 참조하십시오.
API 호출	목록에 없는 모델 사용 가능 여부	담당자에게 문의하여 지원 가능 여부를 평가받으세요.
API 호출	system instruction 없이 호출 가능한지	가능합니다. instruction 생략 시 messages의 system role로 설정하십시오.
API 호출	기본 동시 호출 한도	기본 RPM 30, TPM 30만. 정식 접속 후 조정 신청 가능합니다.
Quota	한도 초과 시 어떤 응답이 오나?	HTTP 429 + `{"error":{"type":"insufficient_quota","message":"Text quota exceeded."}}` — 4.5 참조.
법무	AI 호출 관련 컴플라이언스	미디어 처리 AI 관련 기능의 특별 약정을 참조하십시오.

1. Image Generation Overview

범용 이미지 생성 Task를 생성합니다. 텍스트 프롬프트 또는 참조 이미지를 기반으로 이미지를 생성하고 TaskId를 반환합니다.

TaskId를 받은 뒤 결과 조회 API 또는 콜백으로 생성 완료 상태와 결과 URL을 회수합니다.

1.1 API 정보

POSTvod.intl.tencentcloudapi.com

항목	값
Endpoint	`vod.intl.tencentcloudapi.com`
Method	`POST`
X-TC-Action	`CreateAigcImageTask`
X-TC-Version	`2018-07-17`
X-TC-Region	`ap-seoul`

1.2 지원 모델

모델명	설명	버전
GEM	Nano Banana — 고품질 범용 이미지 생성	2.5 3.0 3.1
OG	1K/2K/4K 해상도 이미지 생성	image2_low image2_medium image2_high
Qwen	Qwen 이미지 생성	0925
Seedream	고해상도 AI 아트 생성	4.5 5.0-lite
Kling	이미지 생성 + Outpainting (이미지 확장)	2.1 3.0 3.0-Omni scene
Vidu	고품질 이미지 생성	q2
Jimeng	Jimeng 이미지 생성 엔진	4.0
MJ (Midjourney)	고품질 아트 이미지, 참조 이미지 + Prompt 기반	v7 v8.1 v8.2 niji_7
GPT-Image2	OpenAI 이미지 생성/편집, 다중 출력, 마스크, 투명 레이어	gpt-image-2

1.3 Supported Model Options

모델별 지원 해상도 · 종횡비(AspectRatio) · 최대 참조 이미지 수와, 해상도/종횡비를 지정하는 방식을 정리한 표입니다. 종횡비 지정 경로는 모델마다 다릅니다 — OutputConfig.AspectRatio(GEM · Kling · Vidu · OG), prompt 내 기술(Seedream · MJ), ExtInfo로 픽셀 직접 주입(Jimeng width/height · Hunyuan size · Qwen 자유).

⚠

size 지정 가능 모델

{"size":"2048x2048"} 같은 픽셀 직접 지정은 모든 모델이 받지 않습니다. size(또는 width/height)를 받는 모델은 Jimeng · Hunyuan · Qwen 뿐입니다. Hunyuan은 면적 상한(width×height ≤ 1024×1024)이 있어 2048×2048은 거부되고, Qwen은 2048×2048까지 허용됩니다. 그 외 모델은 AspectRatio + Resolution(1K/2K/4K)으로 크기를 지정합니다.

ModelName	Version	Resolution	Aspect ratio control	Max ref images	Notes
GEM (GG)	2.5 / 3.0 / 3.1	1K / 2K / 4K (default 1K); 3.1 adds 512	`AspectRatio`: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (3.1 also 1:4, 1:8, 4:1, 8:1)	3 (2.5) / 14 (3.0, 3.1)	Nano Banana. AspectRatio set via OutputConfig.
Kling	2.1 / 3.0 / 3.0-Omni / O1	1K / 2K (2.1, 3.0); 1K / 2K / 4K (3.0-Omni, O1), default 1K	`AspectRatio`: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 (3.0-Omni, O1 add auto)	4 (2.1) / 1 (3.0) / 10 (3.0-Omni, O1)	3.0-Omni / O1 support subject reference.
Seedream (SI)	4.0 / 4.5 / 5.0-lite	1K / 2K / 4K (4.0, default 1K); 2K / 4K (4.5, default 2K); 2K / 3K / 4K (5.0-lite, default 2K)	Set in prompt: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9	14	4.0 multi-output: state image count in prompt + `ExtInfo` `{"sequential_image_generation":"auto"}`.
Jimeng	4.0	Set via `ExtInfo`, range 1024×1024 – 4096×4096	Driven by `width` / `height` in `ExtInfo`	10	Pixel size injected: `ExtInfo` `{"width":1920,"height":1080}`.
Vidu	q2	1080p / 2K / 4K (default 1080p)	`AspectRatio`: 16:9, 9:16, 1:1, 3:4, 4:3, 21:9, 2:3, 3:2	7	—
Hunyuan	3.0	Set via `ExtInfo`; each side 512–2048px and width×height ≤ 1024×1024 (default 1024×1024)	Driven by `size` in `ExtInfo`	3	Pixel size injected: `ExtInfo` `{"size":"728x1024"}`. 360° panorama via `SceneType=3d_panorama`.
Qwen	0925	Free width/height; total pixels 512×512 – 2048×2048 (default 1024×1024)	Free (within pixel range)	1	—
MJ (Midjourney)	v7 / v8.1 / v8.2 / niji_7	Set in prompt	Set in prompt (v8.2의 --q는 1·4만)	3	Native MJ syntax (`--ar`, `--s`, etc.). See §6.2.
OG	image2_low / image2_medium / image2_high	1K / 2K / 4K (default 1K)	`AspectRatio`: 1:1, 3:2, 2:3, 3:4, 4:3, 16:9, 9:16, 21:9, 9:21	16	Multi-output via `OutputImageCount`, up to 8 images.

1.4 Architecture

Architecture Diagram

2. Quickstart

텍스트 프롬프트 한 줄로 첫 이미지 Task를 생성하는 최단 경로입니다. 아래 3 step을 따라 TaskId를 받고, 결과 조회 API로 결과 URL을 회수합니다.

2.1 Step 1 — Endpoint & 인증 헤더

Tencent Cloud Common API Endpoint와 SecretId/SecretKey 기반 TC3-HMAC-SHA256 서명을 사용합니다. 서명 생성 흐름과 raw signed POST 코드는 §4.7 Python raw signed POST 예제를 참고하십시오.

항목	값
Endpoint	`https://vod.intl.tencentcloudapi.com`
X-TC-Action	`CreateAigcImageTask`
X-TC-Version	`2018-07-17`
X-TC-Region	`ap-seoul`
Authorization	`TC3-HMAC-SHA256 Credential=$YOUR_SECRET_ID/...`

2.2 Step 2 — 요청 보내기

아래 cURL 1개를 그대로 실행하면 GEM 3.1 엔진에 prompt-only 요청이 전송되어 TaskId가 반환됩니다.

$YOUR_SECRET_ID, $YOUR_SECRET_KEY, $SUBAPP_ID는 본인 값으로 치환합니다. 전체 인증 헤더(Authorization) 생성은 §4.7 Python raw signed POST 예제를 그대로 사용할 수 있습니다.

200 응답으로 Response.TaskId가 돌아오면 정상입니다. Body 파라미터의 의미는 §3. Request 작성을, 엔진별 차이는 §5. 엔진별 호출 예시를 참조합니다.

Bash Quickstart cURL

curl -X POST https://vod.intl.tencentcloudapi.com \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-TC-Action: CreateAigcImageTask" \
  -H "X-TC-Version: 2018-07-17" \
  -H "X-TC-Region: ap-seoul" \
  -H "Authorization: TC3-HMAC-SHA256 Credential=$YOUR_SECRET_ID/..." \
  -d '{
    "SubAppId": $SUBAPP_ID,
    "ModelName": "GEM",
    "ModelVersion": "3.1",
    "Prompt": "A clean product-style capybara mascot image, studio lighting"
  }'

2.3 Step 3 — TaskId로 결과 조회

DescribeAigcImageTask를 동일한 인증 헤더로 호출하여 결과 상태와 이미지 URL을 회수합니다. 상세 파라미터는 MPS Integration §4. DescribeAigcImageTask 참조.

3. Request 작성

3.1 Input Parameters

Parameter		Type	Description
SubAppId	required	Integer	Application 식별자
ModelName	required	String	이미지 생성 엔진 이름
ModelVersion	required	String	엔진 버전
Prompt	conditional	String	생성 프롬프트. 참조 이미지가 없으면 필수
NegativePrompt	optional	String	원하지 않는 요소 지정
FileInfos.N	optional	Array	참조 이미지 URL 또는 FileId
EnhancePrompt	optional	String	`Enabled` / `Disabled`
OutputConfig	optional	Object	StorageMode, AspectRatio, Resolution 등 — 상세는 §3.2 참조
InputRegion	optional	String	입력 파일 URL의 리전. 해외: `Oversea`
SceneType	optional	String	모델별 Scene 타입
Seed	optional	Integer	결과 재현용 seed
SessionId	optional	String	3일간 중복 요청 방지용 ID
SessionContext	optional	String	콜백 시 함께 전달되는 context 값
TasksPriority	optional	Integer	-10~10 우선순위
ExtInfo	optional	String	모델별 확장 파라미터 전달용 JSON 문자열. 최상위 키 `AdditionalParameters` 안에 모델 고유 옵션(아웃페인팅 확장 비율 등)을 담습니다 — 상세는 §3.3

3.2 OutputConfig 필드

Field	Type	Description
StorageMode	String	`Temporary` / `Permanent`
AspectRatio	String	`1:1`, `16:9`, `9:16`, `4:3`, `3:4` 등 (모델별 상이)
Resolution	String	해상도 — 모델별 상이. GPT-Image2는 `"WxH"` 또는 `"auto"` 지정 가능
ImageCount	Integer	한 요청으로 생성할 이미지 수 (GPT-Image2: 최대 4장)
Background	String	배경 처리. `transparent` 등 (GPT-Image2)
OutputFormat	String	출력 파일 형식 (`png` / `jpg` 등)
InputComplianceCheck	String	입력 콘텐츠 검수 (`Enabled` / `Disabled`) — 일부 모델 필수
OutputComplianceCheck	String	출력 콘텐츠 검수 (`Enabled` / `Disabled`) — 일부 모델 필수

3.3 ExtInfo / AdditionalParameters (모델 확장)

표준 파라미터로 표현할 수 없는 모델 고유 옵션은 ExtInfo 문자열로 전달합니다. 구조는 항상 2중 JSON 인코딩입니다 — 바깥 JSON의 AdditionalParameters 키 값이 다시 JSON 문자열입니다.

⚠

2중 인코딩 구조

ExtInfo = {"AdditionalParameters": "<json-string>"} 이며, 그 값이 다시 모델 파라미터 JSON을 문자열로 인코딩한 것입니다. 즉 모델 파라미터를 두 번 JSON 문자열화해야 합니다.

"ExtInfo": "{\"AdditionalParameters\":\"{\\\"down_expansion_ratio\\\":0.2,\\\"up_expansion_ratio\\\":0.1}\"}"

이미지 생성 모델별 AdditionalParameters

모델 / SceneType	파라미터	설명
Kling 아웃페인팅 `SceneType=image_expand` `ModelVersion=scene`	`down_expansion_ratio` `up_expansion_ratio` `left_expansion_ratio` `right_expansion_ratio`	각 방향으로 캔버스를 확장(outpainting)하는 비율(0~1). 4방향 독립 지정. `OutputImageCount`로 생성 장수 지정 가능
Hunyuan 파노라마 `SceneType=3d_panorama`	—	360° 파노라마(전방위) 이미지 생성. Hunyuan 모델 전용 SceneType
시드 고정 (전 모델 공통)	`Seed`	난수 시드 지정 시 동일 입력에 대해 결과 재현 가능. 미지정 시 매번 랜덤
기타 이미지 생성 모델	—	대부분은 표준 파라미터(`Prompt`/`FileInfos`/`OutputConfig`)만으로 충분. 신규 옵션은 출시 시 본 표에 추가

4. Output & 결과 조회

CreateAigcImageTask는 비동기 API입니다. 호출 즉시 TaskId만 반환하고, 실제 이미지는 백그라운드에서 생성됩니다. 따라서 TaskId로 DescribeTaskDetail을 폴링하여 완료 여부와 결과 URL을 회수하는 2단계 흐름이 필요합니다.

4.1 CreateAigcImageTask 응답

Parameter	Type	Description
TaskId	String	결과 조회용 Task ID. 이후 `DescribeTaskDetail`에 그대로 전달합니다.
RequestId	String	요청 추적용 ID. 문제 발생 시 기술지원 문의에 사용합니다.

4.2 작업 상태 (Lifecycle)

작업은 다음 상태를 순차적으로 거칩니다. FINISH 또는 FAIL이 종료 상태입니다.

WAIT → RUNNING → FINISH 또는 FAIL

상태	설명	권장 동작
WAIT	큐에서 대기 중	2~3초 간격으로 폴링 지속
RUNNING	이미지 생성 처리 중	폴링 지속
FINISH	완료 — 결과 URL 회수 가능	`Output.ImageInfoSet`에서 URL 추출
FAIL	실패	`Message` 확인 후 파라미터 수정·재시도

4.3 DescribeTaskDetail 폴링 예시

생성 요청과 동일한 인증 헤더로 DescribeTaskDetail을 호출합니다. Status가 FINISH가 될 때까지 2~3초 간격으로 반복하십시오.

요청 — DescribeTaskDetailRequest

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "DescribeTaskDetail",
  "region": "ap-seoul",
  "request": {
    "SubAppId": "150003****",
    "TaskId": "150003****-CreateAigcImageTask-xxxxxxxx"
  }
}

응답 — FINISHResponse

{
  "Response": {
    "TaskType": "CreateAigcImageTask",
    "Status": "FINISH",
    "CreateAigcImageTask": {
      "Status": "FINISH",
      "ErrCode": 0,
      "Message": "",
      "Output": {
        "ImageInfoSet": [
          {
            "Url": "https://.../result.png",
            "Width": 1024,
            "Height": 1024
          }
        ]
      }
    },
    "RequestId": "xxxxxxxx"
  }
}

임시 저장(StorageMode: Temporary) 결과 URL은 만료 시간이 짧습니다. 영구 보관이 필요하면 Permanent로 요청하거나 회수 즉시 자체 스토리지로 다운로드하십시오.

4.4 주요 에러 & 대처

에러 유형	원인	대처
모델 버전 미지원	지정한 `ModelVersion`이 존재하지 않음	지원 모델 목록(§6) 확인 후 올바른 버전 선택
해상도 미지원	해당 모델이 지원하지 않는 `Resolution`	모델 특성 표(§6)에서 지원 해상도 선택
종횡비 미지원	해당 모델이 지원하지 않는 `AspectRatio`	모델 특성 표(§6)에서 지원 종횡비 선택
참고 이미지 개수 초과	`FileInfos` 개수가 모델 한도 초과	모델별 한도(GEM 0~3 / Vidu 0~7 / Hunyuan·Kling 1)로 제한
Prompt 누락	참고 이미지도 `Prompt`도 없음	`Prompt` 추가 또는 참고 이미지 제공
SubAppId 누락	서브앱(SubAppId) 미지정	`SubAppId` 지정
참고 이미지 URL 접근 실패	`Type:Url` 참고 이미지에 접근 불가	공인망에서 접근 가능한 URL 사용(Dash 미지원)

5. 엔진별 호출 예시

5.0 공통 호출 골격

모든 엔진은 동일한 endpoint / action / region / auth 위에서 ModelName + ModelVersion + Prompt + OutputConfig만 바뀝니다. 아래 골격을 기준으로 §5.1 표의 엔진별 차이만 끼워 넣으면 됩니다.

Common Request Skeleton

JSON

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "",
    "ModelVersion": "",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1"
    }
  }
}

Common Response

200

{
  "Response": {
    "TaskId": "150003****-AigcImageTask-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXT",
    "RequestId": "XXXXXXXX-****-XXXXXXXXXXXX"
  }
}

5.1 엔진별 차이 매트릭스

#	ModelName	ModelVersion	OutputConfig 권장값	ComplianceCheck	특이사항 / 가이드
1	GEM	`3.1`	`AspectRatio: "1:1"`	—	Quickstart 기본 엔진. prompt-only 동작.
2	Qwen	`0925`	`AspectRatio: "1:1"`	—	—
3	Seedream	`5.0-lite`	`AspectRatio: "1:1"`	—	—
4	Kling	`3.0-Omni`	`AspectRatio: "1:1"`	필수 (Input/Output Enabled)	—
5	Jimeng	`4.0`	`AspectRatio: "1:1"`	—	—
6	MJ	`v7`	`AspectRatio: "16:9"`	—	1요청 = 4장 고정. `--s`/`--c`/`--sref` 등 자체 문법 → §6.2 MJ 가이드
7	Vidu	`q2`	`AspectRatio: "1:1"`	필수 (Input/Output Enabled)	—
8	OG	`image2_high`	`AspectRatio: "1:1"`	—	1K/2K/4K 해상도 (low / medium / high)

GPT-Image2 엔진의 사용 패턴(다중 출력 / 마스크 편집 / 투명 레이어 / 커스텀 사이즈)은 §6.1 GPT-Image2 가이드 참조.

5.2 엔진별 전체 JSON

8개 엔진의 전체 Request Body를 한눈에 비교할 수 있도록 격자로 배치했습니다. 모든 엔진의 응답은 동일하게 { "Response": { "TaskId": "...", "RequestId": "..." } } 형태이며, 이후 DescribeAigcImageTask로 결과를 조회합니다.

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "GEM",
    "ModelVersion": "3.1",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Qwen",
    "ModelVersion": "0925",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Seedream",
    "ModelVersion": "5.0-lite",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Kling",
    "ModelVersion": "3.0-Omni",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1",
      "InputComplianceCheck": "Enabled",
      "OutputComplianceCheck": "Enabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Jimeng",
    "ModelVersion": "4.0",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "MJ",
    "ModelVersion": "v7",
    "Prompt": "A clean product-style capybara mascot, studio lighting, soft shadows --s 250 --c 10 --sref https://your-bucket.cos.ap-seoul.myqcloud.com/style-ref.jpg --sw 500",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "16:9"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Vidu",
    "ModelVersion": "q2",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1",
      "InputComplianceCheck": "Enabled",
      "OutputComplianceCheck": "Enabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "OG",
    "ModelVersion": "image2_high",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "NegativePrompt": "low quality, distorted, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "AspectRatio": "1:1"
    }
  }
}

6. 모델별 상세 가이드

6.1 GPT-Image2

GPT-Image2 모델 상세 가이드

GPT-Image2 기능별 사용법

범용 이미지 생성

JSON Basic Generation

{
  "SubAppId": 1500044236,
  "ModelName": "GPT-Image2",
  "ModelVersion": "gpt-image-2",
  "Prompt": "A professional product photo of wireless earbuds on a marble surface",
  "OutputConfig": {"StorageMode": "Temporary", "AspectRatio": "1:1"}
}

다중 이미지 출력

OutputConfig에 ImageCount를 지정하여 한 요청으로 최대 4장 동시 생성.

투명 레이어 (Transparent Background)

OutputConfig에 OutputFormat: "png" + Background: "transparent" 설정.

마스크 편집 (Inpainting)

FileInfos에 원본 이미지 + 마스크 이미지를 함께 전달합니다. 마스크의 투명 영역이 편집 대상입니다.

커스텀 사이즈 (Custom Size / Auto)

OutputConfig의 Resolution에 "WxH" 형태로 직접 지정하거나 "auto"로 설정.

6.2 MJ (Midjourney)

MJ (Midjourney) 모델 상세 가이드

MJ 기능 목록

기능	상세 설명
Text-to-Image	Prompt를 기반으로 이미지를 생성합니다.
참조 이미지 기반 생성	단일 참조 이미지(JPEG/PNG/WEBP, ≤10MB) 지원. `--iw 0~3`으로 참조 이미지 가중치 조절 (기본값 1)
해상도 규칙	「가로×세로 픽셀」 기준. 원본 해상도 최대 약 104만 픽셀(1024×1024). 임의 커스텀 해상도 불가.
표준 비율 & 해상도	`1:1` 1024×1024 (기본) / `4:5` 819×1024 / `2:3` 682×1024 / `9:16` 576×1024 / `16:9` 1365×768. 확대 시 2배까지 가능.
확대 (Upscale)	Subtle (미세 조정, 원본 충실도 높음) / Creative (예술적 재구성) 2가지 모드. 고정 2배 확대.
출력 수량	단일 요청 시 고정 4장(2×2 격자) 생성. U1~U4로 개별 선택 가능.
핵심 파라미터	`--s 0~1000` 스타일 강도(기본 250) / `--c 0~100` 변동성 (4장 간 차이) / `--sref` 스타일 참조 URL / `--sw 0~1000` 스타일 참조 가중치
고급 기능	부분 재생성 (Vary Region), Pan 확장, Zoom Out, Inpainting 마스크 편집

버전별 차이 (v7 / v8.1 / v8.2 / niji_7)

버전	특징
v8.2	최신 버전 (2026-08 출시). `--q` 품질 단계는 `1`·`4`만 지원 (v7·niji_7의 `1`·`2`·`4`와 다름)
v8.1	이전 최신 버전
v7	레거시 버전. `--q` `1`·`2`·`4` 지원
niji_7	애니·일러스트 특화 버전. 요청당 4장 고정

v8.2 실측: Prompt에 --ar 3:2를 넣어 호출하니 4장이 모두 1344×896으로 생성됐고 작업 시간은 약 20초였습니다. 버전은 ModelVersion: "v8.2"로 지정하며 나머지 호출 구조는 아래 v7 예시와 동일합니다.

MJ 코드 예시

참조 이미지 + 스타일 참조 생성

참조 이미지를 FileInfos로, 스타일 참조를 Prompt의 --sref 플래그로 전달합니다.

JSON MJ v7 — 참조 + 스타일 생성

{
  "SubAppId": 1500044236,
  "ModelName": "MJ",
  "ModelVersion": "v7",
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://example.com/reference-image.png"
    }
  ],
  "Prompt": "A clean product-style capybara mascot, studio lighting, soft shadows --s 250 --c 10 --iw 1.5 --sref https://example.com/style-ref.jpg --sw 500",
  "NegativePrompt": "low quality, distorted, blurry",
  "EnhancePrompt": "Enabled",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "AspectRatio": "16:9"
  }
}

Text-to-Image (기본)

JSON MJ v7 — 기본 생성

{
  "SubAppId": 1500044236,
  "ModelName": "MJ",
  "ModelVersion": "v7",
  "Prompt": "Futuristic cyberpunk city at night, neon lights reflecting on wet streets, cinematic --s 500 --c 30",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "AspectRatio": "16:9"
  }
}

MJ Prompt 파라미터 레퍼런스

파라미터	범위	기본값	설명
`--s`	0~1000	250	스타일 강도. 높을수록 예술적 스타일화 증가
`--c`	0~100	0	변동성. 높을수록 4장 간 차이 증가
`--iw`	0~3	1	참조 이미지 가중치. 높을수록 참조 이미지 반영 강화
`--sref`	URL	—	스타일 참조 이미지 URL
`--sw`	0~1000	100	스타일 참조 가중치
`--ar`	비율	1:1	종횡비 (OutputConfig.AspectRatio와 동일 효과)

💡

Tip

MJ는 단일 요청당 고정 4장을 생성합니다. DescribeTaskDetail 결과에서 4장의 URL이 반환되며, 원하는 이미지를 선택하여 사용합니다. Prompt 내 --sref 등의 플래그는 MJ 자체 문법이며, API 호출 시 Prompt 문자열 안에 그대로 포함시켜 전달합니다.

7. 과금 & 한도

💰

Pricing

Image Generation 상세 과금 정책은 담당자에게 문의해 주십시오.

ℹ️

Quota

Image Generation 한도는 SubAppId 단위로 관리됩니다. Quota 조회/설정 API와 429 응답 처리 흐름은 Text Generation 페이지의 §4. AIGC Quota 관리를 참고하십시오.

1. Video Generation Overview

영상 생성 Task를 생성합니다. 텍스트, 이미지, 첫 프레임 입력을 기반으로 영상을 생성하고 TaskId를 반환합니다.

모델별로 지원 Duration, Resolution, AspectRatio가 다를 수 있으므로 엔진별 예시를 기준으로 시작합니다.

1.1 API 정보

POSTvod.intl.tencentcloudapi.com

항목	값
Endpoint	`vod.intl.tencentcloudapi.com`
Method	`POST`
X-TC-Action	`CreateAigcVideoTask`
X-TC-Version	`2018-07-17`
X-TC-Region	`ap-seoul`

1.2 지원 모델

모델명	설명	버전
Kling	전 기능 영상 모델 — Text/Image/Reference/Motion Control/Lip Sync/Digital Human/Multi-shot/Outpainting/다중 요소 편집	1.6 2.0 2.1 2.5 2.6 3.0 3.0-Omni 3.0-turbo O1 3.0-motion-control
Vidu	Text/Image/First+Last Frame/Reference/Custom Subject/특효 템플릿 지원	q2 q2-turbo q2-pro q3 q3-pro q3-turbo q3-mix q3-drama q3-ad
PixVerse	Text/Image/First+Last Frame/Reference/비디오 편집 지원	V5.6 V6.0 C1
Hailuo (MiniMax Video)	고품질 영상 생성. H3는 네이티브 멀티모달(이미지·영상·오디오 참조 입력)과 음성 동시 생성 지원	02 2.3 2.3-fast H3
GV (Google Veo)	Google AI 영상 생성, 오디오 생성 지원	3.1 3.1-fast
OS (OpenAI Sora)	OpenAI 영상 생성	2.0
Jimeng	Jimeng 영상 생성 엔진	3.0pro
SV	인물 영상 특화 엔진 — 소재(Material) 기반 인물 생성 지원. 인물 사진 기반 영상 제작 시 검열에 매우 민감	1.0-pro 1.0-pro-fast 1.5-pro 1.0-lite-i2v
VS	고품질 영상 생성 엔진 (Text/Image/First+Last Frame/멀티모달 참조)	2.0 2.0-fast 2.0-mini 2.5
Mingmou	Mingmou 영상 생성	1.0
H2	H2 영상 생성 엔진 — Text/Image/Reference	1.0 1.1

1.3 Supported Model Options

모델별 지원 해상도 · 종횡비 · 영상 길이(Duration) · 첫/끝 프레임 · 최대 참조 수 · 오디오 동시 생성 지원 여부를 정리한 표입니다. Duration · Resolution · AspectRatio는 OutputConfig 필드로 지정하며, 허용값은 모델마다 다릅니다.

⚠

duration / resolution / aspect_ratio 호환

{"duration":5,"resolution":"1080P","aspect_ratio":"16:9"} 조합은 Kling · Vidu에서 그대로 동작합니다. Hailuo(6s/10s만) · GV(8s 고정 등) · OS(720P 고정)처럼 길이/해상도가 특정값으로 고정된 모델은 5초 또는 1080P가 불가하니 모델 선택 시 표를 확인하십시오.

ModelName	Version	Resolution	Aspect ratio	Duration	First/last frame	Max reference	A/V sync	Notes
Hailuo	02 / 2.3 / 2.3-fast	768P / 1080P (default 768P)	16:9 only	720P: 6s, 10s / 1080P: 6s	First+last (02 only)	Image-to-video; 2.3-fast single image	No	MiniMax Video.
Hailuo	H3	768P / 1080P / 2K / 4K (1080P·4K는 super-resolution 출력)	21:9, 16:9, 4:3, 1:1, 3:4, 9:16 (text-to-video)	4–15s	First+last (각 1장)	참조 이미지 ≤9 / 참조 영상 ≤3 / 참조 오디오 ≤3 (합산 ≤12)	Yes (네이티브 음성 생성)	네이티브 멀티모달. 첫/끝 프레임과 참조 영상·오디오는 혼용 불가 (§6.5 참조).
Kling	1.6 / 2.1 / 2.5 / 2.6 / 3.0 / 3.0-Omni / 3.0-turbo / O1	720P / 1080P (default 720P; 2.5/2.6 1080P)	16:9, 9:16, 1:1 (2.1, 2.5, 2.6 add 4:3, 3:4, 3:2, 2:3, 21:9)	5s, 10s (3.0 / 3.0-Omni: 3–15s; O1: 3–10s)	Supported (2.1 needs 1080P)	Up to 4 (1.6) / 7 subjects (O1, 3.0-Omni)	Yes (2.6 audio variant, 3.0, 3.0-Omni)	Flagship. Video input: MP4/MOV, 3–10s, 720–2160px, 24–60fps, ≤200MB.
GV (Google Veo)	3.1 / 3.1-fast	720P / 1080P (default 720P)	16:9, 9:16	4s, 8s, 12s	Supported (3.1)	Up to 3	Yes (3.1, needs `EnableAudio=true`)	Google Veo.
OS (OpenAI Sora)	2.0	720P (fixed)	Image-to-video matches image; text-to-video 16:9, 9:16	4s, 8s, 12s	Not supported	Up to 7 (no ref video) / 4 (with ref video)	No	OpenAI Sora. Higher resolution via super-resolution enhancement.
Vidu	q2 / q2-pro / q2-turbo / q3 / q3-pro / q3-turbo	540P / 720P / 1080P (default 720P)	Text-to-video AspectRatio: 16:9, 9:16, 3:4, 4:3, 1:1	1–10s (q3-pro/turbo 1–16s)	Supported (not q3)	Up to 4 images + 2 videos (q3: 5+2)	Yes (q3 family, needs `EnableAudio=true`)	off-peak mode halves price; `movement_amplitude`, realistic/anime style.
Hunyuan	1.5	480P / 720P / 1080P (default 720P)	16:9 only	—	Not supported	1–7 subjects (1–7 images)	No	—
Jimeng	3.0pro	1080P	16:9, 9:16, 3:4, 4:3, 1:1, 21:9	5s, 10s	First frame only	Not supported	No	—
SV	1.0-pro / 1.0-pro-fast / 1.5-pro / 1.0-lite-i2v	480P / 720P (1.5-pro 1080P 미지원)	16:9, 9:16	5s, 10s	1–2 (first/last frame)	Image / Video / Audio (소재 기반)	Yes (1.5-pro AudioGeneration)	인물 영상 특화. 인물 사진 기반 영상 제작 검열에 매우 민감 — §6.4 참조.
VS	2.0 / 2.0-fast / 2.0-mini	480P / 720P / 1080P / 2K / 4K (default 720P)	21:9, 16:9, 4:3, 1:1, 3:4, 9:16	4–15s (default 5s)	Image / Video / Audio reference	다중 참조 입력	Yes (AudioGeneration)	고품질 영상 생성 — §6.4 참조.
VS	2.5	480P / 720P / 2K / 4K (default 720P; 2K·4K super-resolution)	21:9, 16:9, 4:3, 1:1, 3:4, 9:16	4–30s	Text / First frame / First+last frame	이미지·영상·오디오 다중 참조 (최대 50: 이미지 30 + 영상 10 + 오디오 10)	Yes (오디오)	고품질 영상, 최대 30초, 2K·4K 초해상도 직출 — §6.4 참조.
Mingmou	1.0	—	—	—	Not supported	—	No	—
PixVerse	v5.6 / v6 / c1	540P / 720P / 1080P / 2K / 4K (default 720P)	16:9, 4:3, 1:1, 3:4, 9:16, 2:3, 3:2, 21:9 (text-to-video only)	5s / 8s / 10s (v5.6; 10s not on 1080P) / 1–15s (v6, c1)	Supported	1–2 (first/last) / 7 (v5.6 ref) / 3 (c1 ref)	Yes (v6, c1)	See §6.3 PixVerse guide.
Kling	3.0-turbo	720P / 1080P / 2K / 4K	16:9, 9:16, 1:1 (text-to-video only)	3–15s	—	Single image (image-to-video); subject reference supported	—	Text / Image / subject-reference generation.
Vidu	q3-drama	1080P / 2K / 4K (2K & 4K via super-resolution)	9:16, 16:9	8–12s	—	1–14 reference images; subject reference supported	—	Drama-oriented reference generation.
Vidu	q3-ad	720P / 1080P / 2K / 4K (2K & 4K via super-resolution)	1:1, 9:16, 16:9, 3:4, 4:3	3–16s	—	1–7 reference images; reference generation only (FileInfos/SubjectInfos required)	—	Ad-oriented reference generation.
H2	1.1	720P / 1080P / 2K / 4K	16:9 (default), 9:16, 1:1, 4:3, 3:4, 4:5, 5:4, 9:21, 21:9	3–15s (default 5s)	First frame only (image-to-video)	1–9 (reference generation)	—	Text / Image / reference generation.

1.4 Architecture

Architecture Diagram

2. Quickstart

텍스트 프롬프트 한 줄로 첫 영상 Task를 생성하는 최단 경로입니다. 아래 3 step을 따라 TaskId를 받고, 결과 조회 API로 결과 영상 URL을 회수합니다.

2.1 Step 1 — Endpoint & 인증 헤더

Tencent Cloud Common API Endpoint와 SecretId/SecretKey 기반 TC3-HMAC-SHA256 서명을 사용합니다. 서명 생성 흐름과 raw signed POST 코드는 §4.7 Python raw signed POST 예제를 참고하십시오.

항목	값
Endpoint	`https://vod.intl.tencentcloudapi.com`
X-TC-Action	`CreateAigcVideoTask`
X-TC-Version	`2018-07-17`
X-TC-Region	`ap-seoul`
Authorization	`TC3-HMAC-SHA256 Credential=$YOUR_SECRET_ID/...`

2.2 Step 2 — 요청 보내기

아래 cURL 1개를 그대로 실행하면 Kling 3.0-Omni 엔진에 prompt-only 요청이 전송되어 TaskId가 반환됩니다. $YOUR_SECRET_ID, $YOUR_SECRET_KEY, $SUBAPP_ID는 본인 값으로 치환합니다. 전체 인증 헤더(Authorization) 생성은 §4.7 Python raw signed POST 예제를 그대로 사용할 수 있습니다.

Bash Quickstart cURL

curl -X POST https://vod.intl.tencentcloudapi.com \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-TC-Action: CreateAigcVideoTask" \
  -H "X-TC-Version: 2018-07-17" \
  -H "X-TC-Region: ap-seoul" \
  -H "Authorization: TC3-HMAC-SHA256 Credential=$YOUR_SECRET_ID/..." \
  -d '{
    "SubAppId": $SUBAPP_ID,
    "ModelName": "Kling",
    "ModelVersion": "3.0-Omni",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "OutputConfig": {
      "Duration": 5,
      "Resolution": "720P"
    }
  }'

200 응답으로 Response.TaskId가 돌아오면 정상입니다. Body 파라미터 의미는 §3. Request 작성, 엔진별 차이는 §5. 엔진별 호출 예시 참조.

2.3 Step 3 — TaskId로 결과 조회

DescribeAigcVideoTask를 동일한 인증 헤더로 호출하여 결과 상태와 영상 URL을 회수합니다. 상세 파라미터는 MPS Integration §5. DescribeAigcVideoTask 참조.

3. Request 작성

3.1 Input Parameters

Parameter		Type	Description
SubAppId	required	Integer	Application 식별자
ModelName	required	String	영상 생성 엔진 이름
ModelVersion	required	String	엔진 버전
Prompt	conditional	String	텍스트 기반 생성 프롬프트
NegativePrompt	optional	String	원하지 않는 요소 지정
FileInfos.N	optional	Array	참조 이미지/비디오 파일 정보
LastFrameUrl	optional	String	끝 프레임 URL (지원 모델: GV, Kling, Vidu)
LastFrameFileId	optional	String	끝 프레임 FileId
SubjectInfos.N	optional	Array	고정 주체(Subject) 정보 — 캐릭터/오브젝트/음성 ID
EnhancePrompt	optional	String	`Enabled` / `Disabled`
OutputConfig	optional	Object	StorageMode, Duration, Resolution, AspectRatio, AudioGeneration 등 — 상세는 §3.2 참조
InputRegion	optional	String	입력 파일 URL의 리전
SceneType	optional	String	모델별 Scene 타입
Seed	optional	Integer	결과 재현용 seed
SessionId	optional	String	3일간 중복 요청 방지용 ID
SessionContext	optional	String	콜백 시 함께 전달되는 context 값
ExtInfo	optional	String	모델별 확장 파라미터 전달용 JSON 문자열. 1차 키 `AdditionalParameters` 안에 동작제어·대사동기화·스마트 분할·음색 등 모델 고유 옵션을 넣는다 — 상세는 §3.4

3.2 OutputConfig 필드

Field	Type	Description
StorageMode	String	`Temporary` / `Permanent`
Duration	Integer	생성 영상 길이 (모델별 상이)
Resolution	String	`720P`, `1080P`, `2K`, `4K`
AspectRatio	String	`16:9`, `9:16`, `1:1`, `4:3`, `3:4`
AudioGeneration	String	지원 모델에서 오디오 생성 `Enabled`/`Disabled`
EnhanceSwitch	String	Super Resolution 활성화 (`Enabled`/`Disabled`)
OffPeak	String	오프피크(off-peak) 모드. `Enabled` 시 비혼잡 시간대에 처리해 비용을 절감 — 대신 완료까지 더 오래 걸릴 수 있음
FrameInterpolate	String	Vidu 스마트 프레임 보간. `Enabled`/`Disabled`. 중간 프레임을 보간해 더 부드러운 영상
LogoAdd	String	워터마크 로고 삽입 여부. 현재 Vidu만 지원 (`Enabled`/`Disabled`)
InputComplianceCheck	String	입력 콘텐츠 검수 (`Enabled`/`Disabled`)
OutputComplianceCheck	String	출력 콘텐츠 검수 (`Enabled`/`Disabled`)
OutputFormat	String	출력 파일 형식

3.3 FileInfos.N 필드 & 사용 패턴

FileInfos.N은 입력 이미지/비디오 배열입니다. 각 원소는 아래 필드로 입력 소스와 그 역할(첫 프레임·참조·편집 대상 등)을 지정합니다.

Field	Type	Description
Type	String	`File`(점박 미디어 FileId) / `Url`(접근 가능한 URL)
Category	String	`Image` / `Video`
FileId	String	`Type=File`일 때 유효
Url	String	`Type=Url`일 때 유효
Usage	String	입력 역할 구분 — `FirstFrame`(첫 프레임) / `Reference`(참조 프레임). 다중 참조 시 모든 원소가 Usage를 가져야 함
ReferenceType	String	참조 타입 (GV·Kling·PixVerse 적용). GV: `asset`(소재)/`style`(스타일); Kling+Video: `feature`(특징 참조)/`base`(편집 대상)
ObjectId	String	Vidu 주체 Id 또는 참조 모드 제어. 이미지 1장 + `ObjectId` 비어있음 → 첫 프레임 모드; 비어있지 않음 → 참조 모드. prompt에서 `@ObjectId`로 호출
VoiceId	String	Vidu-q2 음색 Id. 모든 이미지가 주체 Id를 가질 때 주체별 음색 지정 가능
KeepOriginalSound	String	`Category=Video`일 때 원본 음성 유지 여부 — `Enabled`/`Disabled`

사용 패턴

패턴	필드	Description
First frame	`Usage = FirstFrame`	첫 프레임 이미지 기준 영상 생성. 출력 종횡비는 입력 이미지 비율을 따름
Reference	`Usage = Reference`	스타일/캐릭터/오브젝트 참조용
First+Last frame	`Usage = FirstFrame` + `LastFrameUrl/FileId`	시작/끝 구도 지정. Kling 2.1 첫·끝 프레임은 `1080P` 필수
Subject reference	`SubjectInfos.N`	고정 주체(Subject) — 캐릭터/오브젝트/음성 ID (권장)
Object reference	`ObjectId` 지정	구방식 참조 — 한 장 이미지에 ObjectId를 비우면 첫 프레임, 채우면 참조

3.4 ExtInfo / AdditionalParameters (모델 확장)

동작 제어·대사 동기화·스마트 분할·음색 지정처럼 표준 파라미터로 표현할 수 없는 모델 고유 기능은 ExtInfo로 전달합니다. 대부분 SceneType으로 기능을 켜고, 세부 옵션을 AdditionalParameters에 담습니다.

⚠

2중 JSON 인코딩 구조

ExtInfo = {"AdditionalParameters": "<json-string>"} 이며, 그 값이 다시 모델 파라미터 JSON을 문자열로 인코딩한 것입니다. 즉 모델 파라미터를 두 번 JSON 문자열화해야 합니다. prompt 안에서는 <<<element_1>>> 형태로 주체(subject)/element를 참조합니다.

영상 생성 기능별 AdditionalParameters

기능 / SceneType	파라미터	설명
동작 제어 `SceneType=motion_control` (Kling 2.6 / 3.0)	`keep_original_sound` `character_orientation`	`keep_original_sound`: `yes`/`no` — 참조 영상 원음 유지 여부. `character_orientation`: `image`(이미지 인물 방향, 참조 영상 ≤10초) / `video`(영상 인물 방향, ≤30초)
대사 동기화 / 디지털 휴먼 `SceneType=avatar_i2v` (Kling)	`sound_file` 또는 `audio_id`	음성을 입에 맞춰 합성. `sound_file`: 오디오 URL/Base64(.mp3/.wav/.m4a/.aac, ≤5MB, 2~300초). `audio_id`·`sound_file` 둘 중 정확히 하나만 지정
대사 동기화 (간편) `SceneType=lip_sync` (Kling)	`sound_file` 또는 `audio_id`	`avatar_i2v`와 동일하게 입력 음성에 입모양을 맞추는 립싱크 전용 씬. 인물 영상/이미지에 음성을 합성
스마트 분할(분경) (Kling 3.0 계열)	`multi_shot` `shot_type` `multi_prompt`	`multi_shot=true`로 다중 컷 생성. `shot_type=customize` 시 `multi_prompt` 배열에 컷별 `index`/`prompt`/`duration` 지정. 미지정 시 모델이 프롬프트를 자동 분할
음색 지정 (Kling 2.6/3.0/3.0-omni)	`voice_list`	`[{"voice_id": ...}]` 형태. prompt에서 `<<<voice_1>>>`로 호출. Kling 2.6은 1080P에서만 음색 ID 지원
주체(subject) 참조 (구 방식) (Kling)	`element_list`	`[{"element_id": ...}]`. prompt에서 `<<<element_1>>>`로 참조. 신규는 `SubjectInfos.N` 권장 (→ §7.3)
다중 요소 편집 `SceneType=multi_elements` (Kling)	`session_id` `edit_mode`	영상 내 특정 요소(피사체)를 선택해 삭제/편집하는 씬. 먼저 §7.8의 선택 API로 `session_id`를 만든 뒤, `edit_mode`(예: `addition`)와 함께 전달합니다. Prompt에서 편집 대상은 `<<<video_1>>>`로 참조합니다
특효 템플릿 `SceneType=template_effect` (Vidu)	`template`	장면 템플릿 이름(예: `morphlab`=폭발). 템플릿별 입력 요구가 다름 — Vidu 템플릿 센터 참조
고정 주체 참조 `SceneType=subject_reference` (Vidu)	`SubjectInfos.N`	여러 컷에 걸쳐 동일 인물/오브젝트를 일관되게 등장시키는 고정 주체 참조 씬
효과음 생성 (텍스트/영상) `SceneType=sfx` (Kling)	`bgm_prompt` `asmr_mode`	음효 프롬프트는 `Prompt`에, 배경음악 프롬프트는 `bgm_prompt`에. `asmr_mode=true` 시 디테일 음효 강화. 입력 영상은 `VideoInfos`로
음악 생성 `SceneType=music` (MiniMaxMusic)	`lyrics`	가사를 직접 지정. `OutputConfig.OutputAudioFormat`으로 출력 포맷(`mp3` 등) 지정
시드 고정 (지원 모델)	`Seed`	난수 시드 지정 시 동일 입력에 대해 결과 재현 가능. 미지정 시 매번 랜덤

대표 예시

"SceneType": "motion_control",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"keep_original_sound\\\":\\\"no\\\",\\\"character_orientation\\\":\\\"video\\\"}\"}"

"SceneType": "avatar_i2v",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"sound_file\\\":\\\"https://.../v.mp3\\\"}\"}"

# AdditionalParameters 내부
{
  "multi_shot": true,
  "shot_type": "customize",
  "multi_prompt": [
    {"index":1, "prompt":"...", "duration":2},
    {"index":2, "prompt":"...", "duration":3}
  ]
}

"Prompt": "...<<<voice_1>>>...",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"voice_list\\\":[{\\\"voice_id\\\":869...391}]}\"}"

"SceneType": "template_effect",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"template\\\":\\\"morphlab\\\"}\"}"

"SceneType": "sfx",
"AdditionalParameters": "{\"bgm_prompt\":\"치유계 피아노...\",\"asmr_mode\":true}"

4. Output & 결과 조회

CreateAigcVideoTask는 비동기 API입니다. 호출 즉시 TaskId만 반환하고, 실제 영상은 백그라운드에서 생성됩니다. 영상 생성은 이미지보다 오래 걸리므로(모델·길이에 따라 수십 초~수 분) TaskId로 DescribeTaskDetail을 폴링하여 완료 여부와 결과 URL을 회수합니다.

4.1 CreateAigcVideoTask 응답

Parameter	Type	Description
TaskId	String	결과 조회용 Task ID. 이후 `DescribeTaskDetail`에 그대로 전달합니다.
RequestId	String	요청 추적용 ID. 문제 발생 시 기술지원 문의에 사용합니다.

⚠

세션 중복 제거(Dedup)

동일 SessionId로 보낸 요청은 3일간 중복 제거됩니다. 재시도 시 동일 결과를 받게 되므로, 새 영상을 원하면 SessionId를 변경하십시오.

4.2 작업 상태 (Lifecycle)

작업은 다음 상태를 순차적으로 거칩니다. FINISH 또는 FAIL이 종료 상태입니다. (영상 API는 처리 중 상태가 RUN입니다.)

WAIT → RUN → FINISH 또는 FAIL

상태	설명	권장 동작
WAIT	큐에서 대기 중	3~5초 간격으로 폴링 지속
RUN	영상 생성 처리 중	폴링 지속(영상은 시간이 더 걸림)
FINISH	완료 — 결과 URL 회수 가능	`Output`에서 영상 URL 추출
FAIL	실패	`Message` 확인 후 파라미터 수정·재시도

4.3 DescribeTaskDetail 폴링 예시

생성 요청과 동일한 인증 헤더로 DescribeTaskDetail을 호출합니다. Status가 FINISH가 될 때까지 3~5초 간격으로 반복하십시오.

요청 — DescribeTaskDetailRequest

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "DescribeTaskDetail",
  "region": "ap-seoul",
  "request": {
    "SubAppId": "150003****",
    "TaskId": "150003****-CreateAigcVideoTask-xxxxxxxx"
  }
}

응답 — FINISHResponse

{
  "Response": {
    "TaskType": "CreateAigcVideoTask",
    "Status": "FINISH",
    "CreateAigcVideoTask": {
      "Status": "FINISH",
      "ErrCode": 0,
      "Message": "",
      "Output": {
        "MediaInfoSet": [
          {
            "Url": "https://.../result.mp4",
            "Duration": 5,
            "Resolution": "720P"
          }
        ]
      }
    },
    "RequestId": "xxxxxxxx"
  }
}

임시 저장(StorageMode: Temporary) 결과 URL은 만료 시간이 짧습니다. 영구 보관이 필요하면 Permanent로 요청하거나 회수 즉시 자체 스토리지로 다운로드하십시오.

4.4 주요 에러 & 대처

에러 유형	원인	대처
모델 버전 미지원	지정한 `ModelVersion`이 존재하지 않음	지원 모델 목록(§6) 확인 후 올바른 버전 선택
해상도 미지원	해당 모델이 지원하지 않는 `Resolution`	모델 특성 표(§6)에서 지원 해상도 선택
종횡비 미지원	해당 모델이 지원하지 않는 `AspectRatio`	모델 특성 표(§6)에서 지원 종횡비 선택
첫·끝 프레임 제약	첫·끝 프레임 생성 조건 미충족	Kling 2.1 첫·끝 프레임은 `Resolution: 1080P` 필수
참고 이미지 개수 초과	`FileInfos` 개수가 모델 한도 초과	모델별 한도(Vidu q2 1~7 / GV 최대 3 등)로 제한
Prompt 누락	참고 이미지도 `Prompt`도 없음	`Prompt` 추가 또는 참고 이미지 제공

5. 엔진별 호출 예시

5.0 공통 호출 골격

모든 엔진은 동일한 endpoint / action / region / auth 위에서 ModelName + ModelVersion + Prompt + OutputConfig만 바뀝니다. 아래 골격을 기준으로 §5.1 표의 엔진별 차이만 끼워 넣으면 됩니다.

Common Request Skeleton

JSON

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "",
    "ModelVersion": "",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

Common Response

200

{
  "Response": {
    "TaskId": "150003****-AigcVideoTask-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXT",
    "RequestId": "XXXXXXXX-****-XXXXXXXXXXXX"
  }
}

5.1 엔진별 차이 매트릭스

#	ModelName	ModelVersion	OutputConfig 권장값	ComplianceCheck	특이사항 / 가이드
1	Kling	`3.0-Omni`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	필수 (Input/Output Enabled)	플래그십. §6.1 Kling 가이드
2	Kling	`O1`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	필수 (Input/Output Enabled)	경량 고속 모델. §6.1 Kling 가이드
3	Hailuo	`2.3`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	MiniMax Video.
4	Vidu	`q3`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	필수 (Input/Output Enabled)	§6.2 Vidu 가이드
5	GV	`3.1`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	Google Veo. 오디오 생성 지원.
6	OS	`2.0`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	OpenAI Sora.
7	PixVerse	`V6.0`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	§6.3 PixVerse 가이드
8	H2	`1.0` / `1.1`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	—
9	Jimeng	`3.0pro`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	—
10	VS	`2.0`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	고품질 영상. §6.4 SV & VS 가이드
11	SV	`1.0-pro`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	인물 영상 특화(소재 기반). §6.4 SV & VS 가이드
12	Mingmou	`1.0`	`Duration: 5` / `Resolution: "720P"` / `AspectRatio: "16:9"`	—	—

5.2 엔진별 전체 JSON

11개 엔진의 전체 Request Body를 한눈에 비교할 수 있도록 격자로 배치했습니다. 모든 엔진의 응답은 동일하게 { "Response": { "TaskId": "...", "RequestId": "..." } } 형태이며, 이후 DescribeTaskDetail로 결과를 조회합니다.

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Kling",
    "ModelVersion": "3.0-Omni",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled",
      "InputComplianceCheck": "Enabled",
      "OutputComplianceCheck": "Enabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Kling",
    "ModelVersion": "O1",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled",
      "InputComplianceCheck": "Enabled",
      "OutputComplianceCheck": "Enabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Hailuo",
    "ModelVersion": "2.3",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Vidu",
    "ModelVersion": "q3",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled",
      "InputComplianceCheck": "Enabled",
      "OutputComplianceCheck": "Enabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "GV",
    "ModelVersion": "3.1",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "OS",
    "ModelVersion": "2.0",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "PixVerse",
    "ModelVersion": "V6.0",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "H2",
    "ModelVersion": "1.0",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Jimeng",
    "ModelVersion": "3.0pro",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "VS",
    "ModelVersion": "2.0",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

{
  "endpoint": "vod.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "SubAppId": "150003****",
    "ModelName": "Mingmou",
    "ModelVersion": "1.0",
    "Prompt": "A capybara mascot moves gently in a short studio video",
    "NegativePrompt": "low quality, distorted, flicker, blurry",
    "EnhancePrompt": "Enabled",
    "OutputConfig": {
      "StorageMode": "Temporary",
      "Duration": 5,
      "Resolution": "720P",
      "AspectRatio": "16:9",
      "AudioGeneration": "Disabled"
    }
  }
}

6. 모델별 상세 가이드

6.1 Kling

Kling 모델 상세 가이드

Kling 모델 버전별 기능 매트릭스

모델 버전	지원 기능	핵심 특징	최대 참조 이미지	오디오 지원	영상 길이
3.0-Omni	Text/Image/Reference	전 기능 통합 · 최고 화질	8장	TTS/더빙/SFX	3~15초
3.0	Text/Image	기본 플래그십, 범용 최적	6장	지원	3~15초
3.0-motion-control	Text/Image/Reference	정밀 모션 컨트롤	6장	지원	최대 10초
O1	Text/Image/Reference	경량 고속 모델	4장	지원	3~10초
2.6	Text/Image	안정 버전 (레거시)	4장	지원	5/10초
2.5	Text/Image	구세대 모델	2장	미지원	5/10초

Kling 고급 기능

동작 제어 (Motion Control)

ModelVersion: 3.0-motion-control — 인물 자세, 동작 궤적을 제어할 수 있습니다.

FileInfos에 포즈 이미지(Category: "Pose")를 추가하여 동작 가이드를 지정합니다.

JSON Motion Control Request

{"SubAppId":1500044236,"ModelName":"Kling","ModelVersion":"3.0-motion-control","Prompt":"A dancer performing ballet moves gracefully","FileInfos":[{"Type":"Url","Category":"Image","Url":"https://example.com/first-frame.jpg","Usage":"FirstFrame"},{"Type":"Url","Category":"Video","Url":"https://example.com/pose-guide.mp4","Usage":"Reference"}],"OutputConfig":{"StorageMode":"Temporary","Duration":10,"Resolution":"1080P"}}

Lip Sync

SceneType: lip_sync — 영상 내 인물의 입 모양을 음성에 맞춰 동기화합니다.

Step 1: DescribeAigcFaceInfo로 영상 내 인물 얼굴 정보(FaceId, 구간) 조회

Step 2: 조회된 FaceId를 사용하여 CreateAigcVideoTask 호출

JSON Lip Sync Request

{"SubAppId":1500044236,"ModelName":"Kling","ModelVersion":"2.6","Prompt":"Lip Sync","SceneType":"lip_sync","ExtInfo":"{\"AdditionalParameters\":\"{\\\"session_id\\\":\\\"FACE_SESSION_ID\\\",\\\"face_id\\\":\\\"0\\\",\\\"voice_id\\\":\\\"YOUR_VOICE_ID\\\"}\"}"}

디지털 휴먼 (Digital Human)

사진 1장 + 음성(TTS 또는 음성 파일)으로 디지털 휴먼 비디오를 생성합니다.

JSON Digital Human Request

{"SubAppId":1500044236,"ModelName":"Kling","ModelVersion":"2.6","FileInfos":[{"Type":"Url","Category":"Image","Url":"https://example.com/portrait.jpg","Usage":"FirstFrame"},{"Type":"Url","Category":"Audio","Url":"https://example.com/speech.mp3","Usage":"Reference"}],"SceneType":"digital_human","OutputConfig":{"StorageMode":"Temporary","Resolution":"1080P"}}

Multi-shot (다중 숏)

Kling 3.0 시리즈는 Multi-shot (다중 숏)을 지원합니다. multi_shot: true 설정 시 다중 숏 모드 활성화.

• customize: multi_prompt로 각 숏의 시간+프롬프트 직접 지정
• intelligence: prompt 기반 자동 분할

JSON Multi-shot (Customize)

{"SubAppId":1500044236,"ModelName":"Kling","ModelVersion":"3.0-Omni","Prompt":"","OutputConfig":{"StorageMode":"Temporary","Duration":15,"Resolution":"1080P"},"ExtInfo":"{\"AdditionalParameters\":\"{\\\"multi_shot\\\": true, \\\"shot_type\\\": \\\"customize\\\", \\\"multi_prompt\\\": [{\\\"index\\\": 1, \\\"prompt\\\": \\\"A person sitting on a park bench\\\", \\\"duration\\\": \\\"5\\\"}, {\\\"index\\\": 2, \\\"prompt\\\": \\\"The person stands up and walks away\\\", \\\"duration\\\": \\\"5\\\"}, {\\\"index\\\": 3, \\\"prompt\\\": \\\"Wide shot of the empty park bench\\\", \\\"duration\\\": \\\"5\\\"}]}\"}"}

Outpainting (이미지 확장)

ModelVersion: scene — 이미지의 주변 영역을 확장합니다. 확장 후 전체 면적 ≤ 원본의 3배

JSON Outpainting Request

{"SubAppId":1500044236,"ModelName":"Kling","ModelVersion":"scene","FileInfos":[{"Type":"Url","Url":"https://example.com/input.jpg"}],"Prompt":"Extend the scene with a beautiful sunset sky","OutputConfig":{"StorageMode":"Temporary"},"ExtInfo":"{\"AdditionalParameters\":\"{\\\"up_expansion_ratio\\\": 0.5, \\\"down_expansion_ratio\\\": 0.2, \\\"left_expansion_ratio\\\": 0.3, \\\"right_expansion_ratio\\\": 0.3}\"}"}

커스텀 보이스 (Custom Voice)

Kling 2.6, 3.0, 3.0-Omni에서 사용자 정의 보이스를 지정하여 영상 내 음성을 합성할 수 있습니다. 사전 준비: CreateKlingCustomVoice API로 보이스 ID 생성 필요

JSON Voice ID Request

{"SubAppId":1500044236,"ModelName":"Kling","ModelVersion":"3.0-Omni","Prompt":"A narrator explaining the story","FileInfos":[{"Type":"Url","Category":"Image","Url":"https://example.com/scene.jpg","Usage":"FirstFrame"}],"OutputConfig":{"StorageMode":"Temporary","Duration":10,"Resolution":"1080P","AudioGeneration":"Enabled"},"ExtInfo":"{\"AdditionalParameters\":\"{\\\"voice_id\\\": \\\"YOUR_VOICE_ID\\\"}\"}"}

6.2 Vidu

Vidu 모델 상세 가이드

Vidu 시나리오별 사용법

커스텀 캐릭터 (Custom Subject)

동일 캐릭터/오브젝트를 여러 영상에서 재사용하려면 캐릭터를 먼저 등록합니다. Vidu는 사전 등록 없이 영상 호출 한 번에 캐릭터를 같이 넘기는 임시 모드도 지원합니다 — §7.5 Vidu 임시 캐릭터 참조.

사전 등록 흐름: CreateAigcAdvancedCustomElement 로 등록 → 약 30초 후 DescribeAigcAdvancedCustomElements 로 실제 Element Id 회수 → 이후 SubjectInfos.N.Id 로 참조. 자세한 워크플로는 §7.3 캐릭터 일관성 (Element) 참조.

Text-to-Video

JSON Vidu Text-to-Video

{"SubAppId":1500044236,"ModelName":"Vidu","ModelVersion":"q2","Prompt":"A golden retriever running on a beach at sunset","OutputConfig":{"StorageMode":"Temporary","Duration":4,"AspectRatio":"16:9"}}

이미지 → 영상 (Image-to-Video / 시작·끝 프레임)

첫 프레임: FileInfos[0].Usage = "FirstFrame". 끝 프레임 추가 시: LastFrameUrl 사용

JSON Vidu First+Last Frame

{"SubAppId":1500044236,"ModelName":"Vidu","ModelVersion":"q3-pro","Prompt":"Smooth transition from day to night","FileInfos":[{"Type":"Url","Category":"Image","Url":"https://example.com/day.jpg","Usage":"FirstFrame"}],"LastFrameUrl":"https://example.com/night.jpg","OutputConfig":{"StorageMode":"Temporary","Duration":4,"AspectRatio":"16:9"}}

참조 이미지 기반 영상 + q3-mix

다중 참조 이미지로 스타일/캐릭터를 참조하여 영상 생성. q3-mix는 더 세밀한 스타일 믹싱 지원.

JSON Vidu q3-mix Reference

{"SubAppId":1500044236,"ModelName":"Vidu","ModelVersion":"q3-mix","Prompt":"Character walks through a fantasy forest","FileInfos":[{"Type":"Url","Category":"Image","Url":"https://example.com/char.jpg","Usage":"Reference"},{"Type":"Url","Category":"Image","Url":"https://example.com/style.jpg","Usage":"Reference"}],"OutputConfig":{"StorageMode":"Temporary","Duration":4}}

6.3 PixVerse

PixVerse 모델 상세 가이드

PixVerse 시나리오별 사용법

PixVerse는 Text-to-Video, Image-to-Video, First+Last Frame, Reference, 비디오 편집을 지원합니다.

비디오 편집 (Video Edit)

기존 비디오를 입력으로 받아 스타일 변환, 효과 추가 등의 편집을 수행합니다. FileInfos에 Category: "Video"로 원본 비디오를 전달합니다.

JSON PixVerse Video Edit

{"SubAppId":1500044236,"ModelName":"PixVerse","ModelVersion":"V6.0","Prompt":"Transform to anime style","FileInfos":[{"Type":"Url","Category":"Video","Url":"https://example.com/input.mp4","Usage":"Reference"}],"OutputConfig":{"StorageMode":"Temporary"}}

6.4 SV & VS

SV & VS 모델 상세 가이드

SV와 VS는 서로 다른 모델입니다. API의 ModelName과 지원 버전이 다릅니다.

표시명	ModelName (API)	지원 버전	성격
VS	`VS`	`2.0` / `2.0-fast` / `2.0-mini` / `2.5`	고품질 영상 생성 (Text/Image-to-Video; 2.5는 First+Last Frame·멀티모달 참조·최대 30s)
SV	`Seedance`	`1.0-pro` / `1.0-pro-fast` / `1.5-pro` / `1.0-lite-i2v`	인물 영상 특화 — 소재(Material) 기반 생성

VS(ModelName: VS, 버전 2.0·2.5 계열)는 고품질 일반 영상 생성 엔진으로, 표준 Text/Image-to-Video 흐름을 따릅니다. 2.5부터는 첫/끝 프레임 기반 생성, 이미지·영상·오디오 다중 참조(최대 50: 이미지 30 + 영상 10 + 오디오 10), 최대 30초 생성을 지원하며 2K·4K는 초해상도 직출입니다.

⚠

SV는 인물 영상 검열에 매우 민감

SV는 자체적으로 인물 사진을 통한 영상 제작 검열에 매우 민감한 편입니다. 인물이 포함된 소재를 다룰 때는 아래 소재 등록 흐름과 인물검증 요건을 반드시 따라야 하며, 검열에 의해 생성이 거부될 수 있습니다.

VS 특수 파라미터

표준 파라미터(SubAppId·Prompt·OutputConfig.Resolution/Duration/AspectRatio)는 다른 모델과 동일합니다. 아래는 VS에서 특별히 의미를 갖는 필드입니다.

Parameter		Type	Description
ModelName	required	String	고정값 `VS`
ModelVersion	required	String	`2.0` / `2.0-fast` / `2.0-mini` / `2.5`
FileInfos[].Category	optional	String	참조 입력 유형 — `Image` / `Video` / `Audio`. 이미지뿐 아니라 영상·오디오도 참조 입력으로 받아 다이내믹한 생성이 가능합니다.
OutputConfig.AudioGeneration	optional	String	음향·화면 동시 출력(음악 동기). `Enabled` / `Disabled`
OutputConfig.Seed	optional	Integer	난수 시드. 같은 시드+입력으로 재현 가능
ExtInfo	optional	String	2중 JSON 인코딩. `AdditionalParameters.bitrate_mode`=`high` 로 고비트레이트 출력 가능

JSON 고비트레이트 ExtInfo

"ExtInfo": "{\"AdditionalParameters\":\"{\\\"bitrate_mode\\\":\\\"high\\\"}\"}"

소재(Material) 기반 생성 & 인물 영상 우회 가이드

SV는 자체적으로 인물 사진을 통한 영상 제작 검열에 매우 민감한 편입니다. 인물이 포함된 영상을 생성할 때는 소재 등록 → asset:// 참조 흐름을 거쳐야 하며, 실제 인물 여부에 따라 인물검증(Liveness) 요건이 갈립니다.

⚠

루트 선택 기준

실제 인물(Real Person) 영상은 인물검증이 필요한 정상 루트를, 가상 인물·일러스트·AI 생성 인물은 인물검증 없이 비실제 인물 루트로 바로 소재 등록할 수 있습니다. 유명인물은 초상권·저작권 민감 이슈이므로 별도 판단이 필요합니다.

루트	인물검증	IsRealPerson	GroupId	비고
실제 인물	필수 (CreateAigcLivenessValidate)	`"True"`	인물검증 결과로 획득한 GroupId	얼굴 인증을 통과한 그룹에만 소재 등록
가상/비실제 인물	생략	`"False"`	임의 지정 가능	인물검증 없이 소재 등록 → `asset://` 참조

소재 & 인물검증 API 규격

아래 API는 모두 Tencent Cloud API 엔드포인트(vod.tencentcloudapi.com)로 POST 호출하며, TC3-HMAC-SHA256 서명과 X-TC-Action 헤더로 액션을 지정합니다. 서명 흐름은 §4.7 Python raw signed POST 예제와 동일합니다. 모든 스펙은 해외(ap-guangzhou) 계정 기준 실호출로 검증했습니다.

① CreateAigcLivenessValidate — 인물검증 세션 생성

POSTvod.tencentcloudapi.com · Action=CreateAigcLivenessValidate

실제 인물 소재를 등록하기 전, 얼굴 인증(Liveness) 세션을 시작합니다. 응답으로 받은 LivenessToken과 H5Link로 사용자가 H5 페이지에서 인증을 진행합니다.

Parameter		Type	Description
SubAppId	required	Integer	VOD 서브 앱 ID
CallbackUrl	optional	String	인증 완료 후 콜백을 받을 URL

JSON Request Body

{
  "SubAppId": 1500000000,
  "CallbackUrl": "https://example.com/liveness-callback"
}

JSON Response Example

200

{
  "Response": {
    "LivenessToken": "liveness-xxxxxxxxxxxxxxxx",
    "H5Link": "https://vod-liveness.example.com/verify?token=liveness-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

ⓘ

인물검증 서비스가 활성화되지 않은 계정에서는 FailedOperation — Create liveness session failed가 반환됩니다. 사용 전 콘솔에서 인물검증(Visual Validate) 기능 활성화가 필요합니다.

② DescribeAigcLivenessValidateResult — 인물검증 결과 조회

POSTvod.tencentcloudapi.com · Action=DescribeAigcLivenessValidateResult

①에서 받은 LivenessToken으로 인증 결과를 조회합니다. 통과 시 실제 인물 소재를 등록할 수 있는 GroupId를 획득합니다.

Parameter		Type	Description
SubAppId	optional	Integer	VOD 서브 앱 ID
LivenessToken	required	String	①의 응답으로 받은 세션 토큰

JSON Request Body

{
  "SubAppId": 1500000000,
  "LivenessToken": "liveness-xxxxxxxxxxxxxxxx"
}

JSON Response Example

200

{
  "Response": {
    "GroupId": "group-xxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

이 GroupId를 ③ CreateAigcMaterial에 그대로 전달하면 얼굴 인증을 통과한 그룹에만 실제 인물 소재가 등록됩니다.

③ CreateAigcMaterial — 소재 등록 (비동기)

POSTvod.tencentcloudapi.com · Action=CreateAigcMaterial

인물 이미지·영상·오디오를 소재로 등록합니다. 비동기 작업으로, 응답의 TaskId를 DescribeTaskDetail로 조회해 완료 시 AssetId를 얻습니다. 이후 영상 생성에서 asset://asset-{AssetId} 형태로 참조합니다.

Parameter		Type	Description
SubAppId	required	Integer	VOD 서브 앱 ID
AssetName	required	String	소재 이름
AssetType	required	String	`Image` / `Video` / `Audio`
FileInfo	required	Object	소재 원본. `{ "Type": "Url", "Url": "..." }` 또는 `{ "Type": "FileId", "FileId": "..." }`
GroupId	required	String	실제 인물은 ②에서 받은 값, 비실제 인물은 임의 그룹 ID
IsRealPerson	optional	String	`"True"`(실제 인물, 인물검증 통과 그룹) / `"False"`(가상·비실제 인물)

JSON Request Body

{
  "SubAppId": 1500000000,
  "AssetName": "model-A",
  "AssetType": "Image",
  "FileInfo": { "Type": "Url", "Url": "https://example.com/person.jpg" },
  "GroupId": "group-xxxxxxxxxxxx",
  "IsRealPerson": "True"
}

JSON Response Example

200

{
  "Response": {
    "TaskId": "1500000000-CreateAigcMaterial-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

완료 조회 — DescribeTaskDetail에 위 TaskId를 넣어 호출하면, TaskType=CreateAigcMaterial이고 CreateAigcMaterialTask.Output.AssetId에서 최종 소재 ID를 얻습니다(약 5초 내 FINISH).

JSON DescribeTaskDetail Response (발췌)

200

{
  "Response": {
    "TaskType": "CreateAigcMaterial",
    "Status": "FINISH",
    "CreateAigcMaterialTask": {
      "TaskId": "1500000000-CreateAigcMaterial-xxxxxxxxxxxxxxxx",
      "Status": "FINISH",
      "ErrCode": 0,
      "Progress": 100,
      "Input": {
        "FileInfo": { "Type": "Url", "Url": "https://example.com/person.jpg" },
        "AssetType": "Image",
        "GroupId": "group-xxxxxxxxxxxx",
        "AssetName": "model-A",
        "IsRealPerson": "True"
      },
      "Output": {
        "AssetId": "asset-20260708xxxxxx-xxxxx",
        "AssetUrl": "https://.../person.jpg?X-Tos-Signature=***",
        "GroupId": "group-xxxxxxxxxxxx"
      }
    },
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

④ CreateAigcVideoTask — 소재 참조 영상 생성

등록된 소재를 FileInfos[].Url에 asset://asset-{AssetId} 형태로 넣어 SV 엔진(ModelName Seedance)으로 영상을 생성합니다.

JSON Request Body (SV 1.0-pro)

{
  "SubAppId": 1500000000,
  "ModelName": "Seedance",
  "ModelVersion": "1.0-pro",
  "FileInfos": [
    { "Type": "Url", "Category": "Image", "Url": "asset://asset-20260708xxxxxx-xxxxx", "Usage": "Reference" }
  ],
  "Prompt": "인물이 천천히 걷는다",
  "OutputConfig": { "Resolution": "1080P", "Duration": 5, "AspectRatio": "16:9", "AudioGeneration": "Disabled" }
}

⑤ DescribeAigcMaterial — 소재 조회

POSTvod.tencentcloudapi.com · Action=DescribeAigcMaterial

등록된 소재의 상태와 접근 URL을 조회합니다. 조회 키는 AssetId이며, GroupId·AssetName으로는 조회할 수 없습니다.

Parameter		Type	Description
SubAppId	required	Integer	VOD 서브 앱 ID
AssetId	required	String	③에서 획득한 소재 ID

JSON Response Example

200

{
  "Response": {
    "AssetId": "asset-20260708xxxxxx-xxxxx",
    "AssetUrl": "https://.../person.jpg?X-Tos-Signature=***",
    "GroupId": "group-xxxxxxxxxxxx",
    "Status": "DONE",
    "Message": "",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

⑥ DeleteAigcMaterial — 소재 삭제

POSTvod.tencentcloudapi.com · Action=DeleteAigcMaterial

AssetId로 소재를 삭제합니다(AssetId 또는 GroupId 중 하나 필수). 삭제 후에도 DescribeAigcMaterial은 잔여 메타를 잠시 반환할 수 있습니다.

Parameter		Type	Description
SubAppId	required	Integer	VOD 서브 앱 ID
AssetId	required	String	삭제할 소재 ID (또는 `GroupId`)

JSON Response Example

200

{
  "Response": {
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

단편(Short drama) 등 얼굴 포함 여부를 판별하기 어려운 콘텐츠는, 모든 소재를 사전 등록 후 재사용하는 캐싱 전략이 권장됩니다 — 중복 생성 비용과 인물검증 반복을 줄일 수 있습니다.

6.5 Hailuo

Hailuo (MiniMax Video) 모델 상세 가이드

버전별 특성

버전	Duration	특징
02	6 / 8 / 10 / 12 / 15 / 20s	길이 선택 폭이 가장 넓은 구형 버전 (실측 20s 이상 가능)
2.3 / 2.3-fast	6s, 10s (default 6s)	일반 Text/Image-to-Video. 종횡비 지정·음성 생성 미지원
H3	4–15s	네이티브 멀티모달 버전 (2026-07 출시). 텍스트·이미지·영상·오디오 입력과 음성 동시 생성, 종횡비 지정 지원

H3는 02/2.3 계열과 동작 방식이 완전히 다릅니다. 02/2.3 계열 기준의 제약(종횡비 지정 불가, 음성 생성 불가, 6s/10s 고정)은 H3에 적용되지 않습니다.

H3 입력 모드 (i2va와 r2va 혼용 불가)

모드	입력	FileInfos Usage
t2va	텍스트만	— (FileInfos 없음)
i2va	첫 프레임 / 끝 프레임 이미지 (각 ≤1장)	`FirstFrame` / `LastFrame`
r2va	참조 이미지 ≤9, 참조 영상 ≤3, 참조 오디오 ≤3 (합산 ≤12)	`Reference`

⚠

i2va와 r2va는 함께 쓸 수 없습니다

첫/끝 프레임(FirstFrame/LastFrame)과 참조 영상·오디오(Reference)를 한 요청에 섞으면 오류가 납니다. 참조 오디오는 단독 입력이 불가하며 이미지나 영상과 함께 넣어야 합니다.

H3 입력 소스 규격

소스	형식	제한
이미지	JPG / JPEG / PNG / WEBP / HEIC / HEIF, 개당 ≤30MB	가로·세로 [256, 5760]px, 비율(w/h) [0.4, 2.5], 첫 프레임 ≤1 · 끝 프레임 ≤1 · 참조 ≤9
영상	MP4 / MOV (H.264·H.265 + AAC·MP3), 개당 ≤50MB	≤3개, 개당 2~15초·합산 ≤15초, 가로·세로 [256, 5760]px, 비율 [0.4, 2.5], 23.976~60fps
오디오	WAV / MP3, 개당 ≤15MB	≤3개, 개당 2~15초·합산 ≤15초, 이미지나 영상과 함께 입력 필수

H3 실측 출력

요청	실측 산출물	작업 시간
t2v · 1080P · 9:16 · 6s	1080×1890, 6.59s, H.264 24fps, AAC 44.1kHz 스테레오, ~6Mbps / 4.9MB	약 3분
t2v · 2K · 16:9 · 15s	2560×1440, 15.08s, H.264 24fps, AAC 32kHz 스테레오, ~5.1Mbps / 9.6MB	약 8분 20초

두 실측 모두 OutputConfig.AudioGeneration을 명시하지 않았는데 음성 트랙이 함께 생성됐습니다. H3는 음성 생성이 기본 동작입니다. 해상도는 768P / 1080P / 2K / 4K를 지원하며 1080P와 4K는 super-resolution으로 확장 출력됩니다.

H3 코드 예시

Text-to-Video (t2va)

실측에 사용한 요청 그대로입니다. Resolution · AspectRatio · Duration을 OutputConfig로 지정합니다.

JSON Hailuo H3 Text-to-Video

{
  "SubAppId": 1500044236,
  "ModelName": "Hailuo",
  "ModelVersion": "H3",
  "Prompt": "A cinematic shot of a hot air balloon drifting over Cappadocia at sunrise, soft golden light, camera slowly panning across the fairy chimneys",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Duration": 6,
    "Resolution": "1080P",
    "AspectRatio": "9:16"
  }
}

첫/끝 프레임 영상 (i2va)

FileInfos에 Usage: "FirstFrame" / "LastFrame"으로 각 1장씩 지정합니다.

JSON Hailuo H3 First+Last Frame

{
  "SubAppId": 1500044236,
  "ModelName": "Hailuo",
  "ModelVersion": "H3",
  "Prompt": "Camera slowly pushes in as the scene transitions from day to night",
  "FileInfos": [
    {"Type": "Url", "Category": "Image", "Url": "https://example.com/first.jpg", "Usage": "FirstFrame"},
    {"Type": "Url", "Category": "Image", "Url": "https://example.com/last.jpg", "Usage": "LastFrame"}
  ],
  "OutputConfig": {"StorageMode": "Temporary", "Duration": 8, "Resolution": "1080P"}
}

멀티모달 참조 영상 (r2va)

참조 영상·오디오는 Usage: "Reference"로 전달합니다. 참조 오디오는 반드시 이미지나 영상과 함께 넣습니다.

JSON Hailuo H3 Reference Video + Audio

{
  "SubAppId": 1500044236,
  "ModelName": "Hailuo",
  "ModelVersion": "H3",
  "Prompt": "Extend the camera movement style of the reference video, matching the rhythm of the reference audio",
  "FileInfos": [
    {"Type": "Url", "Category": "Video", "Url": "https://example.com/ref.mp4", "Usage": "Reference"},
    {"Type": "Url", "Category": "Audio", "Url": "https://example.com/ref.mp3", "Usage": "Reference"}
  ],
  "OutputConfig": {"StorageMode": "Temporary", "Duration": 10, "AspectRatio": "16:9"}
}

7. 시각 일관성 고급 기법

동일한 액션(CreateAigcVideoTask) 위에서 영상의 시각적 일관성을 끌어올리는 기법들입니다. 해외(ap-seoul) 계정 기준으로 게이트웨이가 받는 파라미터 키 이름과 응답 형태를 정리했습니다.

🧩

한눈에 보기

기법	한 줄 요약	핵심 키
첫/끝 프레임 보간	두 이미지를 시작·끝으로 잡고 사이를 채움	`FileInfos[Usage="FirstFrame"]` + `LastFrameUrl`
다중 참조 (Reference)	여러 이미지를 스타일/구도 참고로 사용	`FileInfos[Usage="Reference"]`
캐릭터 일관성 (Element)	사전 등록한 캐릭터를 모든 영상에 동일하게 등장	`SubjectInfos[].Id` + `<<<element_1>>>`
Vidu 임시 캐릭터	등록 없이 호출 한 번에 캐릭터 동시 전달	`SubjectInfos[Name+ImageUrls]` + `[@Name]`
멀티 컷 (분할 촬영)	한 영상 안에서 카메라 워크가 여러 번 전환	`ExtInfo` 안 `multi_shot` JSON

7.1 첫 프레임 + 끝 프레임 보간

장면 N의 마지막 프레임 = 장면 N+1의 첫 프레임으로 강제해 컷 전환을 매끄럽게 만듭니다. 시작 이미지는 FileInfos[Usage="FirstFrame"], 끝 이미지는 LastFrameUrl로 넘깁니다.

JSON First + Last Frame

JSON

{
  "SubAppId":     0,
  "ModelName":    "Kling",
  "ModelVersion": "2.1",
  "Prompt":       "smooth bridge between two scenes",
  "FileInfos": [
    { "Type": "Url", "Category": "Image", "Url": "https://example.com/start.png", "Usage": "FirstFrame" }
  ],
  "LastFrameUrl": "https://example.com/end.png",
  "OutputConfig": { "StorageMode": "Temporary", "Resolution": "1080P", "Duration": 5 }
}

제약	내용
Kling	`ModelVersion = 2.1` + `Resolution = 1080P` 조합에서 `LastFrameUrl` 작동
Vidu / GV	Vidu는 `q2-pro` / `q2-turbo`, GV는 별도 조건
이미지	5MB 이하, jpeg / jpg / png / webp

위 호출은 약 30초 내에 완료되며, 첫 프레임에서 끝 프레임으로 부드럽게 전환되는 5초 영상이 반환됩니다.

7.2 다중 참조 (Reference)

같은 인물·사물을 여러 각도에서 본 이미지를 같이 넣어 모델이 형태를 더 정확히 잡게 합니다. Usage = "Reference" 항목은 첫 프레임으로 고정되지 않고 단순 참고 입력으로만 쓰입니다.

JSON Multi-Reference

JSON

{
  "SubAppId":     0,
  "ModelName":    "Kling",
  "ModelVersion": "3.0-Omni",
  "Prompt":       "create a new scene combining the references",
  "FileInfos": [
    { "Type": "Url", "Category": "Image", "Url": "https://example.com/ref-a.png", "Usage": "Reference" },
    { "Type": "Url", "Category": "Image", "Url": "https://example.com/ref-b.png", "Usage": "Reference" }
  ],
  "EnhancePrompt": "Enabled",
  "OutputConfig": { "StorageMode": "Temporary", "Resolution": "1080P", "Duration": 5, "AspectRatio": "16:9", "AudioGeneration": "Enabled" }
}

다중 참조는 최대 7장까지 (참고 영상이 같이 들어가면 4장까지) 허용됩니다.
참조 이미지가 2장을 넘어가면 같은 호출에서 LastFrameUrl을 같이 쓸 수 없습니다.

7.3 캐릭터 일관성 (Element)

여러 컷에 같은 등장 인물·캐릭터를 등장시키려면 사전 등록 후 ID로 호출합니다. 등록 → 목록 조회로 ID 회수 → 영상 생성에 사용 → (필요 시) 삭제의 4단계 흐름입니다.

Step 1 — 등록 (`CreateAigcAdvancedCustomElement`)

JSON Register Element

JSON

{
  "SubAppId":           0,
  "ElementName":        "samurai-hero",
  "ElementDescription": "main character of cyberpunk short film",
  "ReferenceType":      "image_refer",
  "ElementImageList":   "{\"frontal_image\":\"https://example.com/face.png\",\"refer_images\":[{\"image_url\":\"https://example.com/a.png\"},{\"image_url\":\"https://example.com/b.png\"}]}",
  "DisableModeration":  "True"
}

필드	의미
ElementName	표시용 이름, 20자 이하
ElementDescription	설명, 100자 이하
ReferenceType	`image_refer` (이미지 기반) 또는 `video_refer` (영상 기반)
ElementImageList	JSON 문자열. 안에 `frontal_image`(정면 1장) + `refer_images`(다른 각도 1~3장). 객체 그대로 넘기면 거부됨
DisableModeration	해외 계정에서는 `"True"`로 보내야 해외용 라이브러리에 등록됨

⚠️

JSON 문자열 주의

ElementImageList와 TagList는 객체가 아니라 JSON 문자열입니다. 응답으로 받는 TaskId(형식 {accountId}-CreateAigcAdvancedCustomElement-...t)는 등록 작업을 가리키는 임시 ID이며, 실제 캐릭터 ID는 약 30초 뒤 등록 목록 조회로 받아야 합니다.

Step 2 — 등록된 캐릭터 조회 (`DescribeAigcAdvancedCustomElements`)

JSON List Elements — Response

200

{
  "Response": {
    "TotalCount": 3,
    "ElementSet": [
      { "Id": "313829804205144", "Name": "samurai-hero", "Description": "...", "VoiceId": "", "CreateTime": "2026-06-19T08:38:37Z" }
    ],
    "RequestId": "..."
  }
}

여기서 받은 Id가 영상 생성 호출에 들어갈 진짜 캐릭터 ID입니다 (요청 파라미터: SubAppId, Limit, Offset).

Step 3 — 캐릭터 사용 (`SubjectInfos`)

등록한 캐릭터를 영상에 등장시킵니다. 프롬프트 안에서는 <<<element_1>>>, <<<element_2>>> 같은 토큰으로 SubjectInfos 배열 순서대로 참조합니다.

JSON Use Element

JSON

{
  "SubAppId":     0,
  "ModelName":    "Kling",
  "ModelVersion": "3.0-Omni",
  "SubjectInfos": [
    { "Id": "313829804205144" },
    { "Id": "313829801220307" }
  ],
  "Prompt": "let <<<element_1>>> hold <<<element_2>>>'s hand on a beach at sunset",
  "OutputConfig": { "StorageMode": "Temporary", "Resolution": "1080P", "Duration": 5 }
}

필드	의미
SubjectInfos[].Id	등록된 캐릭터의 `Id`. Kling은 필수, Vidu는 선택
SubjectInfos[].Name	캐릭터 이름. Vidu는 필수(프롬프트 안 `[@name]`으로 참조), Kling은 선택

Step 4 — 캐릭터 삭제 (`DeleteAigcAdvancedCustomElement`)

JSON Delete Element

JSON

{ "SubAppId": 0, "ElementId": "313829804205144" }

해외 라이브러리의 일부 캐릭터는 FailedOperation으로 거부될 수 있습니다. 정책상 의도된 동작이며, 보통은 그대로 두면 됩니다.

7.4 Vidu 임시 캐릭터

Vidu는 사전 등록 없이 영상 호출 한 번에 캐릭터를 같이 넘기는 임시 모드를 지원합니다. 프롬프트 안에서는 [@Name] 형태로 참조합니다.

JSON Vidu Temporary Subject

JSON

{
  "SubAppId":     0,
  "ModelName":    "Vidu",
  "ModelVersion": "q2-pro",
  "SubjectInfos": [
    {
      "Name": "Princess",
      "ImageUrls": [ "https://example.com/princess-1.png", "https://example.com/princess-2.png" ]
    }
  ],
  "Prompt": "[@Princess] sits on a throne and smiles",
  "OutputConfig": { "StorageMode": "Temporary", "Resolution": "1080P", "Duration": 4 }
}

필드	의미
SubjectInfos[].Name	임시 캐릭터 호칭. 프롬프트 안 `[@Name]`으로 참조
SubjectInfos[].ImageUrls	최대 3장 (해상도 128x128 이상, 비율 1:4 이내)
SubjectInfos[].VideoUrls	최대 1개 5초 영상 (`q2-pro` 모델만)
SubjectInfos[].VoiceId	음색 ID (선택)

7.5 멀티 컷 (한 영상 안에 여러 컷)

Kling 3.0 계열은 한 호출 안에서 카메라 앵글이 여러 번 바뀌는 영상을 만들 수 있습니다. 키 자체는 ExtInfo 하나지만, ExtInfo가 JSON 문자열이고 그 안의 AdditionalParameters도 또 한 번 JSON 문자열입니다 — 즉 두 번 직렬화합니다.

Python ExtInfo 구성

import json

inner = {
    "multi_shot":  True,
    "shot_type":   "customize",   # 또는 "intelligence"
    "multi_prompt": [
        { "index": 1, "prompt": "wide shot, robot enters alley", "duration": 2 },
        { "index": 2, "prompt": "close-up, robot eyes glow",     "duration": 3 }
    ]
}
ext_info = json.dumps({
    "AdditionalParameters": json.dumps(inner, ensure_ascii=False)
}, ensure_ascii=False)

필드	값	의미
multi_shot	`true`	멀티 컷 켜기
shot_type	`customize`	사용자가 컷별 프롬프트를 직접 지정
shot_type	`intelligence`	모델이 알아서 컷 분할 (이때 `multi_prompt` 무시, 외부 `Prompt`만 사용)
multi_prompt[].index	1부터	컷 순서
multi_prompt[].prompt	문자열	컷별 프롬프트 (최대 512자)
multi_prompt[].duration	정수 ≥ 1	컷별 길이. 모든 duration 합 = 외부 `OutputConfig.Duration`

컷은 최소 1개, 최대 6개.
모든 컷의 duration 합이 외부 OutputConfig.Duration과 같아야 합니다.

7.6 Python 호출 템플릿 (call_json)

공식 SDK의 typed 모델(models.CreateAigcVideoTaskRequest)은 SubjectInfos, LastFrameUrl, ExtInfo 같은 신규 필드를 아직 클래스 어트리뷰트로 노출하지 않는 경우가 있습니다. 가장 안전한 방법은 CommonClient.call_json(action, payload_dict)로 액션을 직접 호출하는 것입니다.

Python 등록 → ID 회수 → 영상 생성 → 폴링

import os, json, time
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.common.common_client import CommonClient

cred = credential.Credential(
    os.environ["TENCENTCLOUD_SECRET_ID"],
    os.environ["TENCENTCLOUD_SECRET_KEY"],
)
hp = HttpProfile(); hp.endpoint = "vod.intl.tencentcloudapi.com"
cp = ClientProfile(); cp.httpProfile = hp
client = CommonClient("vod", "2018-07-17", cred, "ap-seoul", profile=cp)

# 1) 캐릭터 등록
elem_image_list = json.dumps({
    "frontal_image": "https://example.com/face.png",
    "refer_images": [
        {"image_url": "https://example.com/a.png"},
        {"image_url": "https://example.com/b.png"},
    ],
}, ensure_ascii=False)

resp = client.call_json("CreateAigcAdvancedCustomElement", {
    "SubAppId":           0,
    "ElementName":        "samurai-hero",
    "ElementDescription": "main character",
    "ReferenceType":      "image_refer",
    "ElementImageList":   elem_image_list,
    "DisableModeration":  "True",
})
register_task_id = resp["Response"]["TaskId"]

# 2) 약 30초 후 등록 목록 조회로 진짜 ID 회수
time.sleep(30)
list_resp = client.call_json("DescribeAigcAdvancedCustomElements", {"SubAppId": 0, "Limit": 50})
elem_id = next(
    e["Id"] for e in list_resp["Response"]["ElementSet"]
    if e["Name"] == "samurai-hero"
)

# 3) 캐릭터를 사용해 영상 생성
resp = client.call_json("CreateAigcVideoTask", {
    "SubAppId":     0,
    "ModelName":    "Kling",
    "ModelVersion": "3.0-Omni",
    "SubjectInfos": [{"Id": elem_id}],
    "Prompt":       "<<<element_1>>> walks through a misty bamboo forest at dawn",
    "OutputConfig": {"StorageMode": "Temporary", "Resolution": "1080P", "Duration": 5, "AspectRatio": "16:9"},
})
video_task_id = resp["Response"]["TaskId"]

# 4) 폴링 (DescribeTaskDetail → Response.AigcVideoTask)
while True:
    detail = client.call_json("DescribeTaskDetail", {"SubAppId": 0, "TaskId": video_task_id})
    avt = detail["Response"]["AigcVideoTask"]
    status = avt["Status"]                      # PROCESSING / FINISH / FAIL
    if status == "FINISH":
        print("done:", avt["Output"]["FileInfoSet"][0]["FileUrl"]); break
    if status == "FAIL":
        print("failed:", avt.get("Message")); break
    time.sleep(6)

📡

폴링 흐름

CreateAigcVideoTask 응답의 TaskId를 DescribeTaskDetail로 폴링합니다. 결과는 Response.AigcVideoTask 안에 잡히며 Status는 PROCESSING / FINISH / FAIL 셋 중 하나입니다. 완료 시 결과 URL은 Output.FileInfoSet[0].FileUrl에 있습니다. 폴링 간격은 6초가 적당하고, 5~10분 이상 걸리면 사실상 실패로 봐도 됩니다.

7.7 운영 메모 & 자주 보는 오류

항목	내용
결과 URL 보존	`Temporary`는 짧으면 24시간 안에 만료. 보존하려면 `StorageMode: "Permanent"`로 보내거나, 결과 mp4를 받아 별도 COS로 재업로드
SDK 호환	신규 필드는 typed 모델에 미노출일 수 있음 → `CommonClient.call_json`으로 우회가 가장 안전
검수 (Compliance)	해외 계정 / ap-seoul에서는 일부 `InputComplianceCheck` / `OutputComplianceCheck` 옵션이 거부됨. 게이트웨이 기본값에 맡기고 필요 시 자체 모더레이션 도입 권장

오류 코드	보통의 원인
UnknownParameter	키 이름이 잘못됨. 특히 단수/복수 — `SubjectInfos`가 맞고 `SubjectInfo`/`Subjects`는 거부됨
MissingParameter: ModelName	필수 키 누락
InvalidParameterValue.ModelVersionNotSupport	모델 + 버전 조합이 미지원
InvalidParameterValue.SubAppId	SubAppId가 잘못됨 (해외 계정은 보통 0 또는 본인 application id)
FailedOperation	액션 자체는 통했지만 내부 처리 실패 (가짜 이미지 / 정책 위반 / 학습 실패 등)

✅

고급 기법 요약

텍스트→비디오(Kling 3.0-Omni) · 첫 프레임→비디오(약 60초) · 첫/끝 프레임 보간(Kling 2.1, 약 30초) · 다중 참조 · 캐릭터 등록(ElementImageList JSON 문자열, 약 30초 후 ID 발급) · 캐릭터 사용(SubjectInfos) · 멀티 컷(ExtInfo 내 multi_shot)을 지원합니다. 파라미터 키는 복수형 SubjectInfos가 정확하며, 단수 SubjectInfo는 UnknownParameter로 거부됩니다.

7.8 다중 요소 편집 (multi_elements)

영상 속 특정 요소(피사체)를 선택해 삭제하거나 재생성하는 Kling 다중 요소 편집 기능입니다. 선택 영역을 만드는 두 개의 세션 API로 SessionId를 준비한 뒤, CreateAigcVideoTask에 SceneType=multi_elements로 최종 생성 작업을 제출하는 3단계 흐름입니다.

Flow 3-Step
InitializeAigcMultiElementsSelection   # 영상 업로드/해석 → SessionId 획득
        │
        ▼
EditAigcMultiElementsSelection         # 선택 영역 편집 (add / delete / clear / preview) — 반복
        │
        ▼
CreateAigcVideoTask (SceneType=multi_elements)   # 최종 영상 생성

ℹ

입력 영상 제약

입력 영상은 길이 10초 이하, 가로·세로 각 720px 이상이어야 합니다. SessionId는 발급 후 24시간 유효합니다.

① InitializeAigcMultiElementsSelection — 선택 세션 초기화

편집할 영상을 업로드·해석하고 SessionId를 발급합니다.

Parameter		Type	Description
SubAppId	required	uint64	점광 애플리케이션 ID
FileInfo	optional	Object	영상 소스
FileInfo.Type	required	String	`File` 또는 `Url`
FileInfo.FileId	optional	String	`Type=File`일 때 필수 — VOD 파일 ID
FileInfo.Url	optional	String	`Type=Url`일 때 필수 — 접근 가능한 영상 URL

응답 필드	Type	Description
SessionId	String	세션 ID (24시간 유효). 이후 호출에서 사용
Status	Int64	인식 코드. `0`이면 성공
Fps	Float	영상 프레임레이트
OriginalDuration	Float	영상 길이(초)
Width / Height	Int64	영상 가로 / 세로
TotalFrame	Int64	총 프레임 수
NormalizedVideo	String	정규화된 영상 URL

JSON Request

{
  "SubAppId": 1500000000,
  "FileInfo": { "Type": "Url", "Url": "https://xxx/input.mp4" }
}

JSON Response

200

{
  "Response": {
    "SessionId": "8xxxxxxxxxxx60",
    "Status": 0,
    "Fps": 30.0,
    "OriginalDuration": 5.0,
    "Width": 720,
    "Height": 1280,
    "TotalFrame": 150,
    "NormalizedVideo": "https://xxx/normalized.mp4",
    "RequestId": "xxxx-xxxx"
  }
}

② EditAigcMultiElementsSelection — 선택 영역 편집

하나의 API가 SelectionAction으로 4가지 동작을 구분합니다 — add(선택점 추가) / delete(선택점 삭제) / clear(전체 초기화) / preview(마스크 미리보기). 선택이 만족스러울 때까지 반복 호출합니다.

Parameter		Type	Description
SubAppId	required	uint64	점광 애플리케이션 ID
SelectionAction	required	String	`add` / `delete` / `clear` / `preview`
SessionId	required	String	①에서 받은 SessionId
FrameIndex	optional	Int64	`add`/`delete` 시 필수 — 대상 프레임 번호
Points	optional	Array<Point>	`add`/`delete` 시 필수 — 정규화 좌표. `Point.X`/`Point.Y`는 `[0,1]` 범위

응답 필드	출현	Description
Status	공통	인식 코드(`0`=성공)
Result.FrameIndex	add / delete	현재 조작 프레임 번호
Result.RleMaskList[].ObjectId	add / delete	선택된 객체 ID
Result.RleMaskList[].RleMask	add / delete	선택 마스크 RLE(`Counts`) + 크기(`Size` `[W,H]`)
Result.RleMaskList[].PngMask.Url	add / delete	PNG 마스크 URL
Result.Video / VideoCover	preview	마스크가 표시된 미리보기 영상 / 커버 URL
Result.TrackingOutput	preview	프레임별 마스크 추적 결과 URL

{
  "SubAppId": 1500000000,
  "SelectionAction": "add",
  "SessionId": "8xxxxxxxxxxx60",
  "FrameIndex": 0,
  "Points": [ { "X": 0.773, "Y": 0.297 } ]
}

{
  "Response": {
    "SessionId": "8xxxxxxxxxxx60",
    "Status": 0,
    "Result": {
      "FrameIndex": 0,
      "RleMaskList": [
        { "ObjectId": 0,
          "RleMask": { "Size": [720,1280], "Counts": "..." },
          "PngMask": { "Size": [720,1280], "Url": "https://xxx/mask.png" } }
      ]
    },
    "RequestId": "xxxx-xxxx"
  }
}

{
  "SubAppId": 1500000000,
  "SelectionAction": "clear",
  "SessionId": "8xxxxxxxxxxx60"
}

{
  "Response": {
    "Status": 0,
    "Result": {
      "Video": "https://xxx/preview.mp4",
      "VideoCover": "https://xxx/cover.jpg",
      "TrackingOutput": "https://xxx/tracking.json"
    },
    "RequestId": "xxxx-xxxx"
  }
}

ℹ

동작별 응답

delete의 응답 구조는 add와 동일합니다. clear는 Result 없이 Status만 반환합니다.

③ CreateAigcVideoTask — 최종 영상 생성 (SceneType=multi_elements)

SceneType=multi_elements로 다중 요소 편집 씬을 트리거합니다. ExtInfo의 AdditionalParameters에 앞서 만든 session_id와 edit_mode를 담고, Prompt에서 편집 대상을 <<<video_1>>>로 참조합니다.

JSON Request

{
  "SubAppId": 1500000000,
  "ModelName": "Kling",
  "ModelVersion": "1.6",
  "FileInfos": [
    { "Type": "Url", "Url": "https://xxx.jpeg", "Usage": "Reference" }
  ],
  "Prompt": "<<<video_1>>>에서 특정 피사체 삭제",
  "OutputConfig": { "Duration": 10 },
  "SceneType": "multi_elements",
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"session_id\\\":\\\"8xxxxxxxxxxx60\\\",\\\"edit_mode\\\":\\\"addition\\\"}\"}"
}

JSON Response

200

{
  "Response": {
    "TaskId": "1400000000-AigcVideoTask-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxx-xxxx"
  }
}

📡

결과 조회

반환된 TaskId는 DescribeTaskDetail로 폴링하거나 작업 콜백으로 최종 영상을 받습니다. (→ §4.3 결과 폴링)

8. 과금 & 한도

💰

Pricing

Video Generation 상세 과금 정책은 담당자에게 문의해 주십시오.

ℹ️

Quota

Video Generation 한도는 SubAppId 단위로 관리됩니다. Quota 조회/설정 API와 429 응답 처리 흐름은 Text Generation 페이지의 §4. AIGC Quota 관리를 참고하십시오.

1. Music Generation Overview

오디오 생성 Task를 생성합니다. 두 가지 모드를 지원합니다: SFX (Text-to-SFX) + 음악 생성 (Text-to-Music).

API: CreateAigcAudioTask — Endpoint: vod.tencentcloudapi.com

TaskId를 받은 뒤 DescribeTaskDetail API로 결과를 조회합니다.

1.1 API 정보

POSTvod.tencentcloudapi.com

항목	값
Endpoint	`vod.tencentcloudapi.com`
Method	`POST`
X-TC-Action	`CreateAigcAudioTask`
X-TC-Version	`2018-07-17`
X-TC-Region	`ap-seoul` (Intl 계정) / `ap-guangzhou` (China 계정)

1.2 지원 모델

Sound Effects (SFX, SceneType: sfx)

ModelName	ModelVersion	설명
Kling	—	Kling AI SFX (prompt + duration만 지원)

Music (음악, SceneType: music)

ModelName	ModelVersion	설명
MiniMaxMusic	2.0, 2.5, 2.6, 3.0	MiniMax Text-to-Music (lyrics 파라미터 지원)
GL (Google Lyria)	3.0-clip	짧은 클립 (~30초), 처리 ~18초
GL (Google Lyria)	3.0-pro	풀 트랙 (~2분 36초), 처리 ~50초

2. Input Parameters

Parameter		Type	Description
ModelName	required	String	모델 이름 (Kling / MiniMaxMusic / GL(Google Lyria))
ModelVersion	optional	String	모델 버전
SceneType	required	String	`sfx` (SFX) 또는 `music` (음악)
Prompt	required	String	생성 프롬프트
SubAppId	required	Integer	VOD Sub Application ID (필수. 누락 시 MissingParameter 에러)
AdditionalParameters	optional	String	JSON 형식 추가 파라미터 (예: bgm_prompt·asmr_mode·lyrics 등). `SceneType=sfx+Kling` 시 `bgm_prompt`(배경음악 프롬프트), `asmr_mode`(ASMR 모드 on/off) 전달
VideoInfos.N	optional	Array	참조 비디오 입력. 영상→음효(Kling SFX) 시 음효 프롬프트+배경음악 프롬프트와 함께 전달 — 아래 §4.2 예시 참조
AudioInfos.N	optional	Array	참조 오디오 입력. 음악 생성 시 레퍼런스 오디오를 전달할 때 사용
OutputConfig.StorageMode	optional	String	`Temporary` / `Permanent`
OutputConfig.Duration	optional	Integer	출력 길이 (초, SFX 전용)
OutputConfig.OutputAudioFormat	optional	String	출력 오디오 포맷 (`mp3`·`wav` 등)

2.1 Output Parameters

Parameter	Type	Description
TaskId	String	비동기 태스크 ID (DescribeTaskDetail로 결과 조회)
RequestId	String	요청 고유 ID

⏱

처리 시간 가이드

• Kling SFX 6초: ~20초 이내
• Kling SFX 10초: ~30초
• MiniMaxMusic 2.0/2.5/2.6: 50~75초
• GL 3.0-clip (~30초 클립): ~20초
• GL 3.0-pro (~150초 풀 트랙): ~50초

3. Architecture

Architecture Diagram

4. 코드 예시

4.1 Text-to-SFX (Kling)

Kling SFX CreateAigcAudioTask — Request

JSON

{
    "ModelName": "Kling",
    "SceneType": "sfx",
    "Prompt": "Fireworks sound during celebration",
    "OutputConfig": {
        "StorageMode": "Temporary",
        "Duration": 6
    }
}

Python CommonClient 호출

SDK

from tencentcloud.common import credential
from tencentcloud.common.common_client import CommonClient

cred = credential.Credential("***", "***")
client = CommonClient(credential=cred, region="ap-guangzhou",
    service="vod", version="2018-07-17")

resp = client.call("CreateAigcAudioTask", {
    "ModelName": "Kling",
    "SceneType": "sfx",
    "Prompt": "Fireworks sound during celebration",
    "OutputConfig": {"StorageMode": "Temporary", "Duration": 6}
})
print(resp)

# 결과 조회
detail = client.call("DescribeTaskDetail", {"TaskId": resp["Response"]["TaskId"]})
print(detail)

4.2 Video-to-SFX (Kling)

입력 영상의 장면에 맞춰 음효를 생성합니다. Prompt는 음효(sound effect) 프롬프트, AdditionalParameters로 bgm_prompt(배경음악)와 asmr_mode(ASMR on/off)를 전달합니다.

Kling Video→SFX CreateAigcAudioTask — Request

JSON

{
    "ModelName": "Kling",
    "SceneType": "sfx",
    "VideoInfos": [
        {
            "Type": "Url",
            "Url": "https://example.com/input-video.mp4"
        }
    ],
    "Prompt": "gentle wind, distant birdsong, occasional footsteps, pages turning, raindrops on glass",
    "AdditionalParameters": "{\"bgm_prompt\": \"warm piano, soft string accompaniment, gentle emotion, suitable for narrative video\", \"asmr_mode\": true}",
    "OutputConfig": {
        "StorageMode": "Temporary",
        "Duration": 6
    }
}

Python CommonClient 호출

SDK

client.call("CreateAigcAudioTask", {
    "ModelName": "Kling",
    "SceneType": "sfx",
    "VideoInfos": [{"Type": "Url", "Url": "https://example.com/input-video.mp4"}],
    "Prompt": "gentle wind, distant birdsong, occasional footsteps, pages turning, raindrops on glass",
    "AdditionalParameters": '{"bgm_prompt": "warm piano, soft string accompaniment, gentle emotion, suitable for narrative video", "asmr_mode": true}',
    "OutputConfig": {"StorageMode": "Temporary", "Duration": 6}
})

4.3 MiniMaxMusic 음악 생성

버전 2.0 / 2.5 / 2.6 / 3.0. 아래 예시는 2.0 기준이며 ModelVersion만 바꾸면 동일하게 동작합니다. 3.0 실측: Prompt만으로 요청하니 약 3분 22초 길이의 MP3(44.1kHz 스테레오)가 생성됐고 작업 시간은 약 3분이었습니다. 장르·분위기·BPM을 Prompt에 구체적으로 적을수록 결과가 안정적입니다.

MiniMaxMusic 2.0 CreateAigcAudioTask — Request

JSON

{
    "ModelName": "MiniMaxMusic",
    "ModelVersion": "2.0",
    "SceneType": "music",
    "Prompt": "A cheerful pop song",
    "AdditionalParameters": "{\"lyrics\": \"Hello world, this is my song\"}",
    "OutputConfig": {
        "StorageMode": "Temporary",
        "OutputAudioFormat": "mp3"
    }
}

Python CommonClient 호출

SDK

client.call("CreateAigcAudioTask", {
    "ModelName": "MiniMaxMusic",
    "ModelVersion": "2.0",
    "SceneType": "music",
    "Prompt": "A cheerful pop song",
    "AdditionalParameters": '{"lyrics": "Hello world, this is my song"}',
    "OutputConfig": {"StorageMode": "Temporary", "OutputAudioFormat": "mp3"}
})

4.4 GL (Google Lyria) 3.0-clip

짧은 클립 전용 (~30초). 처리 시간 약 18초. GL은 instrumental 전용으로 lyrics를 전달하지 않습니다.

GL 3.0-clip Request — CreateAigcAudioTask

JSON

{
    "SubAppId": 0,
    "ModelName": "GL",
    "ModelVersion": "3.0-clip",
    "SceneType": "music",
    "Prompt": "Cinematic orchestral build-up, hopeful, 30-second clip",
    "OutputConfig": {
        "StorageMode": "Temporary",
        "OutputAudioFormat": "mp3"
    }
}

Python CommonClient 호출

SDK

client.call("CreateAigcAudioTask", {
    "SubAppId": 0,
    "ModelName": "GL",
    "ModelVersion": "3.0-clip",
    "SceneType": "music",
    "Prompt": "Cinematic orchestral build-up, hopeful, 30-second clip",
    "OutputConfig": {"StorageMode": "Temporary", "OutputAudioFormat": "mp3"}
})

GL 3.0-clip Response — DescribeTaskDetail

JSON

{
    "TaskType": "AigcAudioTask",
    "Status": "FINISH",
    "CreateTime":      "2026-06-07T15:24:05Z",
    "BeginProcessTime":"2026-06-07T15:24:05Z",
    "FinishTime":      "2026-06-07T15:24:23Z",
    "AigcAudioTask": {
        "TaskId":   "***-AigcAudioTask-***t",
        "Status":   "FINISH",
        "ErrCode":  0,
        "Progress": 100,
        "Input": {
            "ModelName":     "GL",
            "ModelVersion":  "3.0-clip",
            "SceneType":     "music",
            "Prompt":        "Cinematic orchestral build-up, hopeful, 30-second clip",
            "OutputConfig":  { "StorageMode": "Temporary", "OutputAudioFormat": "mp3" }
        },
        "Output": {
            "AudioInfos": [{
                "StorageMode": "Temporary",
                "FileUrl":     "http://***.vod2.myqcloud.com/.../aigcAudioGenFile.mp3",
                "ExpireTime":  "2026-06-14T15:24:25Z",
                "MetaData": {
                    "Size":          744610,
                    "Container":     "mp3",
                    "Bitrate":       193580,
                    "Duration":      30.772,
                    "AudioStreamSet": [{ "Bitrate": 192000, "SamplingRate": 44100, "Codec": "mp3" }],
                    "AudioDuration": 30.772
                }
            }]
        }
    }
}

4.5 GL (Google Lyria) 3.0-pro

풀 트랙 생성 (~2분 36초). 처리 시간 약 50초.

GL 3.0-pro Request — CreateAigcAudioTask

JSON

{
    "SubAppId": 0,
    "ModelName": "GL",
    "ModelVersion": "3.0-pro",
    "SceneType": "music",
    "Prompt": "Energetic synth-pop instrumental with retro 80s vibes, driving drum machine, bright lead synth, full song structure",
    "OutputConfig": {
        "StorageMode": "Temporary",
        "OutputAudioFormat": "mp3"
    }
}

Python CommonClient 호출

SDK

client.call("CreateAigcAudioTask", {
    "SubAppId": 0,
    "ModelName": "GL",
    "ModelVersion": "3.0-pro",
    "SceneType": "music",
    "Prompt": "Energetic synth-pop instrumental with retro 80s vibes, driving drum machine, bright lead synth, full song structure",
    "OutputConfig": {"StorageMode": "Temporary", "OutputAudioFormat": "mp3"}
})

GL 3.0-pro Response — DescribeTaskDetail

JSON

{
    "TaskType": "AigcAudioTask",
    "Status": "FINISH",
    "CreateTime":      "2026-06-07T17:08:36Z",
    "BeginProcessTime":"2026-06-07T17:08:36Z",
    "FinishTime":      "2026-06-07T17:09:26Z",
    "AigcAudioTask": {
        "TaskId":   "***-AigcAudioTask-***t",
        "Status":   "FINISH",
        "ErrCode":  0,
        "Progress": 100,
        "Input": {
            "ModelName":     "GL",
            "ModelVersion":  "3.0-pro",
            "SceneType":     "music",
            "Prompt":        "Energetic synth-pop instrumental with retro 80s vibes, driving drum machine, bright lead synth, full song structure",
            "OutputConfig":  { "StorageMode": "Temporary", "OutputAudioFormat": "mp3" }
        },
        "Output": {
            "AudioInfos": [{
                "StorageMode": "Temporary",
                "FileUrl":     "http://***.vod2.myqcloud.com/.../aigcAudioGenFile.mp3",
                "ExpireTime":  "2026-06-14T17:09:26Z",
                "MetaData": {
                    "Size":          3748900,
                    "Container":     "mp3",
                    "Bitrate":       192311,
                    "Duration":      155.95,
                    "AudioStreamSet": [{ "Bitrate": 192000, "SamplingRate": 44100, "Codec": "mp3" }],
                    "AudioDuration": 155.951
                }
            }]
        }
    }
}

4.6 GL 모델 비교

	GL 3.0-clip	GL 3.0-pro
출력 길이	~30초 (짧은 클립)	~150초 (풀 트랙)
처리 시간	~18초	~50초
파일 크기 (192kbps mp3)	~744 KB	~3.7 MB
권장 용도	BGM 인트로/스팅어, 광고 클립	풀 음원, 컨텐츠 BGM, 라이센싱

⚠

GL 3.0-pro 권장 사용법

구체적인 장르/악기/구조를 prompt에 명시하십시오 (예: "with X instrument, Y BPM, full song structure"). 막연한 prompt에서는 오류가 발생할 수 있습니다.

⚠

GL 모델 주의사항

AdditionalParameters의 lyrics 필드는 MiniMaxMusic 전용입니다. GL 모델에 lyrics를 넣으면 ErrCode=70000 + "AudioInfos is empty"로 출력이 누락됩니다. GL은 instrumental 전용입니다.

⚠

동시 실행 제한

Audio 모델 패밀리별 동시 1 task 권장. 초과 시 ErrCode=70000으로 즉시 종료됩니다.

✓

MiniMaxMusic 한국어 가사 지원

lyrics 필드에 한국어를 그대로 입력하면 보컬이 한국어로 발음됩니다.

ℹ

결과 조회

DescribeTaskDetail API로 TaskId를 조회하여 결과를 확인합니다.

5. 과금 안내

💰

Pricing

요금 관련 상세 정보는 AIGC 가격 가이드를 참고하십시오.

ℹ️ Intl 계정: VOD endpoint(vod.tencentcloudapi.com) + region ap-seoul로 정상 호출 가능. China 계정: region ap-guangzhou. 어느 경우든 SubAppId는 필수.

1. 3D Generation Overview

Hunyuan 3D World Model 기반 3D 콘텐츠 생성입니다. 두 가지 모드를 지원합니다:

1. 360 파노라마 (Panorama): CreateAigcImageTask — SceneType: 3d_panorama

2. 3D 씬/모델 생성: CreateAigcVideoTask — SceneType: 3d_scene

1.1 API 정보

360 Panorama

POSTvod.tencentcloudapi.com

항목	값
X-TC-Action	`CreateAigcImageTask`
ModelName	`Hunyuan`
ModelVersion	`3d_2.0`
SceneType	`3d_panorama`

3D Scene/Model

POSTvod.tencentcloudapi.com

항목	값
X-TC-Action	`CreateAigcVideoTask`
ModelName	`Hunyuan`
ModelVersion	`3d_2.0`
SceneType	`3d_scene`

1.2 모델 기능

모드	입력	출력	활용 사례
3D World 생성 (Text/Image → 3D)	텍스트 프롬프트 (사실적/카툰/고풍/SF 등), 이미지 1장 (사진/스케치/손그림)	360° 3DGS/Mesh 씬, 자유로운 탐색·물리 충돌 지원, Unity/UE로 임포트 가능	게임 레벨, VR 공간, 인테리어, 크리에이티브 콘텐츠
3D 재구성 (Real-world Reconstruction)	다중 시점 이미지 또는 짧은 동영상 (orbital 촬영)	실물과 1:1로 일치하는 high-fidelity 디지털 트윈, measurement·editing·simulation 가능	산업용 디지털 트윈, 문화유산 디지털화, 부동산 가상 투어
360 파노라마 합성 (Panorama)	텍스트 / 단일 이미지	Seamless 360° ERP(eqirectangular) 파노라마	VR/AR, 영상 배경 플레이트, 가상 스튜디오

1.3 출력 사양

항목	값
출력 포맷	3D Gaussian Splatting (.spz), Mesh (GLB/FBX/OBJ), Point Cloud (.ply), 파노라마 비디오
생성 속도	텍스트→3D: 3~8분 / 이미지·비디오 재건: 5~15분
엔진 호환	Unity / Unreal Engine 네이티브 지원
오픈소스	2026.04.16 오픈소스 (모델 가중치 + 추론 코드 + 기술 백서, 상업 가능)

2. Parameters — Panorama (CreateAigcImageTask)

Parameter		Type	Description
SubAppId	required	Integer	VOD Sub Application ID (필수. 누락 시 MissingParameter 에러)
ModelName	required	String	`Hunyuan`
ModelVersion	required	String	`3d_2.0`
SceneType	required	String	`3d_panorama`
Prompt	required	String	생성 프롬프트
FileInfos.N	optional	Array	입력 이미지
OutputConfig.StorageMode	optional	String	`Temporary` / `Permanent`

3. Parameters — 3D Scene (CreateAigcVideoTask)

Parameter		Type	Description
SubAppId	required	Integer	VOD Sub Application ID (필수. 누락 시 MissingParameter 에러)
ModelName	required	String	`Hunyuan`
ModelVersion	required	String	`3d_2.0`
SceneType	required	String	`3d_scene`
Prompt	required	String	생성 프롬프트
FileInfos.N	optional	Array	입력 이미지
OutputConfig.StorageMode	optional	String	`Temporary` / `Permanent`
OutputConfig.Duration	optional	Integer	출력 길이 (초)
OutputConfig.Resolution	optional	String	`1080P` 등
OutputConfig.AudioGeneration	optional	String	`Enabled` / `Disabled`

4. Architecture

Architecture Diagram

5. 코드 예시

5.1 360 Panorama

Hunyuan 3D CreateAigcImageTask (Panorama)

JSON

{
    "SubAppId": 1500044236,
    "ModelName": "Hunyuan",
    "ModelVersion": "3d_2.0",
    "Prompt": "A futuristic cyberpunk city at night with neon lights",
    "OutputConfig": {
        "StorageMode": "Permanent"
    },
    "SceneType": "3d_panorama"
}

5.2 3D Scene Generation

Hunyuan 3D CreateAigcVideoTask (3D Scene)

JSON

{
    "SubAppId": 1500044236,
    "ModelName": "Hunyuan",
    "ModelVersion": "3d_2.0",
    "Prompt": "A traditional Korean hanok village surrounded by autumn foliage, photorealistic rendering, 8K resolution",
    "OutputConfig": {
        "StorageMode": "Temporary",
        "Duration": 16,
        "Resolution": "1080P",
        "AudioGeneration": "Enabled"
    },
    "SceneType": "3d_scene"
}

⚠

Status 처리 주의

종료 상태는 FINISH 또는 DONE 둘 다 가능합니다 (호출 경로에 따라 상이). 반드시 양쪽 모두 체크하십시오. 또한 ErrCode가 0이 아니면 실패이므로 Status만으로 성공을 판단하지 마세요.

⏱

처리 시간 가이드

Panorama: 약 1분 (58~74초)
Scene (3D Video): 5~15분 이상 (단순 5초 1080P도 25분+ 소요 케이스 관측)

⚠

동시 실행 제한

모델 패밀리(Image/Video)별 동시 1 task 권장. 초과 시 Status=FINISH + ErrCode=70000 + "Generate task reached the maximum concurrency."로 즉시 종료됩니다. ErrCode 검사가 필수입니다.

6. 과금 안내

💰

Pricing

요금 관련 상세 정보는 AIGC 가격 가이드를 참고하십시오.

ℹ️ 담당자에게 MPS로 사용을 안내받은 경우에만 아래 내용을 참고해주십시오.

1. MPS AIGC Overview

MPS(Media Processing Service) 엔드포인트를 통한 AIGC 콘텐츠 생성 가이드입니다. MPaaS AIGC(VOD 엔드포인트)와 동일한 모델 패밀리를 사용하며, 인증 방식(TC3-HMAC-SHA256)과 파라미터 구조가 다릅니다.

⚠

MPaaS AIGC vs MPS AIGC

	MPaaS AIGC (VOD)	MPS AIGC
Endpoint	vod.tencentcloudapi.com	mps.intl.tencentcloudapi.com
인증	AIGC API Token (Bearer)	SecretId/SecretKey (TC3-HMAC-SHA256)
결과 저장	SubAppId 내 미디어	임시 URL(약 12h) 또는 StoreCosParam(영구 COS)
SDK	tencentcloud-sdk-python (vod)	tencentcloud-sdk-python (mps)
API Version	2018-07-17	2019-06-12

1.1 공통 API 정보

항목	값
Endpoint	`mps.intl.tencentcloudapi.com`
API Version	`2019-06-12`
Region	`ap-seoul` (Intl) / `ap-guangzhou` (China)
인증	TC3-HMAC-SHA256 (SecretId + SecretKey)
Method	`POST`
Content-Type	`application/json`

1.2 지원 모델 — Image

모델명	설명	버전
GEM	Nano Banana — 고품질 범용 이미지 생성	2.5 3.0 3.1
OG	1K/2K/4K 해상도 이미지 생성	image2_low image2_medium image2_high
Qwen	Qwen 이미지 생성	0925
Seedream	고해상도 AI 아트 생성	4.5 5.0-lite
Kling	이미지 생성 + Outpainting	2.1 3.0 3.0-Omni scene
Vidu	고품질 이미지 생성	q2
Jimeng	Jimeng 이미지 생성 엔진	4.0
MJ (Midjourney)	고품질 아트 이미지, 참조 + Prompt 기반	v7 v8.1
GPT-Image2	OpenAI 이미지 생성/편집, 마스크, 투명 레이어	gpt-image-2

1.3 지원 모델 — Video

모델명	설명	버전
Kling	전체 모델 영상 — Text/Image/Reference/Motion Control/Lip Sync/Multi-shot/Outpainting	1.6 2.0 2.1 2.5 2.6 3.0 3.0-Omni O1 3.0-motion-control
Vidu	Text/Image/First+Last Frame/Reference/Custom Subject	q2 q2-turbo q2-pro q3 q3-pro q3-turbo q3-mix
PixVerse	Text/Image/First+Last Frame/Reference, Quality(360p~1080p), 음향 자동 생성	v5.6 v6 c1
Hailuo (MiniMax Video)	고품질 영상 생성. H3는 네이티브 멀티모달(이미지·영상·오디오 참조 입력)과 음성 동시 생성 지원	02 2.3 2.3-fast H3
GV (Google Veo)	Google AI 영상 생성, 오디오 지원	3.1 3.1-fast
OS (OpenAI Sora)	OpenAI 영상 생성	2.0
Jimeng	Jimeng 영상 생성 엔진	3.0pro
SV	인물 영상 특화(소재 기반). 인물 사진 기반 영상 제작 검열에 매우 민감	1.0-pro 1.0-pro-fast 1.5-pro 1.0-lite-i2v
VS	고품질 영상 생성 (2.5: First+Last Frame·멀티모달 참조·최대 30s)	2.0 2.0-fast 2.0-mini 2.5
Mingmou	Mingmou 영상 생성	1.0
H2	H2 영상 생성 엔진	1.0

1.4 Action 목록

Action	기능	비고
CreateAigcImageTask	이미지 생성 태스크 생성	비동기 (TaskId 반환)
CreateAigcVideoTask	비디오 생성 태스크 생성	비동기 (TaskId 반환)
CreateAigcAudioTask	오디오(음악/효과음) 생성 태스크 생성	비동기 (TaskId 반환)
DescribeAigcImageTask	이미지 태스크 결과 조회	TaskId로 폴링
DescribeAigcVideoTask	비디오 태스크 결과 조회	TaskId로 폴링
DescribeAigcAudioTask	오디오 태스크 결과 조회	TaskId로 폴링
DescribeUsageData	미디어 처리 사용량 통계	StartTime/EndTime 구간 집계

2. CreateAigcImageTask

AIGC 이미지 생성 태스크를 생성합니다. 비동기 방식으로 TaskId를 반환하며, DescribeAigcImageTask로 결과를 조회합니다.

2.1 Input Parameters

Parameter		Type	Description
ModelName	required	String	모델명 (GEM, Kling, Seedream, Qwen, Jimeng, MJ, Vidu, OG 등)
ModelVersion	optional	String	모델 버전 (예: 3.1, 5.0-lite, 3.0-Omni)
Prompt	required	String	생성 프롬프트
NegativePrompt	optional	String	제외할 요소 (네거티브 프롬프트)
EnhancePrompt	optional	Boolean	프롬프트 자동 보강 여부
ImageInfos.N	optional	Array of Object	참조 이미지 (Image-to-Image, 편집)
ImageInfos.N.ImageUrl	required	String	참조 이미지 URL
StoreCosParam	optional	Object	영구 COS 저장 설정. 미지정 시 약 12시간 유효한 임시 URL 반환 (별도 `MPS_QcsRole` 권한 필요)
AdditionalParameters	optional	String	JSON 문자열 추가 파라미터. 예: `{"size":"2048x2048"}` (Seedream은 최소 3,686,400 px 이상 필요)

2.2 Output Parameters

Parameter	Type	Description
TaskId	String	태스크 고유 ID (DescribeAigcImageTask에 사용)
RequestId	String	요청 고유 ID

2.3 엔진별 차이 매트릭스

CreateAigcImageTask가 지원하는 이미지 엔진과 권장 파라미터입니다. ModelName만 바꾸면 동일 골격으로 호출됩니다.

#	ModelName	ModelVersion	권장 AspectRatio	특이사항
1	GEM	`3.1`	`1:1`	Quickstart 기본 엔진. prompt-only 동작.
2	Qwen	`0925`	`1:1`	자유 해상도. `AdditionalParameters`의 `size` 직접 지정 가능(512²~2048²).
3	Seedream	`5.0-lite`	`1:1`	`size` 지정 시 최소 3,686,400 px 이상 필요(예: 2048×2048).
4	Kling	`3.0-Omni`	`1:1`	—
5	Jimeng	`4.0`	`1:1`	`AdditionalParameters`로 `width/height` 직접 지정(변당 1024~4096px).
6	MJ	`v7` / `v8.1`	`16:9`	1요청 = 4장 고정. 자체 prompt 문법(`--s`/`--c`/`--sref`). 파라미터는 Prompt로 전달(§3.8).
7	Vidu	`q2`	`1:1`	—
8	OG	`image2_high`	`1:1`	image2_low / image2_medium / image2_high (1K/2K/4K).

2.4 엔진별 전체 Request

8개 엔진의 전체 Request Body입니다. 모든 엔진의 응답은 동일하게 { "Response": { "TaskId": "...", "RequestId": "..." } } 형태이며, 이후 DescribeAigcImageTask로 결과를 조회합니다.

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "GEM",
    "ModelVersion": "3.1",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" }
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Qwen",
    "ModelVersion": "0925",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" },
    "AdditionalParameters": "{\"size\":\"1024x1024\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Seedream",
    "ModelVersion": "5.0-lite",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" },
    "AdditionalParameters": "{\"size\":\"2048x2048\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Kling",
    "ModelVersion": "3.0-Omni",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" }
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Jimeng",
    "ModelVersion": "4.0",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" },
    "AdditionalParameters": "{\"width\":1920,\"height\":1080}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "MJ",
    "ModelVersion": "v7",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "16:9" }
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Vidu",
    "ModelVersion": "q2",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" }
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcImageTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "OG",
    "ModelVersion": "image2_high",
    "Prompt": "A clean product-style capybara mascot image, studio lighting",
    "EnhancePrompt": true,
    "OutputConfig": { "AspectRatio": "1:1" }
  }
}

2.5 호출 & 응답 예시

Python CreateAigcImageTask

Python

import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models

cred = credential.Credential("YOUR_SECRET_ID", "YOUR_SECRET_KEY")
httpProfile = HttpProfile()
httpProfile.endpoint = "mps.intl.tencentcloudapi.com"
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
client = mps_client.MpsClient(cred, "ap-seoul", clientProfile)

req = models.CreateAigcImageTaskRequest()
params = {
    "ModelName": "Seedream",
    "ModelVersion": "5.0-lite",
    "Prompt": "A serene zen garden with cherry blossoms, soft morning light",
    "EnhancePrompt": True,
    "AdditionalParameters": json.dumps({"size": "2048x2048"})
}
req.from_json_string(json.dumps(params))
resp = client.CreateAigcImageTask(req)
print(resp.to_json_string())
# {"TaskId": "2600012260-AigcImage-743691...", "RequestId": "c3cef9a9-..."}

CLI tccli

Shell

tccli mps CreateAigcImageTask \
  --endpoint mps.intl.tencentcloudapi.com \
  --region ap-seoul \
  --ModelName "GEM" \
  --ModelVersion "3.1" \
  --Prompt "A serene mountain landscape with cherry blossoms" \
  --EnhancePrompt True \
  --AdditionalParameters '{"size":"2048x2048"}'

Response CreateAigcImageTask

JSON

{
    "Response": {
        "Data": [
            {
                "TaskType": "AIGCVideo",
                "Summary": [
                    {"Time": "2026-06-20T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-21T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-22T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-23T00:00:00+08:00", "Count": 1,  "Usage": 5},
                    {"Time": "2026-06-24T00:00:00+08:00", "Count": 1,  "Usage": 5},
                    {"Time": "2026-06-25T00:00:00+08:00", "Count": 16, "Usage": 85},
                    {"Time": "2026-06-26T00:00:00+08:00", "Count": 4,  "Usage": 20}
                ],
                "Details": [
                    {
                        "Specification": "aigc-video.PixVerse",
                        "Data": [
                            {"Time": "2026-06-24T00:00:00+08:00", "Count": 1, "Usage": 5},
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 5}
                        ]
                    },
                    {
                        "Specification": "aigc-video.Hailuo",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 6}
                        ]
                    },
                    {
                        "Specification": "aigc-video.Vidu",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 5}
                        ]
                    },
                    {
                        "Specification": "aigc-video.OS",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 8}
                        ]
                    },
                    {
                        "Specification": "aigc-video.VS",
                        "Data": [
                            {"Time": "2026-06-23T00:00:00+08:00", "Count": 1, "Usage": 5},
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 5, "Usage": 25},
                            {"Time": "2026-06-26T00:00:00+08:00", "Count": 4, "Usage": 20}
                        ]
                    },
                    {
                        "Specification": "aigc-video.H2",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 2, "Usage": 10}
                        ]
                    },
                    {
                        "Specification": "aigc-video.Mingmou",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 6}
                        ]
                    },
                    {
                        "Specification": "aigc-video.Jimeng",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 5}
                        ]
                    },
                    {
                        "Specification": "aigc-video.Kling",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 3, "Usage": 15}
                        ]
                    }
                ]
            },
            {
                "TaskType": "AIGCImage",
                "Summary": [
                    {"Time": "2026-06-20T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-21T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-22T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-23T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-24T00:00:00+08:00", "Count": 0,  "Usage": 0},
                    {"Time": "2026-06-25T00:00:00+08:00", "Count": 12, "Usage": 18},
                    {"Time": "2026-06-26T00:00:00+08:00", "Count": 2,  "Usage": 2}
                ],
                "Details": [
                    {
                        "Specification": "aigc-image.Hunyuan",
                        "Data": [
                            {"Time": "2026-06-26T00:00:00+08:00", "Count": 1, "Usage": 1}
                        ]
                    },
                    {
                        "Specification": "aigc-image.GEM",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 1},
                            {"Time": "2026-06-26T00:00:00+08:00", "Count": 1, "Usage": 1}
                        ]
                    },
                    {
                        "Specification": "aigc-image.Vidu",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 1}
                        ]
                    },
                    {
                        "Specification": "aigc-image.Jimeng",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 2, "Usage": 2}
                        ]
                    },
                    {
                        "Specification": "aigc-image.MJ",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 2, "Usage": 8}
                        ]
                    },
                    {
                        "Specification": "aigc-image.OG",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 1}
                        ]
                    },
                    {
                        "Specification": "aigc-image.Qwen",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 1, "Usage": 1}
                        ]
                    },
                    {
                        "Specification": "aigc-image.Seedream",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+08:00", "Count": 4, "Usage": 4}
                        ]
                    }
                ]
            }
        ],
        "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}

ⓘ

완료 응답 (DONE)

DescribeAigcImageTask가 Status=DONE을 반환하면 Message="ok"과 함께 ImageUrls에 결과 이미지가 채워집니다(미지정 시 약 12시간 유효한 프리사인 COS URL).

Response DescribeAigcImageTask (DONE)

JSON

{
    "Status": "DONE",
    "ImageUrls": [
        "https://***.cos.ap-seoul.myqcloud.com/output/aigc-image/2600012260-AigcImage-a2c0411...._0.jpg?q-sign-algorithm=sha1&q-ak=***&..."
    ],
    "Message": "ok",
    "RequestId": "0cc63f11-d730-407b-b834-d051a217657c"
}

3. CreateAigcVideoTask

AIGC 비디오 생성 태스크를 생성합니다. 비동기 방식으로 TaskId를 반환하며, DescribeAigcVideoTask로 결과를 조회합니다.

3.1 Input Parameters

Parameter		Type	Description
ModelName	required	String	모델명 (Kling, Vidu, Hailuo, GV, OS, VS, Jimeng 등)
ModelVersion	optional	String	모델 버전 (예: 3.0-turbo, q3, q3-drama)
Prompt	required	String	생성 프롬프트
NegativePrompt	optional	String	제외할 요소
EnhancePrompt	optional	Boolean	프롬프트 자동 보강 여부
ImageInfos.N	optional	Array of Object	참조 이미지 (First/Last Frame, Reference)
ImageInfos.N.ImageUrl	required	String	참조 이미지 URL
StoreCosParam	optional	Object	영구 COS 저장 설정. 미지정 시 약 12시간 유효한 임시 URL 반환 (`MPS_QcsRole` 권한 필요)
AdditionalParameters	optional	String	JSON 문자열. 예: `{"duration":5,"resolution":"1080P","aspect_ratio":"16:9"}`

3.2 Output Parameters

Parameter	Type	Description
TaskId	String	태스크 고유 ID (DescribeAigcVideoTask에 사용)
RequestId	String	요청 고유 ID

3.3 엔진별 차이 매트릭스

CreateAigcVideoTask가 지원하는 영상 엔진과 권장 파라미터입니다. 공통 AdditionalParameters는 {"duration":5,"resolution":"720P","aspect_ratio":"16:9"} 기준이며, 모델별 허용값은 특이사항을 참고하십시오.

#	ModelName	ModelVersion	AdditionalParameters 특이	특이사항
1	Kling	`3.0-Omni`	Reference 영상 지원, 멀티샷(분할 장면) 지원	플래그십. 참조 영상은 Kling 전용.
2	Vidu	`q3`	—	—
3	PixVerse	`v6`	음향 자동 생성	버전 v5.6 / v6 / c1, 길이 1~15s, 화질 360p~1080p.
4	Hailuo	`2.3`	duration 6/10 고정	MiniMax Video. 길이가 6초·10초로 고정.
5	GV	`3.1`	오디오 생성	Google Veo.
6	OS	`2.0`	720P 중심	OpenAI Sora.
7	Jimeng	`3.0pro`	—	—
8	VS	`2.0`	—	고품질 영상.
8	VS	`2.5`	Duration 4~30s · 480P/720P/2K/4K(2K·4K SR) · 이미지·영상·오디오 참조 ≤50(이미지 30 + 영상 10 + 오디오 10) · 종횡비 21:9/16:9/4:3/1:1/3:4/9:16	고품질 영상, 최대 30초.
9	SV	`1.0-pro`	인물 특화(소재 기반)	ModelName `Seedance`. 인물 검열 민감.
10	Mingmou	`1.0`	—	—
11	H2	`1.0` / `1.1`	1.1: Text/Image/Reference, 720P~4K, 3~15s	1.1은 이미지 생성 시 첫 프레임만, 참조 생성 1~9장.
11	Kling	`3.0-turbo`	720P~4K, 3~15s	문생/이미지(1장). 문생 시 AspectRatio 16:9/9:16/1:1. 주체 참조 지원.
12	Vidu	`q3-drama`	1080P/2K/4K(Super Resolution), 8~12s	참조 1~14장. AspectRatio 9:16/16:9. 주체 참조 지원.
13	Vidu	`q3-ad`	720P~4K(2K/4K Super Resolution), 3~16s	참조 1~7장. 참조 생성 전용. AspectRatio 1:1/9:16/16:9/3:4/4:3.

ℹ

다중 요소 편집 (SceneType=multi_elements)

MPS CreateAigcVideoTask도 SceneType=multi_elements를 지원하며, AdditionalParameters에 session_id·edit_mode를 담아 전달합니다. 단, 선택 영역을 만드는 InitializeAigcMultiElementsSelection / EditAigcMultiElementsSelection 세션 API는 VOD 전용입니다. 따라서 선택 세션은 VOD에서 생성하고, 발급된 session_id를 사용합니다. 전체 흐름과 파라미터는 VOD 측 Video Generation §7.8을 참고하십시오.

3.4 엔진별 전체 Request

10개 엔진의 전체 Request Body입니다. 응답은 동일하게 { "Response": { "TaskId": "...", "RequestId": "..." } } 형태이며, 이후 DescribeAigcVideoTask로 결과를 조회합니다.

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Kling",
    "ModelVersion": "3.0-Omni",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Vidu",
    "ModelVersion": "q3",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "PixVerse",
    "ModelVersion": "v6",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Hailuo",
    "ModelVersion": "2.3",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "GV",
    "ModelVersion": "3.1",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "OS",
    "ModelVersion": "2.0",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Jimeng",
    "ModelVersion": "3.0pro",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "VS",
    "ModelVersion": "2.0",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Mingmou",
    "ModelVersion": "1.0",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcVideoTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "H2",
    "ModelVersion": "1.0",
    "Prompt": "A calm ocean wave at sunset, cinematic",
    "AdditionalParameters": "{\"duration\":5,\"resolution\":\"720P\",\"aspect_ratio\":\"16:9\"}"
  }
}

3.5 호출 & 응답 예시

Python CreateAigcVideoTask

Python

import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models

cred = credential.Credential("YOUR_SECRET_ID", "YOUR_SECRET_KEY")
httpProfile = HttpProfile()
httpProfile.endpoint = "mps.intl.tencentcloudapi.com"
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
client = mps_client.MpsClient(cred, "ap-seoul", clientProfile)

req = models.CreateAigcVideoTaskRequest()
params = {
    "ModelName": "Kling",
    "ModelVersion": "3.0-Omni",
    "Prompt": "A cat walking gracefully on a sunny windowsill, cinematic",
    "ImageInfos": [{
        "ImageUrl": "https://example.com/cat-photo.jpg"
    }],
    "AdditionalParameters": json.dumps({
        "duration": 5,
        "resolution": "1080P",
        "aspect_ratio": "16:9"
    })
}
req.from_json_string(json.dumps(params))
resp = client.CreateAigcVideoTask(req)
print(resp.to_json_string())
# {"TaskId": "2600012260-AigcVideo-xxxx", "RequestId": "..."}

CLI tccli

Shell

tccli mps CreateAigcVideoTask \
  --endpoint mps.intl.tencentcloudapi.com \
  --region ap-seoul \
  --ModelName "Kling" \
  --ModelVersion "3.0-Omni" \
  --Prompt "Ocean waves crashing on rocks at sunset, cinematic" \
  --AdditionalParameters '{"duration":5,"resolution":"1080P","aspect_ratio":"16:9"}'

Response CreateAigcVideoTask

JSON

{
    "Response": {
        "RequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "TaskId": "2600012260-AigcVideo-9f8e7d6c5b4a39281706f5e4d3c2b1a0"
    }
}

ⓘ

완료 응답 (DONE)

DescribeAigcVideoTask가 Status=DONE을 반환하면 Resolution에 실제 출력 해상도(예: 1280x720)가, VideoUrls에 결과 영상(프리사인 COS URL)이 채워집니다.

Response DescribeAigcVideoTask (DONE)

JSON

{
    "Status": "DONE",
    "VideoUrls": [
        "https://aigc-output-video-***.cos.ap-guangzhou.myqcloud.com/.../2600012260-AigcVideo-8b48eaa..._0.mp4?q-sign-algorithm=sha1&q-ak=***&..."
    ],
    "Resolution": "1280x720",
    "Message": "ok",
    "RequestId": "15cd9f4e-9e12-4bf2-818b-f914f4ef49b1"
}

4. CreateAigcAudioTask

AIGC 오디오 생성 태스크를 생성합니다. 음악(music)과 효과음(sfx) 두 가지 장면을 지원하며, 비동기 방식으로 TaskId를 반환하고 DescribeAigcAudioTask로 결과를 조회합니다.

4.1 Input Parameters

Parameter		Type	Description
ModelName	required	String	모델명. 음악: `GL`, `MinimaxMusic` / 효과음: `Kling`, `Tme` 등
ModelVersion	optional	String	모델 버전. `GL`: `2.0` / `3.0-clip` / `3.0-pro`, `MinimaxMusic`: `2.0` / `2.5` / `2.6`
SceneType	optional	String	`music` (음악 생성) / `sfx` (효과음 생성)
Prompt	required	String	생성 오디오 설명 (최대 2000자). 참조 입력이 없으면 필수
VideoInfos.N	optional	Array of Object	참조 비디오 정보. 일부 모델만 지원
VideoInfos.N.VideoUrl	optional	String	참조 비디오 URL
AudioInfos.N	optional	Array of Object	참조 오디오 정보
AudioInfos.N.AudioUrl	optional	String	참조 오디오 URL
AdditionalParameters	optional	String	모델별 특수 파라미터를 담은 JSON 문자열. 예: `{"lyrics":"..."}`

국제 콘솔 참고

국제 콘솔(mps.intl.tencentcloudapi.com)에서는 OutputConfig 파라미터를 받지 않습니다. ModelName / ModelVersion / SceneType / Prompt 중심의 최소 구성으로 호출하며, 생성 결과는 모델 측 스토리지를 통해 제공됩니다.

4.2 Output Parameters

Parameter	Type	Description
TaskId	String	태스크 고유 ID (DescribeAigcAudioTask에 사용)
RequestId	String	요청 고유 ID

4.3 장면 · 엔진별 매트릭스

CreateAigcAudioTask가 지원하는 장면과 엔진입니다. SceneType으로 음악/효과음을 구분하며, 모델별 버전과 특이사항을 참고하십시오.

#	SceneType	ModelName	ModelVersion	특이사항
1	`music`	GL	`3.0-pro`	음악 생성 플래그십. 버전 2.0 / 3.0-clip / 3.0-pro.
2	`music`	MinimaxMusic	`2.6`	MiniMax 음악. 버전 2.0 / 2.5 / 2.6. 일부 지역·계정에서 개방.
3	`sfx`	Kling	—	장면 묘사 기반 효과음 생성.
4	`sfx`	Tme	—	효과음 생성.

4.4 장면별 전체 Request

음악·효과음 장면의 전체 Request Body입니다. 응답은 동일하게 { "Response": { "TaskId": "...", "RequestId": "..." } } 형태이며, 이후 DescribeAigcAudioTask로 결과를 조회합니다.

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcAudioTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "GL",
    "ModelVersion": "3.0-pro",
    "SceneType": "music",
    "Prompt": "Bright energetic K-pop instrumental, 120bpm, uplifting"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcAudioTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "MinimaxMusic",
    "ModelVersion": "2.6",
    "SceneType": "music",
    "Prompt": "Warm lo-fi piano with soft drums, relaxing",
    "AdditionalParameters": "{\"lyrics\":\"...\"}"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcAudioTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Kling",
    "SceneType": "sfx",
    "Prompt": "Fireworks during a festival celebration"
  }
}

{
  "endpoint": "mps.intl.tencentcloudapi.com",
  "action": "CreateAigcAudioTask",
  "region": "ap-seoul",
  "auth": "TC3-HMAC-SHA256",
  "request": {
    "ModelName": "Tme",
    "SceneType": "sfx",
    "Prompt": "Heavy rain with distant thunder"
  }
}

4.5 호출 & 응답 예시

music GL 3.0-pro

Shell

tccli mps CreateAigcAudioTask \
  --endpoint mps.intl.tencentcloudapi.com \
  --region ap-seoul \
  --ModelName GL \
  --ModelVersion 3.0-pro \
  --SceneType music \
  --Prompt "Bright energetic K-pop instrumental, 120bpm, uplifting"

Response CreateAigcAudioTask

JSON

{
    "Response": {
        "TaskId": "2600012260-AigcAudio-b66988ea340243368659616baaa08cba",
        "RequestId": "ca6d4e13-ea83-4411-a1a6-aaa68a19dd72"
    }
}

5. DescribeAigcImageTask

CreateAigcImageTask로 생성한 이미지 태스크의 상태와 결과를 조회합니다. Status가 DONE(성공) 또는 FAIL(실패)이 될 때까지 폴링합니다.

5.1 Input Parameters

Parameter		Type	Description
TaskId	required	String	CreateAigcImageTask에서 반환된 TaskId

5.2 Output Parameters

Parameter	Type	Description
Status	String	`WAIT` (대기) / `RUN` (처리 중) / `DONE` (성공) / `FAIL` (실패)
ImageUrls	Array of String	생성된 이미지 URL 목록. 성공 시 채워지며, StoreCosParam 미지정 시 약 12시간 유효한 프리사인 COS URL
Message	String	성공 시 `"ok"`, 실패 시 에러 메시지
RequestId	String	요청 ID

5.3 Response 예시

Response DescribeAigcImageTask (DONE)

JSON

{
    "Response": {
        "Status": "DONE",
        "ImageUrls": [
            "https://aigc-output-image-***.cos.ap-guangzhou.myqcloud.com/.../2600012260-AigcImage-***_0.jpg?q-sign-algorithm=sha1&q-ak=***&q-sign-time=***"
        ],
        "Message": "ok",
        "RequestId": "bf66c45d-2324-417f-a545-d3b60bde2645"
    }
}

⚠

실패 판정

Status=FAIL이면 ImageUrls는 빈 배열이고 Message에 사유가 담깁니다. 예: 잘못된 size 지정 시 "image size must be at least 3686400 pixels". 성공 시 Status=DONE, Message="ok"입니다.

6. DescribeAigcVideoTask

CreateAigcVideoTask로 생성한 비디오 태스크의 상태와 결과를 조회합니다.

6.1 Input Parameters

Parameter		Type	Description
TaskId	required	String	CreateAigcVideoTask에서 반환된 TaskId

6.2 Output Parameters

Parameter	Type	Description
Status	String	`WAIT` (대기) / `RUN` (처리 중) / `DONE` (성공) / `FAIL` (실패)
VideoUrls	Array of String	생성된 비디오 URL 목록. StoreCosParam 미지정 시 약 12시간 유효한 프리사인 COS URL
Resolution	String	실제 출력 해상도 (예: `1920x1088`)
Message	String	성공 시 `"ok"`, 실패 시 에러 메시지
RequestId	String	요청 ID

6.3 Response 예시

Response DescribeAigcVideoTask (DONE)

JSON

{
    "Response": {
        "Status": "DONE",
        "VideoUrls": [
            "https://aigc-output-video-***.cos.ap-guangzhou.myqcloud.com/.../2600012260-AigcVideo-***_0.mp4?q-sign-algorithm=sha1&q-ak=***&q-sign-time=***"
        ],
        "Resolution": "1920x1088",
        "Message": "ok",
        "RequestId": "7e6d5c4b-3a29-1807-f6e5-d4c3b2a10987"
    }
}

7. DescribeAigcAudioTask

CreateAigcAudioTask로 생성한 오디오 태스크의 상태와 결과를 조회합니다.

7.1 Input Parameters

Parameter		Type	Description
TaskId	required	String	CreateAigcAudioTask에서 반환된 TaskId

7.2 Output Parameters

Parameter	Type	Description
Status	String	`WAIT` (대기) / `RUN` (처리 중) / `DONE` (성공) / `FAIL` (실패)
AudioInfos	Array of Object	생성된 오디오 결과. 모델 측 스토리지를 통해 제공
VideoInfos	Array of Object	비디오 동반 결과 (해당 시)
Message	String	성공 시 `"ok"`, 실패 시 에러 메시지
RequestId	String	요청 ID

7.3 Response 예시

Response DescribeAigcAudioTask (DONE)

JSON

{
    "Response": {
        "Status": "DONE",
        "AudioInfos": [],
        "VideoInfos": [],
        "Message": "ok",
        "RequestId": "670f2706-b75d-4008-961e-2ec73f9d3a23"
    }
}

8. DescribeUsageData

MPS 미디어 처리 사용량을 일(day) 단위로 집계하여 조회합니다. AIGC를 포함한 작업 유형(TaskType)별로 묶이며, 지정한 구간(StartTime~EndTime)에 대해 반환됩니다. 실시간 모니터링용이 아니라 사용량·정산 집계용 API로, 응답의 시간 버킷은 하루 단위로 내려옵니다.

집계 단위 참고

StartTime / EndTime이 시각까지 받더라도 5분·1시간 단위로 잘라주지 않습니다. 응답의 Summary[].Time은 항상 하루 버킷의 시작 시각입니다. 최근 5분/25분 같은 실시간 사용량이 필요하면 작업 제출 시점을 별도로 기록하는 자체 집계가 필요합니다.

8.1 Input Parameters

Parameter		Type	Description
StartTime	required	String	조회 시작 시각. ISO 8601 형식 (예: `2026-06-01T00:00:00+09:00`). 조회 가능 범위는 최근 365일 이내
EndTime	required	String	조회 종료 시각. ISO 8601 형식. 한 번에 조회 가능한 최대 구간은 90일
Types	optional	Array of String	조회할 작업 유형. 생략 시 기본값 `Transcode`. AIGC는 `AIGCVideo` / `AIGCImage`로 분리됨 (아래 표 참고)
ProcessRegions	optional	Array of String	작업이 처리된 실제 리전 필터 (예: `["ap-seoul"]`). API 공통 파라미터 `Region`과는 별개

Region vs ProcessRegions

Region은 API 호출·서명에 쓰는 공통 파라미터이고, ProcessRegions는 MPS 작업이 실제로 처리된 리전을 거르는 필터입니다. 두 값을 동일하게 두면 데이터가 비어 보일 수 있으므로 구분해서 지정합니다.

8.2 Types — 작업 유형

생략 시 기본값은 Transcode입니다. AIGC 사용량은 최신 타입명 AIGCVideo / AIGCImage를 사용합니다.

Type	의미
Transcode	트랜스코딩
Enhance	화질/음질 향상
AIAnalysis	지능형 분석
AIRecognition	지능형 인식
AIReview	콘텐츠 심사
Snapshot	스냅샷
AnimatedGraphics	움짤(GIF) 변환
AiQualityControl	품질 검사
Evaluation	비디오 평가
ImageProcess	이미지 처리
AddBlindWatermark	기본 저작권 디지털 워터마크 추가
AddNagraWatermark	NAGRA 디지털 워터마크 추가
ExtractBlindWatermark	기본 저작권 디지털 워터마크 추출
AIGCVideo	AIGC 비디오 생성
AIGCImage	AIGC 이미지 생성

8.3 ProcessRegions — 처리 리전

값	리전	값	리전
ap-guangzhou	광저우	ap-bangkok	방콕
ap-hongkong	중국 홍콩	ap-tokyo	도쿄
ap-taipei	중국 타이베이	na-siliconvalley	실리콘밸리
ap-singapore	싱가포르	na-ashburn	버지니아
ap-mumbai	뭄바이	na-toronto	토론토
ap-jakarta	자카르타	sa-saopaulo	상파울루
ap-seoul	서울	eu-frankfurt	프랑크푸르트
eu-moscow	모스크바	aws	AWS

8.4 Output Parameters

Parameter	Type	Description
Data	Array of Object	작업 유형별 사용량 통계
Data[].TaskType	String	작업 유형 (예: `Transcode`, `AIGCVideo`, `AIGCImage`)
Data[].Summary	Array of Object	날짜별 요약 통계
Data[].Summary[].Time	String	해당 일자 버킷의 시작 시각
Data[].Summary[].Count	Integer	작업 건수
Data[].Summary[].Usage	Integer	사용량 (단위는 작업 유형별 상이 — 아래 표)
Data[].Details	Array of Object	스펙별 상세 통계
Data[].Details[].Specification	String	세부 과금/처리 스펙. 전통 미디어 처리는 `Standard.H265.4K` 형태, AIGC 작업은 `aigc-video.{ModelName}` / `aigc-image.{ModelName}` 형태(엔진 단위)
Data[].Details[].Data	Array of Object	해당 스펙의 날짜별 사용량 (`Time`/`Count`/`Usage`)
RequestId	String	요청 ID

8.5 Usage 단위

Usage의 단위는 작업 유형에 따라 다릅니다.

작업 유형	Usage 단위
Transcode / Enhance / AIAnalysis / AIRecognition / AIReview / AnimatedGraphics	초(sec)
Snapshot / ImageProcess	이미지 수
AIGCVideo	출력 영상 길이 기준 (초)
AIGCImage	생성 이미지 수 기준

8.6 호출 예시

서울 리전에서 AIGC 비디오/이미지 사용량을 조회하는 예시입니다.

CLI tccli (AIGC)

Shell

tccli mps DescribeUsageData \
  --endpoint mps.intl.tencentcloudapi.com \
  --region ap-seoul \
  --StartTime "2026-06-01T00:00:00+09:00" \
  --EndTime "2026-06-26T00:00:00+09:00" \
  --Types '["AIGCVideo","AIGCImage"]' \
  --ProcessRegions '["ap-seoul"]'

REQ Request Body

JSON

{
    "StartTime": "2026-06-01T00:00:00+09:00",
    "EndTime": "2026-06-26T00:00:00+09:00",
    "Types": ["AIGCVideo", "AIGCImage"],
    "ProcessRegions": ["ap-seoul"]
}

Types를 생략하면 기본 트랜스코딩 사용량을 조회합니다.

REQ Transcode (기본값)

JSON

{
    "StartTime": "2026-06-01T00:00:00+09:00",
    "EndTime": "2026-06-02T00:00:00+09:00",
    "ProcessRegions": ["ap-seoul"]
}

8.7 응답 예시

AIGC 비디오/이미지 응답 예시입니다. AIGC 작업의 Specification은 aigc-video.{ModelName} / aigc-image.{ModelName} 형태로, 엔진(모델) 단위로 집계됩니다. 모델 라인업이 늘어날 수 있으므로 고정 enum이 아니라 유연하게 파싱하는 것이 안전합니다.

Response AIGC

JSON

{
    "Response": {
        "Data": [
            {
                "TaskType": "AIGCVideo",
                "Summary": [
                    {"Time": "2026-06-25T00:00:00+09:00", "Count": 3, "Usage": 15}
                ],
                "Details": [
                    {
                        "Specification": "aigc-video.Kling",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+09:00", "Count": 3, "Usage": 15}
                        ]
                    }
                ]
            },
            {
                "TaskType": "AIGCImage",
                "Summary": [
                    {"Time": "2026-06-25T00:00:00+09:00", "Count": 8, "Usage": 8}
                ],
                "Details": [
                    {
                        "Specification": "aigc-image.Kling",
                        "Data": [
                            {"Time": "2026-06-25T00:00:00+09:00", "Count": 8, "Usage": 8}
                        ]
                    }
                ]
            }
        ],
        "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}

해석	의미
Summary	해당 TaskType의 일자별 합계(모든 엔진 합산). 위 예시에서 AIGCVideo 6/25은 Count 3 / Usage 15초
Details[].Specification	엔진(모델) 단위 식별자. `aigc-video.{ModelName}` / `aigc-image.{ModelName}`
Details[].Data[].Count	해당 엔진·해당 일자의 생성 건수 (비디오=영상 수, 이미지=이미지 수)
Details[].Data[].Usage	과금 사용량. 비디오=출력 영상 길이(초), 이미지=생성 이미지 장수
Time 형식	일 단위 버킷 시작 시각(ISO 8601, 위 예시는 `+09:00`). 빈 일자는 Count/Usage 0으로 채워짐

AIGC 작업의 Specification은 엔진(모델) 단위로 집계되며, 현재 관측되는 값은 다음과 같습니다.

AIGCImage Specification	AIGCVideo Specification
aigc-image.GEM	aigc-video.Kling
aigc-image.OG	aigc-video.PixVerse
aigc-image.Kling	aigc-video.VS
aigc-image.Seedream	aigc-video.Vidu
aigc-image.Hunyuan	aigc-video.GV
aigc-image.Qwen	aigc-video.Hailuo
aigc-image.Vidu	aigc-video.H2
aigc-image.MJ	aigc-video.Jimeng
aigc-image.Jimeng	aigc-video.OS
—	aigc-video.Hunyuan
—	aigc-video.Wan
—	aigc-video.Mingmou

8.8 운영 참고

항목	내용
집계 단위	일(day) 단위. 5분/1시간 단위 조회는 불가
최대 조회 구간	한 번에 90일
조회 가능 과거 범위	최근 365일
QPS	기본 100 requests/sec
과금 주기	Pay-As-You-Go 기본 일(day) 단위. 사용량 집계(이 API)와 실제 청구 주기는 별개
빈 응답	해당 기간 사용량 없음 / `Types` 불일치 / `ProcessRegions` 불일치 / 집계 미반영 시 `Data`가 비어 있을 수 있음
실시간 사용량	이 API만으로는 불가. 작업 제출 시점·TaskId·스펙을 자체 기록하는 별도 집계 필요

9. Polling Pattern (공통)

Image/Video 모두 비동기 방식입니다. Create 후 Describe를 반복 호출하여 결과를 확인합니다.

Python Polling Pattern

Python

import time, json
from tencentcloud.mps.v20190612 import mps_client, models

# ... client setup omitted (see above) ...

# After CreateAigcImageTask / CreateAigcVideoTask:
task_id = "your-task-id-here"

while True:
    # For Image:
    req = models.DescribeAigcImageTaskRequest()
    # For Video: req = models.DescribeAigcVideoTaskRequest()
    req.from_json_string(json.dumps({"TaskId": task_id}))
    resp = json.loads(client.DescribeAigcImageTask(req).to_json_string())
    # For Video: resp = json.loads(client.DescribeAigcVideoTask(req).to_json_string())

    status = resp.get("Status", "")

    if status == "DONE":
        # Success - extract URLs
        urls = resp.get("ImageUrls", [])      # For Video: resp.get("VideoUrls", [])
        print(f"Result: {urls[0]}")
        break
    elif status == "FAIL":
        raise RuntimeError(f"Task failed: {resp.get('Message')}")
    else:  # WAIT / RUN
        print(f"Status: {status} ...")
        time.sleep(6)

⚠

동시 실행 제한

모델 패밀리(Image/Video)별 동시 1 task 권장. 한도 초과 시 Create 호출 단계에서 RequestLimitExceeded 에러가 반환됩니다. 약 30초 후 재시도하면 정상 처리됩니다.

🎬 VOD(Video on Demand) 콘솔 최초 진입부터 애플리케이션 생성 · SubAppId 획득 · 트랜스코딩 · CDN(EdgeOne) 연동까지의 스텝바이스텝 온보딩 가이드입니다.

1. Overview

Tencent Cloud VOD(Video on Demand)는 영상 업로드 · 저장 · 트랜스코딩 · 가속 배포(CDN)를 제공하는 미디어 서비스입니다. 본 가이드는 콘솔에 처음 진입한 사용자가 다음 순서로 초기 설정을 완료하는 과정을 다룹니다.

VOD 서비스 활성화 (Activate)
서브 애플리케이션(Subapplication) 모드 활성화
애플리케이션 생성 및 SubAppId 획득
영상 업로드
간단한 트랜스코딩 실행
EdgeOne CDN 가속 도메인 연동

ℹ

사전 준비

Tencent Cloud 계정(인증 완료)과 콘솔 로그인이 필요합니다. 국제 버전(intl) 콘솔 기준으로 설명합니다.

2. Step 1 — VOD 서비스 활성화

콘솔 상단 메뉴에서 Products › Video Services › Video on Demand로 이동합니다. 최초 진입 시 서비스 활성화(Activate) 안내가 표시됩니다.

콘솔 우측 상단 검색창에 Video on Demand 입력 후 진입
Activate Now 버튼 클릭
약관 동의 후 활성화 완료 — 콘솔 대시보드로 전환됩니다

ℹ

기본 애플리케이션 APPID

활성화하면 계정 APPID와 동일한 기본 애플리케이션(Default App)이 자동 생성됩니다. APPID는 Account › Account Info에서 확인할 수 있습니다.

3. Step 2 — 서브 애플리케이션 모드 활성화

여러 비즈니스/환경을 격리하려면 서브 애플리케이션(Subapplication) 모드를 활성화합니다. 활성화 후 각 애플리케이션은 독립된 SubAppId로 리소스가 분리됩니다.

VOD 콘솔 좌측 메뉴에서 Application Management 진입
Activate Subapplication 클릭
안내 팝업에서 Use Now 선택
서브 애플리케이션 관리에 필요한 Admin Role(관리 역할) 권한 부여에 동의

4. Step 3 — 애플리케이션 생성 & SubAppId 획득

서브 애플리케이션 모드가 활성화되면 새 애플리케이션을 생성하고, 생성된 애플리케이션의 SubAppId를 확인합니다. 이후 모든 API 호출 시 이 SubAppId를 지정합니다.

Application Management 화면에서 Create Application 클릭
애플리케이션 이름(예: my-vod-app)과 설명 입력 후 생성
애플리케이션 목록에서 생성된 항목의 SubAppId(숫자)를 복사 — 콘솔에 노출됩니다

4.1 CLI로 생성/조회 (선택)

CLI CreateSubAppId / DescribeSubAppIds

Shell

# 서브 애플리케이션 생성
tccli vod CreateSubAppId \
  --region ap-seoul \
  --Name "my-vod-app" \
  --Description "Demo VOD application"

# 생성된 SubAppId 목록 조회
tccli vod DescribeSubAppIds --region ap-seoul

5. Step 4 — 영상 업로드

애플리케이션이 준비되면 영상을 업로드합니다. 콘솔에서 직접 업로드하거나, URL 풀(Pull) 업로드를 사용할 수 있습니다.

5.1 콘솔 업로드

대상 애플리케이션 선택 (좌측 상단 애플리케이션 전환 드롭다운)
Media Assets › Video Management 진입
Upload Video 클릭 → 로컬 파일 선택 → 업로드

5.2 URL Pull 업로드 (CLI)

CLI PullUpload

Shell

tccli vod PullUpload \
  --region ap-seoul \
  --SubAppId 1500000000 \
  --MediaUrl "https://example.com/sample.mp4" \
  --MediaName "sample-video"

6. Step 5 — 간단한 트랜스코딩

업로드한 영상을 표준 트랜스코딩 템플릿으로 변환합니다. 변환이 완료되면 각 출력 규격별 재생 URL을 얻을 수 있습니다.

업로드된 영상 항목에서 Process Video 클릭
Transcoding 탭 선택 후 트랜스코딩 템플릿 선택 (예: H.264 · 720P)
OK으로 작업 제출 → 상태가 Processing → Completed로 전환
완료 후 Manage → 트랜스코딩 출력의 재생 URL 복사

6.1 CLI 트랜스코딩 (선택)

CLI ProcessMedia

Shell

tccli vod ProcessMedia \
  --region ap-seoul \
  --SubAppId 1500000000 \
  --FileId "5285890799710174442" \
  --MediaProcessTask '{"TranscodeTaskSet":[{"Definition":100}]}'

ℹ

템플릿 ID(Definition)

Definition은 트랜스코딩 템플릿 ID입니다. 시스템 기본 템플릿 또는 Template Settings에서 만든 커스텀 템플릿 ID를 사용합니다.

7. Step 6 — EdgeOne CDN 가속 도메인 연동

기본 재생 도메인 대신 EdgeOne 가속 도메인을 연동하면 더 빠른 글로벌 배포가 가능합니다. EdgeOne에서 도메인을 추가한 뒤, VOD에 해당 도메인을 가져오는(import) 순서로 진행합니다.

7.1 EdgeOne에 도메인 추가

EdgeOne 콘솔 › Site List에서 대상 사이트 선택
Domain Name Service › Domain Management 진입
Add Domain 클릭 → 가속 도메인 입력
Origin(오리진) 타입을 Video on Demand (VOD)로 선택, 대상 VOD 애플리케이션 지정
발급된 CNAME 값을 도메인 DNS에 등록

7.2 VOD에 EdgeOne 도메인 가져오기

VOD 콘솔 › Distribution and Playback › Domain Name 진입
Add Domain → Import existing EdgeOne domain 선택
앞서 추가한 EdgeOne 도메인을 선택 후 가져오기
도메인 상태가 Deployed가 되면 재생 도메인으로 사용 가능

7.3 재생 인증(Key) 주의

⚠

토큰 인증 방식

EdgeOne 연동 도메인에서 VOD 재생 보호(Key Hotlink Protection)를 사용할 경우, VOD는 Type V 토큰 인증만 지원합니다. 재생 서명 생성 시 이 방식에 맞춰 URL을 발급하십시오.

8. References

문서	링크
VOD Getting Started	`www.tencentcloud.com/document/product/266/8757`
Subapplication System	`www.tencentcloud.com/document/product/266/33987`
Add Acceleration Domain	`www.tencentcloud.com/document/product/266/56731`
Using EdgeOne with VOD	`www.tencentcloud.com/document/product/266/66749`

⚙️ MPS(Media Processing Service) 콘솔 최초 진입부터 서비스 활성화 · 템플릿 준비 · 처음 트랜스코딩 작업 제출까지의 스텝바이스텝 온보딩 가이드입니다.

1. Overview

Tencent Cloud MPS(Media Processing Service)는 영상 트랜스코딩 · 화질강화 · 자막/음성 처리 · 미디어 AI 분석 등을 제공하는 미디어 처리 서비스입니다. VOD와 달리 오브젝트 스토리지(COS)를 입출력으로 사용하며, 다음 순서로 초기 설정을 진행합니다.

MPS 서비스 활성화 (Activate)
COS 버킷 준비 (입력/출력 스토리지)
트랜스코딩 템플릿 확인 / 커스텀 템플릿 생성
처음 트랜스코딩 작업 제출 (ProcessMedia)
작업 상태 조회 (DescribeTasks)

ℹ

사전 준비

Tencent Cloud 계정(인증 완료)과 콘솔 로그인, 그리고 COS 버킷이 필요합니다. 국제 콘솔(intl) 기준으로 설명하며, API 엔드포인트는 mps.intl.tencentcloudapi.com입니다.

2. Step 1 — MPS 서비스 활성화

콘솔 상단 검색창에서 Media Processing Service를 검색해 진입합니다. 최초 진입 시 활성화(Activate) 안내가 표시됩니다.

콘솔 메뉴에서 Media Services › Media Processing Service 진입
Activate Now 버튼 클릭 → 약관 동의
활성화 완료 후 MPS 콘솔 대시보드로 전환

3. Step 2 — COS 버킷 준비

MPS는 입력 미디어를 COS에서 읽고 처리 결과를 다시 COS로 출력합니다. 입력/출력용 버킷을 준비하십시오. (동일 버킷 내 경로를 나눠 사용해도 됩니다.)

COS 콘솔에서 버킷 생성 (MPS와 동일 리전 권장, 예: ap-seoul)
입력 미디어를 업로드하거나, 처리 시 InputInfo에 URL/COS 경로를 지정
MPS가 COS에 접근할 수 있도록 서비스 권한(Role) 승인

4. Step 3 — 트랜스코딩 템플릿 확인

MPS는 코덱 · 해상도 · 컨테이너 조합이 미리 정의된 프리셋(Preset) 템플릿을 제공합니다. 작업 제출 시 템플릿 ID(Definition)를 지정합니다. 대표 프리셋 템플릿은 다음과 같습니다.

Definition	Name	Container	설명
100010	STD-H264-MP4-360P	mp4	표준 H.264 · 360P
100020	STD-H264-MP4-540P	mp4	표준 H.264 · 540P
100030	STD-H264-MP4-720P	mp4	표준 H.264 · 720P
100040	STD-H264-MP4-1080P	mp4	표준 H.264 · 1080P
100070	STD-H264-MP4-1440P	mp4	표준 H.264 · 1440P (2K)
100080	STD-H264-MP4-2160P	mp4	표준 H.264 · 2160P (4K)
100210–100280	STD-H264-HLS-*	HLS	HLS 스트리밍 출력 (360P–2160P)
100800–100840	TSC-H264-MP4-*	mp4	Top Speed Codec 고압축 — 동일 화질을 유지하며 비트레이트 절감 (SAME/360P–1080P)
100910	image-quality-enhancement	mp4	화질 강화 프리셋
100920	2-times-super-resolution	mp4	2배 Super Resolution

4.1 CLI로 템플릿 조회

CLI DescribeTranscodeTemplates

Shell

tccli mps DescribeTranscodeTemplates \
  --region ap-seoul \
  --endpoint mps.intl.tencentcloudapi.com \
  --Type Preset \
  --Limit 20

ℹ

커스텀 템플릿

프리셋으로 부족한 경우 CreateTranscodeTemplate로 코덱/비트레이트/해상도를 직접 지정한 커스텀 템플릿을 만들 수 있습니다. 생성된 Definition을 이후 작업에 재사용하십시오.

5. Step 4 — 처음 트랜스코딩 작업 제출

핵심 API는 ProcessMedia입니다. 입력 미디어(InputInfo), 출력 스토리지(OutputStorage), 그리고 수행할 작업(MediaProcessTask)을 지정합니다.

CLI ProcessMedia

Shell

tccli mps ProcessMedia \
  --region ap-seoul \
  --endpoint mps.intl.tencentcloudapi.com \
  --InputInfo '{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/input.mp4"}}' \
  --OutputStorage '{"Type":"COS","CosOutputStorage":{"Bucket":"my-bucket-1250000000","Region":"ap-seoul"}}' \
  --OutputDir "/mps-output/" \
  --MediaProcessTask '{"TranscodeTaskSet":[{"Definition":100040}]}'

파라미터	설명
InputInfo	입력 미디어. `Type`=`URL` 또는 `COS`. COS일 때는 Bucket/Region/Object 지정
OutputStorage	출력 저장소. 일반적으로 `COS`
OutputDir	출력 경로 프리픽스 (예: `/mps-output/`)
MediaProcessTask.TranscodeTaskSet[].Definition	트랜스코딩 템플릿 ID (위 표 참조)

JSON Response

200

{
  "Response": {
    "TaskId": "2600012260-Procedure-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

6. Step 5 — 작업 상태 조회

제출된 작업은 비동기로 처리되며, DescribeTasks로 상태를 폴링하거나 DescribeTaskDetail로 단일 작업을 조회합니다.

CLI DescribeTasks

Shell

# 상태별 작업 목록 (Status 필수: WAITING / PROCESSING / FINISH)
tccli mps DescribeTasks \
  --region ap-seoul \
  --endpoint mps.intl.tencentcloudapi.com \
  --Status FINISH \
  --Limit 10

# 단일 작업 상세
tccli mps DescribeTaskDetail \
  --region ap-seoul \
  --endpoint mps.intl.tencentcloudapi.com \
  --TaskId "2600012260-Procedure-xxxxxxxxxxxxxxxx"

⚠

Status 파라미터 필수

DescribeTasks는 Status가 필수입니다. 생략 시 MissingParameter 에러가 반환됩니다. 값은 WAITING / PROCESSING / FINISH 중 하나입니다.

7. References

문서	링크
MPS ProcessMedia API	`www.tencentcloud.com/document/product/1041/33640`
MPS Preset Templates	`www.tencentcloud.com/document/product/1041/40222`
MPS Getting Started	`www.tencentcloud.com/document/product/1041/33684`

WAND Overview

Category	Count	Service	Core API
Transcoding	3	MPS	`ProcessMedia` · TranscodeTaskSet
Video AI	11	MPS	`ProcessMedia` (AI subtasks)
Audio	4	MPS	`ProcessMedia` · AudioEnhance
Image	11	MPS	`ProcessImage`
VOD Exclusive	4	VOD	SearchMedia / AIGC / Knowledge

ℹ

공통 호출 패턴

MPS 계열 기능은 대부분 ProcessMedia(영상/오디오) 또는 ProcessImage(이미지) 하나로 호출됩니다. 작업 종류는 프리셋 템플릿 ID(Definition) 또는 AI 오케스트레이션 스케줄 ID(ScheduleId)로 구분하며, 커스텀 규격은 OverrideParameter로 지정합니다. 모든 처리 작업은 비동기이며 TaskId를 반환하고, DescribeTaskDetail로 상태를 조회합니다.

ℹ

입력·출력

입력은 InputInfo.Type가 URL(공개 URL) 또는 COS(버킷 오브젝트). 출력은 OutputStorage(COS 버킷)+OutputDir로 지정하며, OutputObjectPath로 파일명 템플릿({inputName}·{definition} 등)을 쓸 수 있습니다.

General Transcode

ProcessMedia · TranscodeTaskSetMPS · Transcoding

코덱·해상도·비트레이트·컨테이너를 지정한 규격으로 재인코딩합니다. 포맷 호환 확보와 용량 절감이 주 목적입니다. 프리셋 템플릿(Definition)만으로 제출하거나, OverrideParameter로 개별 규격을 덮어쓸 수 있습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 소스. `Type`=`URL` 또는 `COS`
MediaProcessTask.TranscodeTaskSet[].Definition	Integer	required	트랜스코딩 템플릿 ID. 프리셋 예: `100040`=H.264 1080P MP4, `100030`=720P, `100020`=480P
...OverrideParameter	Object	optional	프리셋 위에 개별 규격(Container·VideoTemplate·AudioTemplate 등)을 덮어쓰기
OutputStorage / OutputDir	Object/String	required	출력 COS 버킷·경로
...OutputObjectPath	String	optional	출력 파일명 템플릿. 예: `/output/{inputName}_1080p.{format}`

ℹ

프리셋 vs 커스텀

프리셋 템플릿은 콘솔에서 미리 만들어 둔 규격 세트입니다. 임의 규격이 필요하면 프리셋 Definition을 베이스로 두고 OverrideParameter에 VideoTemplate.Codec(libx264/libx265/av1), Width/Height, Bitrate, Fps 등을 넣어 덮어씁니다.

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [
      {
        "Definition": 100040,
        "OverrideParameter": {
          "Container": "mp4",
          "VideoTemplate": { "Codec": "libx264", "Width": 1920, "Height": 1080, "Bitrate": 4000, "Fps": 30 },
          "AudioTemplate": { "Codec": "aac", "Bitrate": 128, "SampleRate": 44100 }
        }
      }
    ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

✓

작업 조회

반환된 TaskId를 DescribeTaskDetail에 넣어 Status(PROCESSING→FINISH)와 결과 파일 경로를 조회합니다.

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

TSC Transcode (Top Speed Codec)

ProcessMedia · TranscodeTaskSetMPS · Transcoding

TSC(Top Speed Codec)는 지각 품질을 유지하면서 비트레이트와 대역폭을 크게 낮추는 고압축 트랜스코딩입니다. 일반 트랜스코딩과 동일한 TranscodeTaskSet을 쓰되 Top Speed Codec 계열 템플릿 ID를 사용합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 소스
MediaProcessTask.TranscodeTaskSet[].Definition	Integer	required	Top Speed Codec 템플릿 ID. 범위 `100800–100840` (해상도·코덱 조합별)
...OverrideParameter.TEHDConfig	Object	optional	Top Speed Codec 세부(`Type`=`TEHD-100`/`TEHD-200`, 최대 비트레이트 상한 등)
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [ { "Definition": 100800 } ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

✓

절감 효과

동일 화질 기준 비트레이트를 크게 낮춰 CDN/스토리지 비용을 절감합니다. 원본 대비 실제 절감률은 콘텐츠 복잡도에 따라 달라집니다.

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

ProRes Codec

ProcessMedia · OverrideParameter.StdExtInfoMPS · Transcoding

Apple ProRes(10bit, yuv422p) 마스터급 코덱으로 트랜스코딩합니다. ProRes는 전용 프리셋 템플릿을 설치하는 방식이 아니라, 일반 트랜스코딩 템플릿을 베이스로 OverrideParameter.StdExtInfo에 ProRes 규격을 JSON 문자열로 넣어 지정합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

⚠

필수 조건

① OverrideParameter.StdExtInfo에 video_info.video_codec="prores"를 지정하고 ② 출력 컨테이너는 반드시 mov로 설정해야 합니다. mp4 등 다른 컨테이너로는 ProRes가 정상 출력되지 않습니다.

StdExtInfo 필드

Field	Value	Description
video_codec	`prores`	ProRes 코덱 지정
bit_depth	`10`	10비트 색심도
format	`yuv422p`	ProRes 표준 크로마 서브샘플링(4:2:2)
short	`1080`	짧은 변(세로) 기준 리사이즈 목표. 예: 1080 → 1080p 급

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [
      {
        "Definition": 100040,
        "OutputObjectPath": "/output/{inputName}_prores.mov",
        "OverrideParameter": {
          "Container": "mov",
          "StdExtInfo": "{\"video_info\":{\"video_codec\":\"prores\", \"bit_depth\":10, \"format\":\"yuv422p\",\"short\":1080}}"
        }
      }
    ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

✓

출력 검증

완료된 작업(DescribeTaskDetail)의 트랜스코딩 결과 Output.Container가 mov로 반환되어야 정상입니다.

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Video Enhancement

ProcessMedia · EnhanceMediaQualityMPS · Video AI

대형모델 기반 화질 복원·강화. 노이즈/블러 제거, 디테일·얼굴 복원, 저조도 개선, 손떨림 안정화 등을 수행합니다. 해상도 변경 없이 품질만 끌어올리거나, Super Resolution과 결합해 업스케일할 수 있습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상
MediaProcessTask.EnhanceMediaQualityTask.Definition	Integer	required	화질강화 템플릿 ID (실사/애니 계열별)
OutputStorage / OutputDir	Object/String	required	출력 위치

강화 템플릿(실사/애니/안정화)

Type	720P	1080P	2K	4K
실사(Real-person)	327001	327003	327005	327007
애니(Anime)	327002	327004	327006	327008
손떨림 안정화(Shake-opt)	327009	327010	327011	327012

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "EnhanceMediaQualityTask": { "Definition": 327003 }
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Super Resolution

ProcessMedia · EnhanceMediaQualityMPS · Video AI

저해상 영상을 720P/1080P/2K/4K로 업스케일합니다. 단순 확대가 아니라 대형모델이 디테일을 재생성하며, 실사·애니 계열별 전용 템플릿을 사용합니다. 화질 복원(Video Enhancement)과 동일한 EnhanceMediaQualityTask 오케스트레이션에서 목표 해상도 템플릿을 지정하는 방식입니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상(저해상)
MediaProcessTask.EnhanceMediaQualityTask.Definition	Integer	required	목표 해상도 템플릿. 실사 1080P=`327003`, 2K=`327005`, 4K=`327007`
OutputStorage / OutputDir	Object/String	required	출력 위치

목표 해상도 템플릿

Target	Real-person	Anime
720P	327001	327002
1080P	327003	327004
2K	327005	327006
4K	327007	327008

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "EnhanceMediaQualityTask": { "Definition": 327007 }
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

ℹ

선택 기준

원본 해상도는 유지하고 노이즈/디테일만 개선하려면 Video Enhancement, 해상도 자체를 키우려면 Super Resolution(더 높은 목표 템플릿)을 사용합니다.

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Subtitle / ASR

ProcessMedia · SmartSubtitlesMPS · Video AI

영상의 음성을 인식(ASR)해 SRT/VTT 자막을 생성합니다. 프리셋 인식 템플릿으로 언어를 지정합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상
MediaProcessTask.SmartSubtitlesTask.Definition	Integer	required	자막 템플릿. `10101`=중문 인식, `10102`=영문 인식
OutputStorage / OutputDir	Object/String	required	SRT/VTT 출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "SmartSubtitlesTask": { "Definition": 10102 }
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/40197

Subtitle Translate

ProcessMedia · SmartSubtitlesMPS · Video AI

음성 인식 결과를 다른 언어로 번역한 이중(원문+번역) 자막을 생성합니다. 인식+번역이 결합된 자막 템플릿을 사용합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상
MediaProcessTask.SmartSubtitlesTask.Definition	Integer	required	인식+번역 템플릿. 예: `10103`=중문 인식→중·영 이중 자막
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "SmartSubtitlesTask": { "Definition": 10103 }
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/40197

Dubbing / TTS

SyncDubbing / ProcessMediaMPS · Video AI

텍스트→음성(TTS) 합성, 음성 복제(voice clone), 또는 원음을 다른 목소리/언어로 교체(STS)합니다. 짧은 텍스트는 SyncDubbing으로 동기 합성하고, 긴 텍스트나 음성 교체는 비동기로 COS에 출력합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
SessionId	String	optional	중복 제출 방지용 세션 ID
VoiceId	String	optional	음성 복제로 얻은 음색 ID (없으면 프리셋 음색)
Text	String	required	합성할 텍스트(TTS 모드)
InputInfo	Object	optional	음성 교체(STS) 시 원본 오디오/영상

ℹ

워크플로

일반적으로 ① voice clone으로 VoiceId를 얻고 → ② TTS로 그 음색으로 합성합니다. 2000자 초과 텍스트는 자동으로 비동기 TTS로 전환됩니다.

요청 예시

JSON Request (SyncDubbing · TTS)

{
  "SessionId": "dub-0001",
  "VoiceId": "xxxxxxxxxxxxxxxx",
  "Text": "Hello, this is a synthesized voice sample."
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Watermark / Subtitle Erase

ProcessMedia · SmartEraseMPS · Video AI

화면 내 하드자막·워터마크·로고를 AI로 지우고 배경을 복원합니다. 영역 자동 검출 또는 지정 영역 처리를 지원합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상
MediaProcessTask.SmartEraseTask.Definition	Integer	required	제거 템플릿. `101`=자막 제거, `201`=워터마크 고급
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "SmartEraseTask": { "Definition": 101 }
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Content Understanding

VideoComprehension · AiAnalysisTaskMPS · Video AI

대형모델이 영상·음성 내용을 이해해 요약·장면 분석·QA를 텍스트로 반환합니다. 두 영상/오디오를 비교 분석하는 것도 가능합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상/오디오
AiAnalysisTask.Definition	Integer	required	분석 오케스트레이션 ID (내용 이해 = `33`)
...ExtendedParameter	String(JSON)	required	`mvc.mode`(summary/qa/scene 등)·`mvc.prompt`(자연어 지시)

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 33,
    "ExtendedParameter": "{\"mvc\":{\"mode\":\"summary\",\"prompt\":\"Summarize the key scenes\"}}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/862/126094

Media Quality Inspect

ProcessMedia · AiQualityControlTaskMPS · Video AI

블러·화면 깨짐·검은 테두리·프리즈/스터터·무음 등 품질 이상을 자동 검사하고, 품질 점수와 이상 구간을 리포트합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상
MediaProcessTask.AiQualityControlTask.Definition	Integer	required	품질 검사 템플릿 ID (검사 항목 세트별)
OutputStorage / OutputDir	Object/String	optional	리포트 출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "AiQualityControlTask": { "Definition": 40 }
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Video Remake

VideoRemake · AiAnalysisTask · Definition 29MPS · Video AI

원본 영상을 변형해 플랫폼 중복 검출을 회피하거나(중복 회피), 창의적으로 재편집합니다. 화면 속 화면(PicInPic), 화면 확장(Expand), 세로/가로 채우기 등 변형 모드를 ExtendedParameter.vremake로 지정합니다. 얼굴 교체·인물 교체·AB 교차 편집은 Face / Person Swap 페이지를 참고하십시오.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	원본 영상
AiAnalysisTask.Definition	Integer	required	`29` (Video Remake 오케스트레이션)
...ExtendedParameter.vremake.mode	String	required	변형 모드: `PicInPic`(화면 속 화면)·`Expand`(화면 확장)·수직/수평 채우기 등

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 29,
    "ExtendedParameter": "{\"vremake\":{\"mode\":\"PicInPic\"}}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/862/124394

Face / Person Swap

ProcessMedia · AiAnalysisTask · Definition 29MPS · Video AI

영상 속 인물의 얼굴을 교체(Face Swap)하거나 인물 전체를 교체(Person Swap)하고, 두 영상을 AB 교차 편집합니다. Video Remake와 동일하게 AiAnalysisTask.Definition=29를 사용하며, ExtendedParameter.vremake.mode로 모드를 지정합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

모드 (vremake.mode)

Mode	Description
SwapFace	영상 속 얼굴을 지정한 얼굴로 교체. 원본 얼굴(`srcFaces`)과 대체 얼굴(`dstFaces`)을 1:1로 매핑
SwapCharacter	인물 전체를 교체. 정면 전신 사진(`srcCharacter` → `character`) 필요
AB	두 영상을 AB 교차 편집. 랜덤 크롭/배속/미러링 등 변형 옵션 지원

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상(URL 또는 COS)
AiAnalysisTask.Definition	Integer	required	`29` (Video Remake 오케스트레이션)
...ExtendedParameter.vremake.mode	String	required	`SwapFace` / `SwapCharacter` / `AB`
...vremake.swapFace.srcFaces[]	Array	SwapFace	원본 영상 속 교체 대상 얼굴 이미지 URL 목록
...vremake.swapFace.dstFaces[]	Array	SwapFace	대체할 얼굴 이미지 URL 목록 (srcFaces와 1:1)
...vremake.swapCharacter.srcCharacter	String	SwapCharacter	원본 인물 정면 전신 사진 URL
...vremake.swapCharacter.character	String	SwapCharacter	대체할 인물 정면 전신 사진 URL
OutputStorage / OutputDir	Object/String	required	출력 COS 버킷·경로

⚠

입력 제약

SwapFace: 영상 해상도 ≤ 4K, 얼굴 이미지 1장 < 10MB(jpg/png), 얼굴 총 개수 ≤ 6. SwapCharacter: 영상 길이 ≤ 20분, 인물 사진은 정면 전신 컷.

요청 예시 — Face Swap

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 29,
    "ExtendedParameter": "{\"vremake\":{\"mode\":\"SwapFace\",\"swapFace\":{\"srcFaces\":[\"https://example.com/src.png\"],\"dstFaces\":[\"https://example.com/dst.jpg\"]}}}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

요청 예시 — Person Swap

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 29,
    "ExtendedParameter": "{\"vremake\":{\"mode\":\"SwapCharacter\",\"swapCharacter\":{\"srcCharacter\":\"https://example.com/src_fullbody.png\",\"character\":\"https://example.com/dst_fullbody.png\"}}}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

✓

작업 조회

ExtendedParameter는 vremake 객체를 JSON 문자열로 직렬화해 넣습니다(큰따옴표 이스케이프). 반환된 TaskId를 DescribeTaskDetail로 조회해 상태와 결과 영상을 확인합니다.

📎 Official docs: www.tencentcloud.com/document/product/862/124394

Auto Highlight

ProcessMedia · AiAnalysisTask · Definition 26MPS · Video AI

영상에서 하이라이트 구간을 자동 추출해 여러 클립 또는 하나로 병합한 릴로 만듭니다. 축구·농구 등 룰 기반 시나리오와, LLM 기반(force_cls 10020) 커스텀 모드를 모두 지원합니다. LLM 모드에서는 자연어 프롬프트로 "어떤 장면을 뽑을지" 지시할 수 있습니다. (참조: demo.tencentpoc.com/highlight)

Before / After

Before

Demo coming soon

After

Demo coming soon

기본 구조

AiAnalysisTask.Definition=26 + ExtendedParameter(JSON 문자열). 오프라인 처리의 최상위 키는 hht 하나입니다. force_cls(분석 시나리오/분류)로 룰 기반과 LLM 기반이 갈립니다.

force_cls (분석 시나리오)

force_cls	Type	Description
10020	LLM (custom / VLOG)	대형모델 범용 모드. `prompt`·`scenario`·`model_segment_limit` 사용 가능
10010	Short drama / TV / Film	드라마·TV·영화 — 주인공 등장/BGM 하이라이트
4001	Football	슛·골·카드·리플레이 인식 (근접 스코어보드 OCR: `football_close_ocr=1`)
4002	Basketball	농구 경기
1001	Honor of Kings	게임
100101	HoK Competition	게임 대회
1003	League of Legends	게임

hht 파라미터

Parameter	Type		Description
force_cls	Integer	required	분석 시나리오(위 표)
merge_type	Integer	required	출력 형태. `0`=여러 클립(`top_clip`개), `1`=하나로 병합(`merge_time`초)
need_vad	Integer	optional	VAD(음성 구간 감지)로 문장 경계 정렬. `1`=on, `0`=off
res_save_type	Integer	optional	`1`=클립 파일 저장, `0`=시간 구간만 반환(미디어 미출력)
top_clip	Integer	optional	(merge_type=0) 최대 클립 수 1~100
merge_time	Integer	optional	(merge_type=1) 병합 릴 목표 길이(초) 최대 3600
threshold	Float	optional	하이라이트 후보 최소 신뢰도 0~1. 높이면 엄격, 낮추면 느슨
scenario	String	optional	(10020 전용) 장면 카테고리 키워드. 예: `Skiing`, `Travel VLOG`
model_segment_limit	[min,max]	optional	(10020 전용) 클립 1개 길이 범위(초). 예: `[8,50]`
prompts.multimodal_prompt	String	optional	(10020 전용) LLM에 자연어로 추출 지시. 예: "주인공 클로즈업 위주로"
football_close_ocr	Integer	optional	(4001 전용) 근접 스코어보드 OCR `1`=on

요청 예시 — LLM 모드(10020, 커스텀)

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 26,
    "ExtendedParameter": "{\"hht\":{\"force_cls\":10020,\"merge_type\":0,\"need_vad\":1,\"res_save_type\":1,\"top_clip\":10,\"scenario\":\"Travel VLOG\",\"model_segment_limit\":[8,50],\"prompts\":{\"multimodal_prompt\":\"Extract scenic highlight moments\"}}}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

요청 예시 — 룰 기반(4001, 축구)

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 26,
    "ExtendedParameter": "{\"hht\":{\"force_cls\":4001,\"merge_type\":1,\"merge_time\":900,\"need_vad\":1,\"res_save_type\":1,\"football_close_ocr\":1}}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

⚠

ExtendedParameter는 JSON 문자열

hht 객체는 문자열로 직렬화해 ExtendedParameter에 넣습니다. 위 예시처럼 큰따옴표를 이스케이프해야 합니다.

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

AI Narration

ProcessMedia · AiAnalysisTask · Definition 35MPS · Video AI

드라마·숏폼을 AI가 요약·해설하는 나레이션 영상으로 자동 재편집합니다. 프리셋 시나리오(scene)를 선택하며, 커스텀 스크립트는 지원하지 않습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 영상(드라마/숏폼)
AiAnalysisTask.Definition	Integer	required	`35` (나레이션 오케스트레이션)
...ExtendedParameter	String(JSON)	required	프리셋 시나리오(`scene`) 지정

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "AiAnalysisTask": {
    "Definition": 35,
    "ExtendedParameter": "{\"scene\":\"short-drama\"}"
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Voice Denoising

ProcessMedia · AudioEnhanceMPS · Audio

배경 잡음을 제거해 음성을 또렷하게 만듭니다. AudioEnhance의 denoise 서브 설정을 켭니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 오디오/영상
MediaProcessTask.TranscodeTaskSet[].OverrideParameter.EnhanceConfig	Object	required	오디오 강화 설정(아래)
...EnhanceConfig.Denoise.Switch	String	required	`ON`/`OFF`
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [
      {
        "Definition": 100040,
        "OverrideParameter": {
          "Container": "mp3",
          "AudioTemplate": { "Codec": "mp3", "Bitrate": 128, "SampleRate": 44100 },
          "EnhanceConfig": { "Denoise": { "Switch": "ON" } }
        }
      }
    ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Audio Separation

ProcessMedia · AudioEnhanceMPS · Audio

음원에서 보컬·반주(배경음)를 분리 추출합니다. 트랙(보컬/배경)과 타입을 지정합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 오디오/영상
MediaProcessTask.TranscodeTaskSet[].OverrideParameter.EnhanceConfig	Object	required	오디오 강화 설정(아래)
...EnhanceConfig.AudioSeparate.Switch	String	required	`ON`/`OFF`
...AudioSeparate.Track	String	required	`vocal`(보컬) 또는 `background`(반주)
...AudioSeparate.Type	String	optional	`normal` / `music`
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [
      {
        "Definition": 100040,
        "OverrideParameter": {
          "Container": "mp3",
          "AudioTemplate": { "Codec": "mp3", "Bitrate": 128, "SampleRate": 44100 },
          "EnhanceConfig": { "AudioSeparate": { "Switch": "ON", "Track": "vocal", "Type": "music" } }
        }
      }
    ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Volume Balancing

ProcessMedia · AudioEnhanceMPS · Audio

구간별 음량 편차를 보정해 일정한 라우드니스로 맞춥니다. 표준화(loudNorm) 또는 게인 컨트롤을 선택합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 오디오/영상
MediaProcessTask.TranscodeTaskSet[].OverrideParameter.EnhanceConfig	Object	required	오디오 강화 설정(아래)
...EnhanceConfig.VolumeBalance.Switch	String	required	`ON`/`OFF`
...VolumeBalance.Type	String	optional	`loudNorm`(라우드니스 표준화) / `gainControl`
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [
      {
        "Definition": 100040,
        "OverrideParameter": {
          "Container": "mp3",
          "AudioTemplate": { "Codec": "mp3", "Bitrate": 128, "SampleRate": 44100 },
          "EnhanceConfig": { "VolumeBalance": { "Switch": "ON", "Type": "loudNorm" } }
        }
      }
    ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Audio Quality Enhancement

ProcessMedia · AudioEnhanceMPS · Audio

노이즈 제거 + 음량 균형 + 미화(declick/deesser)를 한 번에 적용하는 종합 음질 강화입니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 오디오/영상
MediaProcessTask.TranscodeTaskSet[].OverrideParameter.EnhanceConfig	Object	required	오디오 강화 설정(아래)
...EnhanceConfig.Denoise / VolumeBalance / ...	Object	required	여러 서브 강화를 동시에 ON
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.mp4" } },
  "MediaProcessTask": {
    "TranscodeTaskSet": [
      {
        "Definition": 100040,
        "OverrideParameter": {
          "Container": "mp3",
          "AudioTemplate": { "Codec": "mp3", "Bitrate": 128, "SampleRate": 44100 },
          "EnhanceConfig": { "Denoise": { "Switch": "ON" }, "VolumeBalance": { "Switch": "ON", "Type": "loudNorm" } }
        }
      }
    ]
  },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/33640

Virtual Try-On

ProcessImage · ScheduleId 30100MPS · Image

모델(인물) 이미지에 다른 의류를 입히는 AI 가상 피팅. 모델 + 의류 이미지가 필요합니다. 일반은 의류 1~2장, 속옷 시나리오(ScheduleId 30101)는 1장.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30100`
의류 이미지	Object	required	착용시킬 의류 이미지(추가 입력)
OutputStorage / OutputDir	Object/String	required	출력 위치

ℹ

두 장 필요

모델 이미지 + 의류 이미지를 모두 제공해야 동작합니다.

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30100,
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Change Model

ProcessImage · ScheduleId 30110MPS · Image

의류는 그대로 두고 착용 모델(체형/인물)만 교체합니다. 원본 + 의류 이미지가 필요합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30110`
의류 이미지	Object	required	유지할 의류 이미지
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30110,
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Background Fusion

ProcessImage · ScheduleId 30060MPS · Image

피사체에 새 배경을 합성하거나, 프롬프트로 배경을 생성합니다. 배경 이미지를 주거나 Prompt만으로 생성할 수 있습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30060`
배경 이미지	Object	optional	합성할 배경(생략 시 프롬프트 생성)
Prompt	String	optional	배경 생성 지시문
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30060,
  "Prompt": "modern studio background, soft lighting",
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

AI Cutout

ProcessImage · ScheduleId 30030MPS · Image

피사체를 정밀하게 분리해 배경이 투명한 PNG로 추출합니다. 투명도 임계값·엣지 샘플링을 조정할 수 있습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30030`
투명도/엣지 옵션	Object	optional	투명도 임계값, 엣지 샘플링 스텝
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30030,
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

AI Outpainting

ProcessImage · ScheduleId 30010MPS · Image

이미지 바깥 영역을 AI가 자연스럽게 그려 캔버스를 확장합니다. 목표 비율 또는 픽셀 크기를 지정합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30010`
AspectRatio / Width / Height	String/Int	required	목표 비율 또는 크기 중 최소 하나
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30010,
  "OutpaintingParam": { "AspectRatio": "16:9" },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Inpainting

ProcessImage · ScheduleId 30061MPS · Image

마스크로 지정한 영역만 프롬프트에 따라 다시 그립니다. 원본 + 마스크 + 프롬프트가 필요합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30061`
마스크 이미지	Object	required	재생성 영역 마스크
Prompt	String	required	재생성 지시문
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30061,
  "Prompt": "replace with a red sports car",
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Multi-View

ProcessImage · ScheduleId 30070MPS · Image

한 장의 이미지로 좌우/상하 다른 시점·원근의 컷을 생성합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30070`
시점/줌 옵션	Object	optional	수평/수직 각도, 줌 컨트롤
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30070,
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Grid Split

ProcessImage · ScheduleId 30050MPS · Image

여러 컷이 합쳐진 분할/그리드 이미지(만화 등)를 개별 컷으로 자동 분리합니다. 처리에 약 2분 소요됩니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30050`
텍스트 제거	String	optional	컷 내 텍스트 제거 여부
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30050,
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Object Detection

ProcessImage · ScheduleId 30080MPS · Image

이미지 속 객체를 검출·인식해 박스/설명을 반환합니다. 프롬프트 또는 포인트로 대상을 지정할 수 있습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30080`
Prompt	String	optional	찾을 대상(프롬프트 또는 포인트 중 하나 필요)
Point	Array	optional	좌표 지정 검출
OutputStorage / OutputDir	Object/String	required	출력 위치

ℹ

입력 필요

Prompt 또는 Point 중 최소 하나가 필요합니다.

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30080,
  "Prompt": "detect all cars",
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Image Understanding

ProcessImage · ScheduleId 30200MPS · Image

Gemini 계열 모델로 이미지 내용을 설명하거나 질의응답(VQA)합니다. 결과는 텍스트입니다. Prompt가 필수입니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ScheduleId	Integer	required	AI 오케스트레이션 ID = `30200`
Prompt	String	required	질문/지시문
OutputStorage / OutputDir	Object/String	required	출력 위치

ℹ

Prompt 필수

이미지 이해는 반드시 Prompt가 있어야 합니다.

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ScheduleId": 30200,
  "Prompt": "Describe this image in detail",
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Image Super-Res

ProcessImageMPS · Image

이미지를 2배 이상 Super Resolution 업스케일하고 노이즈 제거·디테일 강화를 적용합니다. ImageTask.EnhanceConfig.SuperResolution으로 지정합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
InputInfo	Object	required	입력 이미지
ImageTask.EnhanceConfig.SuperResolution.Switch	String	required	`ON`/`OFF`
...SuperResolution.Size	Integer	optional	업스케일 배수(예: 2, 4)
...SuperResolution.Type	String	optional	`lq`(저품질 원본)/`hq`
OutputStorage / OutputDir	Object/String	required	출력 위치

요청 예시

JSON Request

{
  "InputInfo": { "Type": "URL", "UrlInputInfo": { "Url": "https://example.com/input.jpg" } },
  "ImageTask": { "EnhanceConfig": { "SuperResolution": { "Switch": "ON", "Type": "lq", "Size": 2 } } },
  "OutputStorage": { "Type": "COS", "CosOutputStorage": { "Bucket": "your-bucket-125xxxxxxx", "Region": "ap-seoul" } },
  "OutputDir": "/output/"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "2600000000-WorkflowTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/1041/106357

Media Search

VOD · SearchMediaVOD · Exclusive

VOD 라이브러리에서 이름/태그/분류로 미디어를 검색하고 메타데이터·재생 주소를 조회합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
SubAppId	Integer	required	VOD 서브앱 ID
Text	String	optional	검색어(이름/설명)
Sort	Object	optional	정렬 필드·방향
Offset / Limit	Integer	optional	페이징

요청 예시

JSON Request

{
  "Action": "SearchMedia",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "Text": "keyword",
  "Sort": { "Field": "CreateTime", "Order": "Desc" },
  "Offset": 0, "Limit": 10
}

응답 예시

JSON Response

200

{
  "Response": {
    "TotalCount": 1,
    "MediaInfoSet": [
      {
        "FileId": "xxxxxxxxxxxxxxxxxxxx",
        "BasicInfo": { "Name": "sample", "Type": "mp4", "MediaUrl": "https://xxxxxxxxxx.vod2.myqcloud.com/xxx/xxx.mp4" }
      }
    ],
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/266/34179

AI Animation

VOD · CreateAigcVideoRedrawTaskVOD · Exclusive

실사 영상을 애니메이션/카툰 스타일로 AI 재생성(리드로우)합니다. 비동기 작업으로 TaskId를 반환합니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
SubAppId	Integer	required	VOD 서브앱 ID
FileId	String	required	리드로우할 VOD 파일 ID
스타일 옵션	Object	optional	애니메이션 스타일 파라미터

요청 예시

JSON Request

{
  "Action": "CreateAigcVideoRedrawTask",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "FileId": "xxxxxxxxxxxxxxxxxxxx"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "vod-redraw-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/266/115841

AI Character Register

VOD · CreateAigcAdvancedCustomElementVOD · Exclusive

참조 이미지/영상으로 일관된 외형의 AI 캐릭터(주체)를 등록합니다. 이후 AIGC 생성에서 재사용할 수 있습니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
SubAppId	Integer	required	VOD 서브앱 ID
참조 이미지/영상	Object	required	캐릭터 학습용 참조 자료

요청 예시

JSON Request

{
  "Action": "CreateAigcAdvancedCustomElement",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "FileId": "xxxxxxxxxxxxxxxxxxxx"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "vod-element-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/266/115841

Semantic Search

VOD · ImportMediaKnowledgeVOD · Exclusive

미디어를 지식베이스에 색인(임베딩)해 두면, 자연어로 내용 기반 의미 검색이 가능해집니다.

Before / After

Before

Demo coming soon

After

Demo coming soon

Parameters

Parameter	Type		Description
SubAppId	Integer	required	VOD 서브앱 ID
FileId	String	required	색인할 VOD 파일 ID

요청 예시

JSON Request

{
  "Action": "ImportMediaKnowledge",
  "Version": "2018-07-17",
  "SubAppId": 1500000000,
  "FileId": "xxxxxxxxxxxxxxxxxxxx"
}

응답 예시

JSON Response

200

{
  "Response": {
    "TaskId": "vod-knowledge-xxxxxxxxxxxxxxxx",
    "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

📎 Official docs: www.tencentcloud.com/document/product/266/110323

🧩 Skill을 연동하면 콘솔 접속이나 API 직접 연동 없이, Claude Code · WorkBuddy 같은 Agent Tool에 자연어로 작업을 지시해 Tencent Cloud의 미디어·AIGC 기능을 실행할 수 있습니다. 이 페이지는 그 연동 개념과 실제 적용 흐름을 정리합니다.

1. Overview

Tencent Cloud는 자체 파운데이션 모델을 전면에 내세우기보다, 전 세계의 멀티모달 AI를 통합 제공하고 여기에 미디어·클라우드 기술을 결합해 하나의 생태계로 묶는 방향을 지향합니다. Skill은 이 여러 제품(TokenHub · WAND · VOD MaaS · WorkBuddy)을 하나의 작업 흐름으로 연결하는 접점입니다.

PaaS 기반 미디어·AIGC 제품은 콘솔에서 기능을 제공하더라도, 실제 연동 단계에서 API 호출 · 비동기 작업 조회 · 결과 확인이라는 부담이 남습니다. Skill은 이 절차를 하나의 "사용 레시피"로 패키징해, Agent Tool이 참고하여 대신 수행하도록 만듭니다.

ℹ

여기서의 "학습"은 파인튜닝이 아닙니다

Skill 연동은 모델 파인튜닝이 아니라, Skill 패키지 안의 지침 · API 호출 방식 · SDK 예제 · 결과 조회 절차를 Agent Tool이 참고하도록 연결하는 방식입니다.

2. Skill이란

Skill은 제품 사용 레시피에 가까운 개념입니다. 제품팀이 공식 제공하는 파일이며, 일반적으로 SKILL.md와 관련 API·SDK 코드, 파라미터 설명, 실행 절차가 함께 압축 파일 형태로 배포됩니다.

사용자는 이 파일을 다운로드해 Claude Code나 WorkBuddy에 읽히기만 하면 됩니다. Skill을 적용하면 콘솔 접속이나 별도 API 연동 없이 주요 기능을 자연어 작업 명령으로 실행할 수 있어, 특히 빠른 PoC 단계에서 효과가 큽니다.

구성 요소	설명
SKILL.md	기능 개요와 사용 지침, 언제 어떤 절차를 따를지 정의
API · SDK 예제	호출 방식, 요청/응답 구조, 언어별 코드 스니펫
파라미터 설명	모델·해상도·옵션 등 입력 파라미터 레퍼런스
실행 절차	작업 생성 → 비동기 조회 → 결과 확인까지의 흐름

3. Skill Marketplace

Skill은 대표적으로 Knot와 SkillHub에서 제공됩니다. 내부망인 Knot에서 최신 버전이 먼저 올라오는 경우가 많으므로, 내부 검토나 PoC 준비 단계에서는 Knot에서 다운로드하는 것을 권장합니다.

채널	설명
Knot	최신 Skill이 먼저 제공되는 내부 마켓플레이스 — `knot.woa.com/skills/detail/24233`
SkillHub	Skill 커뮤니티 마켓플레이스

WAND Skill Marketplace — WAND Skill이 제공되는 Marketplace 화면

4. Agent Tool 연동

Skill이 적용된 Agent Tool은 별도의 API 연동이나 콘솔 접속 없이 자연어 작업을 수행합니다. 예를 들어 다음과 같은 요청을 그대로 처리할 수 있습니다.

"Kling 3.0으로 10초짜리 영상을 만들고, 4K로 업스케일링해 주세요"
"내 컴퓨터의 /downloads/EPL.mp4 경기 영상을 2분짜리 하이라이트로 뽑아 주세요"

💡

모델 비용과의 연결

Agent Tool이 이미 작업 레시피(Skill)를 확보하고 있으면, 모든 판단 단계에 고가 토큰 모델을 쓸 필요가 줄어듭니다. Skill에 정의된 절차를 참고해 실행하므로 일부 단계는 더 저렴한 모델로도 동일한 결과를 기대할 수 있으며, 이는 TokenHub 활용 포인트와도 연결됩니다.

5. Claude Code

Knot에서 다운로드한 Skill을 Claude Code에 적용합니다. 이때 Claude Code의 /model 설정에서 Tencent Cloud가 제공하는 Text TokenHub 엔드포인트를 사용하면 토큰 비용을 추가로 절감할 수 있습니다.

Skill을 적용한 Claude Code에 영상 업스케일링 작업을 요청하면, 콘솔에 들어가거나 API 호출 구조를 직접 이해할 필요 없이 자연어 한 줄로 작업을 시작하고 결과를 받을 수 있습니다.

Claude Code에 Skill 적용 — Claude Code에 WAND Skill을 적용한 뒤 자연어로 작업을 지시하는 예시

Claude Code 업스케일 실행 — 콘솔 접속 없이 Agent Tool에서 업스케일링 작업을 실행하는 흐름

5.1 결과물

Video Enhancement 결과를 Before / After로 확인한 화면

6. WorkBuddy

WorkBuddy에서의 Skill 연동은 더 간단합니다. Marketplace에서 다운로드한 WAND Skill을 바로 적용하면 됩니다. 사용 레시피를 읽은 WorkBuddy에 자연어로 작업을 지시하면, 필요한 API 호출과 비동기 작업 조회를 Agent가 대신 처리합니다.

WorkBuddy Skill 적용 — WorkBuddy에서 WAND Skill을 적용하는 화면

WorkBuddy 작업 결과 — WorkBuddy가 작업을 수행하고 결과를 제공하는 화면

Text 모델을 Claude로 쓰든 DeepSeek 계열로 쓰든 작업 결과는 동일하게 설계할 수 있습니다. 작업 절차의 핵심은 모델 자체가 아니라 Skill에 정의된 레시피에 있기 때문입니다.

7. Before / After

Kling 3.0으로 영상을 생성한 뒤 4K로 후처리하는 작업을 예로 들면, 연동 방식에 따라 절차가 크게 달라집니다. (Tencent Cloud 계정 개통과 API Key 발급은 공통 전제)

Before — 직접 API 연동

1. Tencent Cloud SDK로 호출 환경 구현
2. CreateAigcVideoTask — Kling 3.0 영상 생성
3. DescribeAigcVideoTask — 생성 결과 폴링
4. ProcessMedia — 4K 업스케일 / Enhancement
5. DescribeTaskDetail — 처리 결과 폴링

After — Skill 연동

1. Claude Code / WorkBuddy에 Skill 적용
2. "Kling 3.0으로 영상 생성 후 4K로 업스케일링해 주세요" 자연어 지시
3. Agent가 API 호출·비동기 조회·결과 확인 절차를 대신 수행

✅

정리

Skill은 Tencent Cloud AI 제품을 실제 작업 환경 안으로 가져오는 실행 레이어입니다. Skill을 함께 제안하면 사용자는 콘솔 가이드나 API 문서를 처음부터 따라가지 않아도, 파일 하나로 PoC 효과를 빠르게 확인하고 TokenHub · WAND · VOD MaaS · WorkBuddy를 자연스럽게 연결할 수 있습니다.

AIGC Product Guide

Text Generation

Image Generation

Video Generation

Music Generation

3D Generation

MPS AIGC

VOD Integration

1. Text Generation Overview

1.1 Step 1 — Token 발급

1.2 Step 2 — Endpoint 선택

1.3 Step 3 — Headers 준비

1.4 Step 4 — 첫 호출

2. API 정보

3. 인증 & Token 관리

3.1 CreateAigcApiToken

Request Parameters

Response Parameters

3.2 DescribeAigcApiTokens

Request Parameters

Response Parameters

3.3 DeleteAigcApiToken

Request Parameters

3.4 서브계정 권한 설정 (CAM)

정책 1: 모든 SubAppId에 대한 권한

정책 2: 특정 SubAppId에 대한 권한

4. AIGC Quota 관리

개요

공통 규약

QuotaType 차원

운영 가이드 — 실전 시나리오

4.1 DescribeAigcQuotas

Request Parameters

4.2 CreateAigcQuota

Request Parameters

4.3 ModifyAigcQuota

Request Parameters

4.4 DeleteAigcQuota

Request Parameters

4.5 한도 초과 시 LLM 응답

4.6 누적 · 리셋 · over-shoot 주의사항

관련 에러 코드

4.7 Python raw signed POST 예제

FAQ

5. Request 작성 가이드

5.1 Request Headers

5.2 프로토콜 매트릭스

어떤 프로토콜을 골라야 하나?

5.3 지원 모델

모델 스펙 · 호출 정책

B. 모델 스펙 (5~9번)

C. 호출 정책 (10~12번)

5.4 Request Parameters (OpenAI Completions)

messages 배열 내 객체 구조

Part 객체 구조

ExtraContent 구조 (Gemini 전용)

6. 호출 예시

6.1 OpenAI Completions

cURL 예시

OpenAI SDK 예시

6.2 Anthropic Messages

cURL 예시

Anthropic SDK 예시

6.3 Responses API

cURL 예시

OpenAI SDK 예시

7. Response 처리

7.1 Response Parameters

7.2 Error Codes

7.3 사용량 조회 — DescribeAigcUsageData

Request Parameters

Response Parameters

8. 과금 안내

9. 실천 튜토리얼

9.1 Claude Code 연동

사전 준비

설치

설정: settings.json

Onboarding 스킵

실행 및 확인