VOD APILast Updated 2026-09-05 19:22:10

Image2

On this page

Endpoint: POST https://vod.intl.tencentcloudapi.com
Action: CreateAigcImageTask

기본 정보

항목	값
ModelName	`OG`
ModelVersion	`image2_` / `image2.5_sunburst_` / `image2.5_flare_*`
기본값	`ModelVersion=image2_medium` / `AspectRatio=1:1`
가드레일 해제 지원	미지원

버전별 지원 규격

버전	출력 규격	입력 및 조건
공통	해상도: `1K` / `2K` / `4K`; 커스텀 크기는 아래 픽셀 제약 적용 비율: `1:1` / `3:2` / `2:3` / `3:4` / `4:3` / `16:9` / `9:16` / `21:9` / `9:21` image2.5: sunburst / flare 각각 low, medium, high, xhigh, max	참조 이미지: 최대 `16장`

2.0 계열(image2_*)과 2.5 계열(image2.5_sunburst_* / image2.5_flare_*)을 같은 ModelName으로 호출합니다. 액션 CreateAigcImageTask, 결과는 DescribeTaskDetail로 조회합니다.

요청 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	고정값 `OG`
`ModelVersion`	선택	String	모델 버전. 생략하면 엔진 기본값
`Prompt`	필수	String	생성 프롬프트
`FileInfos.N`	선택	Array	참조 이미지(image-to-image). `Category`는 `Image`
`OutputConfig.AspectRatio`	선택	String	`1:1` / `16:9` / `9:16` / `4:3` / `3:4` 등
`OutputConfig.OutputImageCount`	선택	Integer	생성 장수 (모델별 상한 상이)
`ExtInfo`	선택	String	모델 전용 옵션을 담은 JSON 문자열. 커스텀 사이즈 `{"size":"2048x2048"}`, 투명 배경 `{"background":"transparent"}`. 제약은 아래 `커스텀 해상도 (size)` 참조

요청 예시

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_sunburst_medium",
  "Prompt": "a serene japanese garden, soft morning light",
  "OutputConfig": {
    "AspectRatio": "1:1",
    "OutputImageCount": 1,
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

응답 예시

LANGUAGE
{
  "AigcImageTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Progress": 100,
    "Output": {
      "FileInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcImageGenFile.png",
          "ExpireTime": "2026-08-01T10:29:48Z",
          "MetaData": {
            "Width": 1024,
            "Height": 1024,
            "Container": "png"
          }
        }
      ]
    }
  }
}

특수 설정

모델 버전

2.5 계열의 ModelVersion은 image2.5_{계열}_{단계} 형식입니다. 계열은 sunburst와 flare 두 가지이고, 단계는 다섯 단계입니다.

단계	sunburst	flare
`low`	`image2.5_sunburst_low`	`image2.5_flare_low`
`medium`	`image2.5_sunburst_medium`	`image2.5_flare_medium`
`high`	`image2.5_sunburst_high`	`image2.5_flare_high`
`xhigh`	`image2.5_sunburst_xhigh`	`image2.5_flare_xhigh`
`max`	`image2.5_sunburst_max`	`image2.5_flare_max`

2.0 계열은 image2_low / image2_medium / image2_high를 그대로 사용합니다.

품질 모드

ModelVersion으로 품질 단계를 고릅니다. 단계가 올라갈수록 정밀도가 높아지고 생성 시간이 길어집니다.

ModelVersion 단계	특징	권장 용도
`low`	가장 빠르게 생성	빠른 초안, 대량 테스트, 프롬프트 반복
`medium`	속도와 화질의 균형	일반적인 실사용, 범용 디자인
`high`	디테일과 질감, 빛과 그림자 표현 강화	검토용 결과물, 상세 표현이 필요한 이미지
`xhigh`	`high`보다 높은 정밀도	최종 검토, 확대 사용
`max`	최고 정밀도. 복잡한 텍스트와 작은 글자에 강함	최종 결과물, 인쇄물, 고정밀 제품 이미지

계열별 생성 시간

같은 프롬프트와 1024x1024 기준으로 측정한 값입니다. 네트워크 상태와 서버 부하에 따라 달라집니다.

계열	`low`	`medium`	`high`	`xhigh`	`max`
`sunburst`	`30초`	`30초`	`53초`	`92초`	`169초`
`flare`	`22초`	`22초`	`35초`	`41초`	`61초`

다중 이미지 참조

한 번의 요청에 여러 장의 참조 이미지를 넣을 수 있습니다. 이미지 편집, 스타일 이전, 다중 이미지 융합에 사용합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_sunburst_medium",
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://<cos>/room.png"
    },
    {
      "Type": "Url",
      "Url": "https://<cos>/fabric.jpg"
    }
  ],
  "Prompt": "redesign this room with the material palette of the second image, keep the layout unchanged",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16"
  },
  "SessionContext": "job-001"
}

여러 장 출력 (OutputImageCount)

OutputConfig.OutputImageCount로 한 번에 만들 이미지 수를 지정합니다. OG는 1~8장입니다.

LANGUAGE
{
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16",
    "OutputImageCount": 3
  }
}

엔진별로 출력 가능한 장수가 다릅니다

OutputImageCount 허용 범위는 엔진마다 다릅니다. Kling은 1~9장, OG는 1~8장입니다.

커스텀 해상도 (size)

ExtInfo의 size로 출력 해상도를 직접 지정합니다.

조건	값
가로세로	각각 `16`의 배수
최대 한 변	`3840px` 이하
총 픽셀 수	`655,360 ~ 8,294,400`

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_flare_high",
  "Prompt": "a serene Japanese garden, soft morning light",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1K",
    "AspectRatio": "9:16"
  },
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\": \\\"2000x1104\\\"}\"}",
  "SessionContext": "job-001"
}

auto 모드

size에 auto를 넣으면 모델이 입력에 맞춰 해상도를 결정합니다. 이때는 AspectRatio에 auto를 넣지 말고 구체적인 비율을 지정해야 합니다.

LANGUAGE
{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\": \\\"auto\\\"}\"}"
}

자주 쓰는 프리셋은 1024x1024(정사각형), 1536x1024(가로), 1024x1536(세로)입니다. 2K(2560x1440)와 4K(3840x2160) 출력도 지원하며 2560px를 넘는 경우는 제한적 지원입니다.

이미지 편집 마스크

FileInfos에 ReferenceType=mask를 지정한 이미지를 함께 넣어 편집할 영역을 마스킹합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_sunburst_medium",
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://<cos>/room.png",
      "ReferenceType": "mask"
    },
    {
      "Type": "Url",
      "Url": "https://<cos>/room.png"
    }
  ],
  "Prompt": "the same sunny indoor lounge with a pool, but with a flamingo standing in the pool",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16"
  },
  "SessionContext": "job-001"
}

투명 배경

ExtInfo의 background에 transparent를 넣으면 배경이 투명한 이미지를 만듭니다.

LANGUAGE

"ExtInfo": "{\"AdditionalParameters\": \"{\\\"background\\\":\\\"transparent\\\"}\"}"

VOD와 MPS의 전달 위치가 다릅니다

같은 OG 엔진이라도 투명 배경 옵션을 넣는 자리가 다릅니다. VOD는 ExtInfo 안의 AdditionalParameters(JSON 문자열이 이중으로 인코딩됨)에 넣고, MPS는 최상위 AdditionalParameters에 직접 지정합니다.

출력 포맷 (OutputFormat)

OutputConfig.OutputFormat으로 출력 형식을 지정합니다. 생략 시 모델 기본값을 사용합니다.

LANGUAGE
{
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1K",
    "OutputFormat": "png"
  }
}

값	설명
`jpeg`	JPEG 출력
`png`	PNG 출력

PNG 출력을 권장하는 경우

무손실이 필요하거나 후처리에서 알파 채널이나 세부 계조를 다뤄야 하면 png를 지정하세요. 전달용으로 용량이 중요하면 jpeg가 유리합니다.

프롬프트 길이

프롬프트는 최대 32,000자까지 넣을 수 있습니다. 한국어, 영어, 일본어, 아랍어 등 여러 언어의 텍스트 렌더링을 지원합니다.

추가 옵션

품질 모드 = 버전

low/medium/high/xhigh/max는 속도, 비용, 화질 트레이드오프입니다.