WAND-Vega-Image

화이트리스트 등록이 필요한 모델입니다.

대상: WAND-Vega-Image 1.0 Pro. Lite와 Flash는 화이트리스트 등록 없이 사용할 수 있습니다.

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations인증: Tokenhub API Key / Bearer

WAND-Vega-Image는 텍스트로 이미지를 생성하거나 참조 이미지를 편집합니다. 1.0 Pro / 1.0 Flash / 1.0 Lite를 제공하며 요청 후 작업 ID로 결과를 조회합니다.

기본 정보

항목	값
호출 경로	Tokenhub API
Pro 모델 ID	wand-vega-image-pro
Flash 모델 ID	wand-vega-image-flash
Lite 모델 ID	wand-vega-image-lite
가드레일 해제 지원	지원

버전별 지원 규격

버전	해상도	비율	참조 이미지
wand-vega-image-pro	1K / 2K / 4K	1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9	최대 10장
wand-vega-image-flash	1K / 2K / 4K	1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9	최대 10장
wand-vega-image-lite	1K / 2K / 4K	1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9	최대 10장

Lite와 Flash는 참조 이미지 입력 비용이 없습니다. 1.0 Pro는 처음 3장까지 무료이며, 4번째 이미지부터 입력 비용이 부과됩니다.

참조 이미지 규격

버전	참조 이미지 수	권장 파일당 용량	형식
wand-vega-image-pro	최대 10장	20MB 이하	PNG / JPEG
wand-vega-image-flash	최대 10장	20MB 이하	PNG / JPEG
wand-vega-image-lite	최대 10장	20MB 이하	PNG / JPEG

참조 이미지는 input.content.image_url에 전달합니다. 입력은 파일당 20MB 이하로 구성하고 이미지 개수는 전체 참조 배열을 기준으로 계산합니다. 참조 URL은 생성 서비스에서 다운로드할 수 있어야 하며, 비공개 객체는 유효한 서명 URL을 사용하십시오.

Tokenhub는 model 하나로 버전을 지정합니다. VOD/MPS에서는 ModelName=wand-vega-image와 ModelVersion=1.0-pro / 1.0-flash / 1.0-lite를 나누어 전달합니다.

호출 절차

이미지 생성은 시간이 오래 걸리는 작업이므로 API는 다음 두 단계로 구성된 비동기 호출 방식을 사용합니다.

1. 작업 제출: 이미지 생성 API를 호출합니다. 성공하면 task_id가 반환됩니다.
2. 결과 폴링: status = completed가 될 때까지 task_id를 사용하여 작업 결과 조회 API를 호출한 후 결과에서 이미지 URL을 가져옵니다.

이미지 생성

API 설명

WAND-Vega 이미지 생성 API는 텍스트 기반 이미지 생성과 참조 이미지 기반 생성을 지원합니다. 입력한 참조 이미지와 텍스트 프롬프트를 기반으로 이미지를 생성하며, 이미지가 제공되지 않으면 텍스트 기반 이미지 생성을 수행합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations

요청 파라미터

파라미터	필수	타입	설명
model	필수	string	모델 ID. wand-vega-image-pro / wand-vega-image-flash / wand-vega-image-lite
prompt	필수	string	텍스트 프롬프트이며 길이는 2000자 이하여야 합니다. 참조 이미지가 없으면 이 텍스트를 기반으로 이미지를 생성합니다.
input	선택	array[object]	이미지 변환/참조 이미지 시나리오에 사용하는 멀티모달 입력 콘텐츠 배열입니다.
input.content	선택	array[object]	입력 콘텐츠 세그먼트 배열입니다. 순서대로 연결되어 멀티모달 프롬프트를 구성합니다.
input.content.type	선택	string	콘텐츠 유형. 값: input_image(참조 이미지).
input.content.image_url	선택	string	참조 이미지 URL. 버전별 장수, 파일당 용량 및 형식은 참조 이미지 규격을 확인하십시오.
size	선택	string	${width}x${height} 형식의 출력 이미지 크기입니다.

요청 예시

텍스트 기반 이미지 생성

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "wand-vega-image-pro",
  "prompt": "A detailed painting of a butterfly",
  "size": "1024x1024"
}'

참조 이미지 기반 생성

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "wand-vega-image-pro",
  "prompt": "A seamless composition of all reference images",
  "input": [
    {
      "content": [
        {
          "type": "input_image",
          "image_url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
        }
      ]
    }
  ],
  "size": "1024x1024"
}'

응답 파라미터

파라미터	타입	설명
task_id	string	작업 ID입니다. 결과 조회와 콜백 연결에 사용합니다.
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.

응답 예시

{
  "task_id": "251380669-VegaImage-f91e7435e1e34dfa9898a451946bb3d3",
  "request_id": "5b7c57a3-e5e4-4df0-958b-e72d35582be1"
}

작업 결과 조회

조회 경로

이미지 생성 작업의 상태와 결과를 조회합니다. 작업을 제출하고 task_id를 받은 후 이 API를 폴링하여 결과를 가져옵니다.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/tasks/<task_id>

작업 제출 시 반환된 task_id로 3~5초 간격으로 조회합니다.

요청 파라미터

파라미터	필수	타입	설명
task_id	필수	string	작업 제출 시 반환된 task_id인 작업 ID(경로 파라미터)입니다.

요청 예시

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/tasks/<task_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

응답 파라미터

필드	유형	설명
status	String	작업 상태. 아래 상태별 처리 참조
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.
data	array[object]	생성된 결과 목록입니다.
data[].url	string	생성된 이미지의 다운로드 URL입니다. 서명이 포함된 임시 URL이므로 유효기간 안에 다운로드하여 저장하십시오.
usage	object	사용량입니다.
usage.total_tokens	integer	이 작업에서 소비한 토큰 수로, 과금/정산에 사용됩니다.
created_at	integer	작업 생성 시각. Unix timestamp(초)입니다.
finished_at	integer	작업 완료 시각. Unix timestamp(초)입니다.

상태별 처리

상태	의미	처리
queued	생성 대기	상태 조회 계속
in_progress	생성 중	상태 조회 계속
completed	생성 완료	data.url에서 이미지 다운로드
failed	생성 실패	오류 응답 확인
cancelled	취소됨	조회 종료
incomplete	미완료 상태로 종료	종료 사유 확인

응답 예시

{
  "task_id": "251380669-VegaImage-68a067d14b3c43c0961ce83373709f44",
  "status": "completed",
  "request_id": "92aa30e9-7549-4319-a0eb-467302d446f5",
  "data": [
    {
      "url": "https://aigc-image.cos.myqcloud.com/xxx/result.png"
    }
  ],
  "usage": {
    "total_tokens": 16200
  },
  "created_at": 1787560807,
  "finished_at": 1787560820
}

참조 입력과 결과 주소

input.content.image_url에는 다운로드 가능한 원본 이미지 URL을 전달합니다. 이미지 참조 입력은 소재 라이브러리 등록과 별개입니다.

생성 결과는 data.url에서 받습니다. 반환된 COS 다운로드 URL은 쿼리 문자열을 포함한 전체 주소를 사용하며, 만료 전에 파일을 저장하십시오. 이미지 생성 결과의 URL과 영상용 asset://<id>는 서로 다른 값입니다.

출력 크기

size는 요청 크기입니다. Flash는 텍스트 기반 생성에서도 요청과 다른 크기·비율의 이미지를 반환할 수 있습니다. 저장 전에 결과 파일의 실제 너비·높이와 종횡비를 확인하십시오.

비율별 픽셀 규격

비율	1K 해상도	2K 해상도	4K 해상도
1:1	1024×1024 / 1080×1080	2048×2048 / 2160×2160	4096×4096
2:3	1024×1536 / 1080×1620	1440×2160	3328×4992
3:2	1536×1024 / 1620×1080	2160×1440	4992×3328
3:4	1080×1440	1440×1920 / 2160×2880	3584×4800
4:3	1440×1080	1920×1440 / 2880×2160	4800×3584
9:16	720×1280 / 1080×1920	1440×2560	2160×3840
16:9	1280×720 / 1920×1080	2560×1440	3840×2160
21:9	1512×648	2520×1080	5040×2160

오류 코드

API 오류 코드를 참조하십시오.