Image Generation

텍스트 프롬프트 또는 레퍼런스 이미지로 이미지를 생성하는 비동기 태스크 API입니다. Hunyuan, GEM, Qwen, Vidu, Kling, OG, Seedream, MJ 엔진을 지원하며 text-to-image, image-to-image, 3D 파노라마 이미지 생성이 가능합니다. 태스크 제출 후 반환된 TaskId로 결과를 폴링합니다.

API 정보

항목	값
Action	`CreateAigcImageTask`
결과 조회	`DescribeAigcImageTask`
엔드포인트	`mps.intl.tencentcloudapi.com` (국제) / `mps.tencentcloudapi.com` (중국 본토)
인증 방식	TC3-HMAC-SHA256 서명 (SecretId/SecretKey)
기본 리전	`ap-guangzhou`

지원 엔진

레퍼런스 이미지 상한은 모델과 버전 조합으로 결정되며, 모델과 무관하게 플랫폼 공통 상한 20장이 먼저 적용됩니다.

엔진	버전	레퍼런스 이미지 상한	비고
Hunyuan	`3.0` (기본), `3d_2.0` (`SceneType=3d_panorama`)	3	기본 모델
GEM	`2.5` / `3.0` / `3.1`	20	플랫폼 상한까지 허용
Qwen	`0925`	9
Vidu	`q2`	7
Kling	`2.1` / `3.0`	4	버전별 상한이 다르므로 주의
Kling	`O1` / `3.0-Omni`	10
OG	`image2_low` / `image2_medium` / `image2_high`	20	`OutputImageCount` 다중 출력 검증됨
Seedream	`4.5` / `5.0-lite` / `5.0-pro`	20
MJ	`v7` / `v8.1` / `v8.2`	3	요청당 항상 4장 반환

공통 스펙: 해상도 720P / 1080P / 2K / 4K, 화면 비율 1:1 / 3:2 / 2:3 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9, 출력 포맷 jpeg / png.

요청 파라미터

파라미터	타입	필수 여부	예시	설명
`ModelName`	String	선택	`GEM`	생성 엔진. 기본값 `Hunyuan`
`ModelVersion`	String	선택	`3.1`	엔진별 버전. 미지정 시 기본 버전 적용
`Prompt`	String	조건부 필수	`cyberpunk city night scene`	이미지 설명. 최대 1000자. 레퍼런스 이미지가 없으면 필수
`NegativePrompt`	String	선택	`people`	네거티브 프롬프트
`EnhancePrompt`	Boolean	선택	`true`	프롬프트 보강 활성화
`SceneType`	String	선택	`3d_panorama`	Hunyuan 전용 씬 타입. 지정 시 `ModelVersion=3d_2.0` 자동 적용
`ReferenceImageInfos.N`	Array	선택	`ImageUrl` + `RefType`	레퍼런스 이미지. `ImageUrl`만 지원 (COS 직접 지정 불가). `RefType`은 `asset`(콘텐츠 참조) / `style`(스타일 참조)
`AdditionalParameters`	String	선택	`{"cfg_scale":7}`	모델별 확장 파라미터. JSON 문자열로 전달
`AspectRatio`	String	선택	`16:9`	출력 화면 비율
`Resolution`	String	선택	`2K`	출력 해상도
`OutputImageCount`	Integer	선택	`4`	출력 장수. 기본값 1. OG 등 일부 모델만 적용되고 GEM/Hunyuan은 무시
`OutputFormat`	String	선택	`png`	출력 포맷 `jpeg` / `png`
결과 저장소 설정	Object	선택	COS Bucket/Region/Path	결과를 저장할 COS. 미설정 시 MPS 임시 저장소에 12시간 보관

응답 및 결과 조회

제출이 성공하면 TaskId가 즉시 반환됩니다. 이후 DescribeAigcImageTask에 TaskId를 전달해 상태를 폴링합니다.

CreateAigcImageTask 호출, 응답에서 TaskId 확보
DescribeAigcImageTask를 5초 간격으로 폴링
Status가 DONE이면 ImageInfos[].Url에서 결과 URL 확인. FAIL이면 Message에서 원인 확인

Status 값은 WAIT / RUN / DONE / FAIL입니다. 레퍼런스 이미지 상한 초과처럼 모델 단에서 검증되는 오류는 제출 시점에는 TaskId가 정상 발급되고 실행 단계에서 FAIL로 전환되므로, 제출 성공만으로 파라미터 유효성을 판단해서는 안 됩니다.

호출 예시

MPS API는 TC3-HMAC-SHA256 서명이 필요합니다. 아래 Authorization 헤더의 서명 부분은 SecretId/SecretKey로 계산한 값으로 대체해야 합니다.

Text-to-Image (GEM)
Image-to-Image
3D 파노라마 (Hunyuan)

curl -X POST https://mps.intl.tencentcloudapi.com/ \
  -H "Authorization: TC3-HMAC-SHA256 Credential=${SECRET_ID}/${DATE}/mps/tc3_request, SignedHeaders=content-type;host, Signature=${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -H "X-TC-Action: CreateAigcImageTask" \
  -H "X-TC-Version: 2018-07-17" \
  -H "X-TC-Timestamp: ${TIMESTAMP}" \
  -H "X-TC-Region: ap-guangzhou" \
  -d '{
    "ModelName": "GEM",
    "ModelVersion": "3.1",
    "Prompt": "cyberpunk city night scene",
    "NegativePrompt": "people",
    "AspectRatio": "16:9",
    "Resolution": "2K"
  }'

curl -X POST https://mps.intl.tencentcloudapi.com/ \
  -H "Authorization: TC3-HMAC-SHA256 Credential=${SECRET_ID}/${DATE}/mps/tc3_request, SignedHeaders=content-type;host, Signature=${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -H "X-TC-Action: CreateAigcImageTask" \
  -H "X-TC-Version: 2018-07-17" \
  -H "X-TC-Timestamp: ${TIMESTAMP}" \
  -H "X-TC-Region: ap-guangzhou" \
  -d '{
    "ModelName": "GEM",
    "ModelVersion": "3.0",
    "Prompt": "blend these elements",
    "ReferenceImageInfos": [
      {"ImageUrl": "https://example.com/img1.jpg", "RefType": "asset"},
      {"ImageUrl": "https://example.com/img2.jpg", "RefType": "style"}
    ]
  }'

curl -X POST https://mps.intl.tencentcloudapi.com/ \
  -H "Authorization: TC3-HMAC-SHA256 Credential=${SECRET_ID}/${DATE}/mps/tc3_request, SignedHeaders=content-type;host, Signature=${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -H "X-TC-Action: CreateAigcImageTask" \
  -H "X-TC-Version: 2018-07-17" \
  -H "X-TC-Timestamp: ${TIMESTAMP}" \
  -H "X-TC-Region: ap-guangzhou" \
  -d '{
    "ModelName": "Hunyuan",
    "SceneType": "3d_panorama",
    "Prompt": "tropical rainforest panorama"
  }'

응답 예시

태스크 제출 응답:

{
  "Response": {
    "TaskId": "abc123def456-aigc-image-20260328112000",
    "RequestId": "12ae8d8e-dce3-4151-9d4b-5594145287e1"
  }
}

결과 조회 응답 (DescribeAigcImageTask):

{
  "Response": {
    "TaskId": "abc123def456-aigc-image-20260328112000",
    "Status": "DONE",
    "Message": "",
    "ImageInfos": [
      {
        "Url": "https://aigc-output-1250000000.cos.ap-guangzhou.myqcloud.com/output/aigc-image/result_0.png?q-sign-algorithm=..."
      }
    ],
    "RequestId": "22bf9e9f-edf4-5262-0e5c-6605256398f2"
  }
}

주의사항

결과 이미지는 기본적으로 MPS 임시 저장소에 12시간만 보관됩니다. COS 결과 저장소를 설정하지 않았다면 완료 즉시 다운로드해야 합니다.

레퍼런스 이미지 개수가 모델 상한을 초과해도 제출 단계에서는 TaskId가 정상 반환되고 실행 중 FAIL로 실패합니다. 상한은 모델과 버전 조합으로 결정되며, 플랫폼 공통 상한 20장을 넘으면 제출 단계에서 InvalidParameterValue로 거부됩니다.

MJ 엔진은 요청당 항상 4장을 반환하며 OutputImageCount로 변경할 수 없습니다. Resolution과 AspectRatio를 지원하지 않으므로 프롬프트 파라미터(--ar 16:9 등)로 제어해야 합니다. 레퍼런스 이미지는 사전 서명 정보가 없는 순수 공개 URL만 허용되며, niji 버전은 비활성 상태입니다.

레퍼런스 이미지는 ImageUrl 형식만 지원합니다. COS에 있는 이미지는 사전 서명 URL을 생성해 전달해야 하며, MJ에는 사전 서명 URL을 사용할 수 없습니다. Kling에 너무 작은 레퍼런스 이미지(예: 256x256)를 전달하면 Image pixel is invalid 오류가 발생하므로 1024x1024 이상을 권장합니다.

가격표에 표시된 Wan 2.2는 아직 API에서 지원하지 않으며 호출 시 Not support model name 오류가 반환됩니다.

Getting Started

WAND AIGC

MPS Features

TokenHub

Appendix

API 정보

지원 엔진

요청 파라미터

응답 및 결과 조회

호출 예시

응답 예시

주의사항

​API 정보

​지원 엔진

​요청 파라미터

​응답 및 결과 조회

​호출 예시

​응답 예시

​주의사항

API 정보

지원 엔진

요청 파라미터

응답 및 결과 조회

호출 예시

응답 예시

주의사항