Hy

Endpoint: POST https://vod.intl.tencentcloudapi.comAction: 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장을 생성합니다. 여러 장은 요청을 순차로 제출합니다.

요청 예시

텍스트 생성입니다.

{
  "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가 편집 지시문으로 해석됩니다.

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

응답 예시

{
  "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세로 형식입니다.

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

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

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

참조 이미지

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

{
  "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를 확인한 뒤 다음 요청을 제출합니다.