WAND-Vega-VideoHOT

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

대상: WAND-Vega-Video 1.0 Pro / 1.5 Pro. Lite는 화이트리스트 등록 없이 사용할 수 있습니다. 소재 관리 기능은 별도 접근 권한이 필요합니다.

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

WAND-Vega-Video는 텍스트, 첫·마지막 프레임, 참조 이미지·영상·오디오로 영상을 생성합니다. 생성 작업을 제출한 후 작업 ID로 상태와 결과를 조회합니다.

기본 정보

항목	값
호출 경로	Tokenhub API
입력	텍스트 / 첫·마지막 프레임 / 참조 이미지·영상·오디오
생성 방식	비동기
결과 조회	`GET /v1/wand/vega-videos/tasks/{id}`
결과 필드	`content.video_url`

버전별 지원 규격

버전	해상도	비율	길이
`wand-vega-video-1.5-pro`	`720P` / `1080P` / `2K` / `4K`	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `adaptive`	`4~15초` / `-1`
`wand-vega-video-1.0-pro`	`720P` / `1080P` / `2K` / `4K`	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `adaptive`	`4~15초` / `-1`
`wand-vega-video-1.0-lite`	`768P` / `1080P` / `2K` / `4K`	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `adaptive`	`4~15초`

기본 길이는 5초, 기본 비율은 adaptive입니다. Pro의 기본 해상도는 720P, Lite는 768P입니다. adaptive는 모델 또는 입력 소재에 따라 비율을 결정합니다.

Pro의 duration=-1은 모델이 길이를 결정하도록 지정합니다. Lite는 -1을 지원하지 않습니다. 지원하지 않는 해상도는 자동 변환되지 않으며 요청 단계에서 오류가 반환됩니다. 예를 들어 Lite에 720P를 지정하지 마십시오.

입력 방식

방식	content 구성	조건
텍스트 기반	`type=text`	비어 있지 않은 텍스트 요소 `1개` 이상
첫·마지막 프레임	`text` + `image_url`	`first_frame` 최대 `1장` / `last_frame` 최대 `1장`
참조 기반	`text` + 이미지·영상·오디오	각 미디어 요소에 해당 `role` 지정
등록 소재 참조	`text` + `asset://<id>`	`1.0 Pro` / `1.5 Pro` 전용. 소재 상태 `DONE` 필요

호출 절차

생성 API에 요청을 제출하고 응답의 id를 받습니다.
작업 조회 API를 3~5초 간격으로 호출합니다.
status=succeeded이면 content.video_url에서 결과를 다운로드합니다. failed이면 error를 확인하고 조회를 종료합니다.

생성 요청은 요청 단위의 멱등성을 제공하지 않습니다. 같은 요청을 다시 제출하면 새로운 작업 ID가 발급되어 중복 생성·과금될 수 있습니다. 작업 ID를 받은 뒤에는 재제출하지 않고 해당 작업을 조회하십시오.

영상 생성

API 설명

텍스트 기반, 첫·마지막 프레임 기반, 참조 기반 생성은 같은 API를 사용합니다. content의 type과 role 조합으로 입력 방식을 지정합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks

요청 파라미터

파라미터	필수	타입	설명
`model`	필수	String	버전별 모델 ID
`content`	필수	Array[Object]	텍스트와 참조 미디어. 비어 있지 않은 `type=text` 요소를 하나 이상 포함
`resolution`	선택	String	Pro: `720P` / `1080P` / `2K` / `4K`. Lite: `768P` / `1080P` / `2K` / `4K`
`ratio`	선택	String	버전별 지원 규격의 비율. 기본 `adaptive`
`duration`	선택	Integer	`4~15`초의 정수. 기본 `5`. Pro는 `-1` 추가 지원
`options`	선택	Object	확장 옵션. 생략 또는 빈 객체는 기본값 적용
`options.return_last_frame`	선택	Boolean	마지막 프레임 반환 요청. 기본 `false`. 실제 마지막 프레임이 생성된 경우에만 조회 결과에 포함

content 요소

하나의 요소에는 type에 맞는 콘텐츠 필드를 사용합니다. 서로 다른 미디어 필드를 한 요소에 혼합하지 마십시오.

파라미터	필수	타입	설명
`content.type`	필수	String	`text` / `image_url` / `video_url` / `audio_url`
`content.text`	조건부 필수	String	`type=text`일 때 비어 있지 않은 프롬프트. 여러 텍스트 요소는 배열 순서대로 연결
`content.image_url`	조건부 필수	Object	`type=image_url`일 때 `{"url":"..."}` 형식
`content.image_url.url`	조건부 필수	String	이미지 URL 또는 Pro에서 사용할 등록 소재 참조
`content.video_url`	조건부 필수	Object	`type=video_url`일 때 `{"url":"..."}` 형식
`content.video_url.url`	조건부 필수	String	비어 있지 않은 영상 URL
`content.audio_url`	조건부 필수	Object	`type=audio_url`일 때 `{"url":"..."}` 형식
`content.audio_url.url`	조건부 필수	String	비어 있지 않은 오디오 URL
`content.role`	조건부 필수	String	미디어 요소에는 필수. `type=text`에서는 사용하지 않음

type	role	용도
`text`	사용하지 않음	텍스트 프롬프트
`image_url`	`first_frame`	첫 프레임
`image_url`	`last_frame`	마지막 프레임
`image_url`	`reference_image`	참조 이미지
`video_url`	`reference_video`	참조 영상. 다른 role 사용 불가
`audio_url`	`reference_audio`	참조 오디오. 다른 role 사용 불가

참조 입력 조건

항목	조건
첫·마지막 프레임	각각 최대 `1장`. 텍스트 프롬프트 필수
첫·마지막 프레임의 비율	`ratio` 생략 시 입력 이미지에 따라 결정. 지원 비율을 명시적으로 지정할 수도 있음
참조 이미지·영상·오디오	미디어마다 `role` 필수. 생략하거나 빈 값으로 전달하면 오류
권장 참조 구성	이미지 `9장` / 영상 `3개` / 오디오 `3개` 이내, 전체 `12개` 이하
오디오 참조	참조 이미지 또는 영상을 함께 전달하는 구성 권장
파일 주소	외부에서 접근 가능한 HTTP/HTTPS URL 또는 유효한 서명 URL. Base64 인라인 입력 미지원
등록 소재	Pro에서만 `asset://<id>` 사용. 소재와 영상 생성 요청은 동일 AppID에 속해야 함

위 참조 개수는 Tokenhub 요청 구성의 권장값입니다. VOD/MPS의 FileInfos 개수나 용량 규격을 이 API의 제한으로 적용하지 마십시오.

요청 예시

텍스트 기반 생성

bash

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wand-vega-video-1.0-lite",
    "content": [{"type": "text", "text": "A red ceramic cup on a white table, slow camera push in."}],
    "resolution": "768P",
    "ratio": "16:9",
    "duration": 6
  }'

첫·마지막 프레임 기반 생성

json

{
  "model": "wand-vega-video-1.0-pro",
  "content": [
    {"type": "text", "text": "Move naturally from the first frame to the last frame while maintaining consistent lighting."},
    {"type": "image_url", "image_url": {"url": "https://example.com/start.jpg"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "https://example.com/end.jpg"}, "role": "last_frame"}
  ],
  "resolution": "1080P",
  "duration": 8
}

참조 이미지·영상·오디오 기반 생성

json

{
  "model": "wand-vega-video-1.5-pro",
  "content": [
    {"type": "text", "text": "Animate the reference product in the reference scene, matching the rhythm of the reference audio."},
    {"type": "image_url", "image_url": {"url": "https://example.com/product.jpg"}, "role": "reference_image"},
    {"type": "video_url", "video_url": {"url": "https://example.com/scene.mp4"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 10,
  "options": {"return_last_frame": true}
}

응답 파라미터

정상 제출 응답은 HTTP 201 Created이며 작업 ID를 반환합니다. 작업 접수는 영상 생성 완료를 의미하지 않습니다.

필드	타입	설명
`id`	String	작업 조회에 사용할 ID
`model`	String	요청한 모델 ID
`status`	String	제출 성공 시 `queued`

json

{
  "id": "<task_id>",
  "model": "wand-vega-video-1.0-lite",
  "status": "queued"
}

작업 결과 조회

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks/{id}

요청 파라미터

파라미터	필수	타입	설명
`id`	필수	String	생성 요청에서 반환된 작업 ID. 경로 파라미터

bash

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

응답 파라미터

필드	타입	설명
`id`	String	작업 ID
`model`	String	요청한 모델 ID를 그대로 반환하는 값. 실제 결과 생성 모델을 별도로 식별하는 필드는 아님
`status`	String	`queued` / `running` / `succeeded` / `failed`
`content`	Object	`succeeded`일 때 생성 결과
`content.video_url`	String	완료 영상의 임시 다운로드 주소. 유효기간 `12시간`
`content.last_frame_url`	String	`return_last_frame=true`이고 마지막 프레임이 생성된 경우에만 포함
`error`	Object	`failed`일 때 오류 정보
`error.code`	String	작업 오류 코드. 예: `InternalError` / `TaskTimeout`
`error.message`	String	실패 사유

상태별 처리

상태	의미	처리
`queued`	대기	같은 작업 ID로 조회 계속
`running`	생성 중	같은 작업 ID로 조회 계속
`succeeded`	완료	결과 다운로드 후 조회 종료
`failed`	실패	오류 확인 후 조회 종료

json

{
  "id": "<task_id>",
  "model": "wand-vega-video-1.5-pro",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "last_frame_url": "https://example.com/last-frame.jpg"
  }
}

결과 URL은 만료 전에 저장하십시오. 대기 시간이 초과되면 failed와 TaskTimeout이 반환될 수 있습니다. 장시간 대기가 지속되면 작업 ID와 조회 응답을 전달하여 문의하십시오.

Pro / 소재 라이브러리 참조

소재 등록 → 소재 조회 → 영상 생성 → 결과 조회 순서로 사용합니다. 필요가 없어진 소재는 삭제할 수 있습니다. asset://<id>는 1.0 Pro와 1.5 Pro 전용이며 Lite는 HTTP/HTTPS URL을 사용합니다.

소재 등록 API는 ID를 즉시 반환하지만 파일 처리는 비동기로 진행합니다. ID를 받았더라도 status=DONE이 되기 전에는 생성 요청에 사용하지 마십시오. 소재와 영상 생성 요청은 동일 AppID에 속해야 합니다.

API 목록

기능	메서드	경로
소재 등록	`POST`	`/v1/wand/vega-video-assets`, `action=create`
소재 조회	`GET`	`/v1/wand/vega-video-assets/{id}`
소재 삭제	`POST`	`/v1/wand/vega-video-assets`, `action=delete`

소재 등록 요청

파라미터	필수	타입	설명
`action`	필수	String	`create`
`url`	필수	String	외부 접근 가능한 원본 HTTP/HTTPS URL. Base64 입력 미지원
`asset_type`	필수	String	대소문자를 구분하는 `Image` / `Video` / `Audio`
`asset_name`	선택	String	관리용 이름. 생성 요청의 참조 방식에는 영향 없음
`group_id`	선택	String	기존 그룹에 소재를 추가할 때 지정. 생략하면 자동 생성
`is_real_person`	선택	Boolean	실사 인증 소재 여부. `true`이면 실사 인증으로 발급된 그룹 ID 필요

bash

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create",
    "url": "https://example.com/product.jpg",
    "asset_type": "Image",
    "asset_name": "reference-product"
  }'

소재 등록 응답

정상 응답은 HTTP 201 Created입니다.

필드	타입	설명
`id`	String	소재 조회와 생성 참조에 사용할 ID
`group_id`	String	소재 그룹 ID. 반환된 경우에 포함
`request_id`	String	`X-Request-Id` 요청 헤더를 전달한 경우 반환되는 추적 ID

json

{
  "id": "<asset_id>",
  "group_id": "<group_id>"
}

그룹 ID를 생략하면 group-YYYYmmddHHMMSS-숫자4자리 형식으로 자동 생성됩니다. 여러 소재를 같은 그룹으로 관리하려면 동일한 group_id를 지정하십시오.

소재 조회

GET /v1/wand/vega-video-assets/{id}에서 id는 등록 응답의 소재 ID입니다. 3~5초 간격으로 조회합니다.

bash

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/<asset_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'

필드	타입	설명
`id`	String	소재 ID
`status`	String	`WAIT` / `DONE` / `FAIL`
`url`	String	TOS의 임시 서명 다운로드 주소. 값이 있을 때만 포함되며 `WAIT` 중에는 보통 없음
`group_id`	String	소재 그룹 ID. 값이 있을 때만 포함
`message`	String	실패 사유 또는 추가 설명. 값이 있을 때만 포함
`request_id`	String	`X-Request-Id` 요청 헤더를 전달한 경우에만 포함

상태	의미	처리
`WAIT`	소재 처리 중	조회 계속
`DONE`	사용 가능	Pro 생성 요청에서 `asset://<id>`로 참조
`FAIL`	소재 처리 실패	`message`를 확인하고 수정한 원본 URL로 다시 등록

json

{
  "id": "<asset_id>",
  "status": "DONE",
  "url": "https://example.com/reference.jpg?signature=...",
  "group_id": "<group_id>"
}

소재 주소와 실사 인물 참조

asset://<id>는 파일 다운로드 주소가 아닌 논리 참조입니다. 소재 파일은 조회 응답의 url에서 다운로드하며 이 TOS 서명 URL의 유효기간은 약 11.5시간입니다. 반환된 호스트와 서명 쿼리를 그대로 사용하십시오. 영상 생성 결과의 content.video_url과 소재 조회의 url은 서로 다른 주소입니다.

Lite는 asset://를 지원하지 않습니다. 같은 비인물 소재를 Lite에 전달할 때는 원본 공개 URL 또는 유효한 소재 조회 URL을 사용하십시오.

실사 인물 소재는 먼저 실사 인증을 진행해 발급된 그룹 ID를 받아야 합니다. 이후 group_id와 is_real_person=true로 소재를 등록하고, DONE 확인 후 Pro 생성 요청에서 참조합니다. 일반 그룹에 is_real_person=true만 추가하는 방식으로 실사 인증을 대체할 수 없습니다. 실사 인증 절차와 권한은 담당자에게 문의하십시오.

등록 소재로 영상 생성

json

{
  "model": "wand-vega-video-1.5-pro",
  "content": [
    {"type": "text", "text": "Preserve the reference subject and create natural motion."},
    {"type": "image_url", "image_url": {"url": "asset://<asset_id>"}, "role": "reference_image"}
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

소재 삭제

삭제는 DELETE가 아닌 POST입니다. id와 group_id 중 정확히 하나만 지정합니다. 둘 다 전달하거나 모두 생략하면 오류가 반환됩니다.

파라미터	필수	타입	설명
`action`	필수	String	`delete`
`id`	조건부 필수	String	개별 소재 삭제 시 지정
`group_id`	조건부 필수	String	그룹의 전체 소재 삭제 시 지정

개별 소재 삭제

json

{"action": "delete", "id": "<asset_id>"}

그룹 전체 삭제

json

{"action": "delete", "group_id": "<group_id>"}

응답 필드	타입	설명
`deleted`	Boolean	정상 삭제 시 `true`
`id`	String	개별 삭제일 때 삭제된 소재 ID
`group_id`	String	그룹 삭제일 때 삭제된 그룹 ID
`request_id`	String	`X-Request-Id` 요청 헤더를 전달한 경우에만 포함

json

{"deleted": true, "id": "<asset_id>"}

이미 삭제한 소재를 다시 삭제하면 404 not_found가 반환될 수 있습니다. 그룹 삭제는 해당 그룹의 모든 소재에 적용되므로 삭제 범위를 확인하십시오.

오류 코드

HTTP 요청 오류와 비동기 작업 실패를 구분합니다. HTTP 오류는 응답의 error를, 생성 작업 실패는 조회 결과의 status와 error를 확인하십시오.

HTTP 상태	error.code	의미 및 처리
`400`	`invalid_request_error`	필수 필드, 타입, 모델별 해상도, type/role 또는 삭제 ID 조합 확인
`401`	게이트웨이에서 반환한 코드	Bearer 인증과 API Key 유효 여부 확인
`403`	`permission_denied`	소재 라이브러리 접근 권한 확인
`404`	`not_found`	작업 또는 소재 ID와 요청 경로 확인. 이미 삭제된 소재인지 확인
`413`	`request_too_large`	소재 관리 API의 요청 본문 또는 응답 크기 초과
`500`	`internal_error`	서비스 오류. 작업 ID를 받은 경우 먼저 기존 작업 조회
`503`	`service_unavailable`	일시적인 과부하. 재시도 간격을 늘려 요청

소재 관리 API의 POST 요청 본문과 응답 크기 한도는 각각 1MiB입니다. URL로 등록하는 이미지·영상·오디오 파일 자체의 용량 한도를 의미하지 않습니다.

json

{
  "error": {"code": "invalid_request_error", "message": "Invalid request parameters"}
}

Tokenhub API 오류 코드

WAND-Vega-VideoHOT ​

기본 정보 ​

버전별 지원 규격 ​

입력 방식 ​

호출 절차 ​

영상 생성 ​

API 설명 ​

요청 파라미터 ​

content 요소 ​

참조 입력 조건 ​

요청 예시 ​

응답 파라미터 ​

작업 결과 조회 ​

요청 파라미터 ​

응답 파라미터 ​

상태별 처리 ​

Pro / 소재 라이브러리 참조 ​

API 목록 ​

소재 등록 요청 ​

소재 등록 응답 ​

소재 조회 ​

소재 주소와 실사 인물 참조 ​

등록 소재로 영상 생성 ​

소재 삭제 ​

오류 코드 ​

WAND-Vega-VideoHOT

기본 정보

버전별 지원 규격

입력 방식

호출 절차

영상 생성

API 설명

요청 파라미터

content 요소

참조 입력 조건

요청 예시

응답 파라미터

작업 결과 조회

요청 파라미터

응답 파라미터

상태별 처리

Pro / 소재 라이브러리 참조

API 목록

소재 등록 요청

소재 등록 응답

소재 조회

소재 주소와 실사 인물 참조

등록 소재로 영상 생성

소재 삭제

오류 코드