VOD APILast Updated 2026-09-25

Hy

On this page

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

기본 정보

항목	값
ModelName	`Hunyuan`
ModelVersion	`3.5-preview` / `3.0`
기본값	`ModelVersion=3.5-preview`
지원 모드	텍스트 생성, 참조 이미지 생성, 생성물 재편집
가드레일 해제 지원	미지원

Hy Image에는 입력·출력 가드레일 해제 파라미터가 적용되지 않습니다.

텍스트 생성과 참조 이미지 기반 생성을 함께 지원합니다.

3.0은 참조 이미지 3장, 3.5-preview는 6장까지 입력할 수 있습니다.

요청 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	고정값 `Hunyuan`
`ModelVersion`	선택	String	`3.5-preview` / `3.0`
`Prompt`	필수	String	생성 프롬프트. 참조 이미지가 있으면 편집 지시문으로 동작
`FileInfos.N`	선택	Array	참조 이미지. `Type`과 `Url`을 넣습니다
`OutputConfig.Resolution`	선택	String	`1K` / `2K` / `4K`
`OutputConfig.AspectRatio`	선택	String	`1:1` / `16:9` / `9:16` / `4:3` 등
`OutputConfig.PersonGeneration`	선택	String	`AllowAdult` / `Disallowed`
`ExtInfo`	선택	String	픽셀 크기 직접 지정. 아래 항목을 참조하세요

요청당 출력 이미지

3.5-preview는 요청당 이미지 1장을 생성합니다. 여러 장은 요청을 순차로 제출합니다.

요청 예시

텍스트 생성입니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Hunyuan",
  "ModelVersion": "3.5-preview",
  "Prompt": "a serene japanese garden, soft morning light",
  "OutputConfig": {
    "Resolution": "2K",
    "AspectRatio": "16:9",
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

참조 이미지 기반 생성입니다. 참조 이미지를 넣으면 Prompt가 편집 지시문으로 해석됩니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Hunyuan",
  "ModelVersion": "3.5-preview",
  "Prompt": "change the car color to matte black, keep the composition",
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://<host>/car.png"
    }
  ],
  "OutputConfig": {
    "Resolution": "1K",
    "AspectRatio": "16:9",
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

응답 예시

LANGUAGE
{
  "AigcImageTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Progress": 100,
    "Output": {
      "FileInfos": [
        {
          "FileUrl": "https://store.vod-qcloud.com/.../aigcImageGenFile.png",
          "ExpireTime": "2026-10-02T07:59:41Z",
          "MetaData": {
            "Width": 2048,
            "Height": 1152,
            "Container": "png_pipe"
          }
        }
      ]
    }
  }
}

특수 설정

출력 해상도

Resolution과 AspectRatio 조합에 따른 실제 출력 픽셀입니다. 값은 16의 배수로 맞춰집니다.

Resolution	`1:1`	`16:9`	`9:16`	`4:3`	`3:4`
생략	`720x720`	`1280x720`	`720x1280`	`960x720`	`720x960`
`1K`	`1024x1024`	`1808x1024`	`1024x1808`	`1360x1024`	`1024x1360`
`2K`	`2048x2048`	`2048x1152`	`1152x2048`	`1920x1440`	`1440x1920`
`4K`	`4096x4096`	`3840x2160`	`2160x3840`	`3840x2880`	`2880x3840`

Resolution을 생략하고 AspectRatio만 넣으면 짧은 변이 720으로 고정됩니다. 두 값을 모두 생략하면 3:2 비율의 1872x1248로 출력됩니다. 같은 Resolution이라도 비율에 따라 실제 픽셀이 달라지므로, 정확한 크기가 필요하면 아래 ExtInfo로 직접 지정하세요.

4K / 5:4 조합은 2688x2160으로 출력됩니다.

픽셀 크기 직접 지정

ExtInfo에 size를 넣으면 Resolution과 AspectRatio보다 우선 적용됩니다. 값은 가로x세로 형식입니다.

LANGUAGE
{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\":\\\"1808x1024\\\"}\"}"
}

입력값	실제 출력
`1808x1024`	`1808x1024`
`656x1024`	`656x1024`
`656x1000`	`656x992` (`16`의 배수로 내림)
`auto`	프롬프트에 맞춰 자동 결정
`100x100`	`256x256` (하한으로 보정)

출력 크기는 16의 배수와 최소 크기 기준으로 보정됩니다. auto는 Resolution을 함께 지정하면 해당 해상도를 기준으로, 단독이면 프롬프트를 기준으로 비율을 결정합니다.

참조 이미지

FileInfos에 Type과 Url을 지정합니다. 이미지 파일은 Type을 Url로 둡니다.

LANGUAGE
{
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://<host>/reference.png"
    }
  ]
}

항목	값
허용 필드	`Type`(`Url`), `Url` / `ReferenceType`(선택)
참조 장수	최대 `6장`
포맷	jpeg, png, webp

참조 이미지 필드

FileInfos는 Type="Url"과 이미지 Url을 지정합니다.

운영 참고

항목	값
`1K` 처리 시간	`12초`에서 `21초`
`2K` 처리 시간	`21초`에서 `30초`
`4K` 처리 시간	`34초`에서 `46초`

여러 이미지 요청은 순차로 처리합니다. DescribeTaskDetail에서 Status="FINISH" / ErrCode=0과 Output.FileInfos를 확인한 뒤 다음 요청을 제출합니다.