Tokenhub APILast Updated 2026-09-30

PixVerse

On this page

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video
인증: Tokenhub API Key / Bearer

PixVerse는 텍스트, 이미지, 첫 프레임 / 끝 프레임, 참조 입력으로 영상을 생성합니다.

기본 정보

항목	값
호출 경로	Tokenhub API
가드레일 해제 지원	미지원

버전별 지원 규격

버전	해상도	비율	길이
`pixverse-video-v6.0`	`360p` / `540p` / `720p` / `1080p`	`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `2:3` / `3:2` / `21:9`	`1 ~ 15초`
`pixverse-video-c1`	`360p` / `540p` / `720p` / `1080p`	`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `2:3` / `3:2` / `21:9`	`1 ~ 15초`

입력 모드

버전	입력
`pixverse-video-v6.0`	텍스트-동영상 / 이미지-동영상 / 시작/마지막 프레임 / 참조 기반 생성
`pixverse-video-c1`	텍스트-동영상 / 이미지-동영상 / 시작/마지막 프레임 / 참조 기반 생성

호출 절차

동영상 생성은 시간이 오래 걸리는 작업입니다(일반적으로 1~5분). API는 비동기 호출 방식을 사용하며, 다음 두 단계로 나뉩니다.

작업 제출: 기능 API(텍스트-동영상/이미지-동영상/시작/마지막 프레임-동영상/참조-동영상)를 호출합니다. 성공하면 Resp.video_id(작업 ID)가 반환됩니다.
결과 폴링: video_id로 작업 결과 조회 API를 호출합니다. Resp.status = 1(생성 성공)이 될 때까지 3~5초마다 폴링한 후 Resp.url에서 결과 동영상을 가져오는 것이 좋습니다.

참고: 작업이 성공적으로 생성된 후에는 다시 제출하지 마십시오. 폴링으로 결과를 가져오십시오. 공통 응답 형식: ErrCode(0은 성공), ErrMsg(메시지), Resp(데이터 객체).

텍스트-동영상

API 설명

텍스트 프롬프트만으로 동영상을 생성하며, 카메라 움직임, 오디오 및 다중 숏 토글을 지원합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video

요청 파라미터

파라미터	필수	타입	설명
prompt	필수	string	원하는 동영상 콘텐츠를 설명하는 텍스트 프롬프트입니다. 값 범위: ≤ `5000`자.
model	필수	string	모델 버전입니다. 값 범위: `pixverse-video-v6.0`, `pixverse-video-c1`
duration	필수	integer	동영상 길이(초)입니다. 값 범위: `1~15`의 정수. 기본값: 5.
quality	필수	string	동영상 선명도입니다. 값 범위: `360p` / `540p` / `720p` / 1080p.
aspect_ratio	선택	string	비율입니다. 값 범위: `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `2:3` / `3:2` / `21`:9. 기본값: `16`:9.
camera_movement	선택	string	카메라 움직임입니다(예: zoom_in, 필요에 따라 사용).
seed	선택	integer	난수 시드입니다. 값 범위: `0`~2147483647. 지정하지 않거나 `0`으로 설정하면 난수를 사용합니다.
generate_audio_switch	선택	boolean	오디오 스위치입니다. true=소리 있음(어울리는 배경 음악이나 음향 효과 자동 생성), false=음소거. 기본값: false.
generate_multi_clip_switch	선택	boolean	다중 숏 스위치이며, `pixverse-video-v6.0`만 지원합니다. true=다중 숏(시스템이 지능적으로 숏 분할), false=단일 숏. 기본값: false.

요청 예시

LANGUAGE
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "pixverse-video-v6.0",
  "prompt": "An orange kitten on the windowsill looks toward the camera",
  "duration": 5,
  "quality": "360p",
  "aspect_ratio": "16:9"
}'

참고: 해당 모델을 호출하려면 예시의 model을 pixverse-video-c1로 바꾸십시오.

응답 파라미터

필드	타입	설명
ErrCode	integer	오류 코드이며, `0`은 성공을 나타냅니다.
ErrMsg	string	오류 또는 안내 정보입니다.
Resp	object	응답 데이터 객체입니다.
Resp.video_id	string	작업 상태 폴링에 사용하는 작업 ID입니다.
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.

응답 예시

LANGUAGE
{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": "4-WandVideo-4ba31a7d508249b787fa0b0c62a6a399"
  },
  "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

오류 코드

요청이 실패하면 ErrCode는 0이 아닙니다. 구체적인 원인은 ErrMsg를 참조합니다. 작업이 성공적으로 제출되면 생성 단계의 작업 상태를 "작업 결과 조회" API를 통해 가져올 수 있습니다.

status	설명	처리 권장 사항
`1`	생성 성공	`Resp.url`에서 결과 동영상을 가져옵니다.
`5`	생성 중	status=`1`이 될 때까지 `3~5초`마다 한 번씩 폴링합니다.
`6`	삭제됨	작업 결과가 삭제되었습니다. 작업을 다시 시작하십시오.
`7`	콘텐츠 검토 실패	프롬프트/이미지에 금지된 콘텐츠가 포함되어 있는지 확인하고 수정한 후 다시 시도하십시오.
`8`	생성 실패	서버 측 생성 오류가 발생했습니다. 요청을 다시 시도하십시오. 계속 실패하면 기술 지원팀에 문의하고 작업 ID를 제공합니다.

이미지-동영상

API 설명

이미지를 첫 프레임으로 사용하여 동적인 동영상을 생성합니다. 공개적으로 액세스 가능한 URL로 이미지를 직접 전달하며, 출력 동영상의 비율은 입력 이미지의 비율을 따릅니다. 네거티브 프롬프트, 카메라 움직임, 오디오 및 다중 숏 토글을 지원합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/image-to-video

요청 파라미터

파라미터	필수	타입	설명
img_id	필수	string	이미지 주소이며, 공개적으로 액세스 가능한 이미지 URL 또는 base64 이미지 데이터일 수 있습니다.
img_ids	선택	array[string]	다중 이미지 템플릿 전용 이미지 URL 배열입니다(예: ["url1", "url2"]).
prompt	필수	string	텍스트 프롬프트입니다. 값 범위: ≤ `5000`자.
model	필수	string	모델 버전입니다. 값 범위: `pixverse-video-v6.0`, `pixverse-video-c1`
duration	필수	integer	동영상 길이(초)입니다. 값 범위: `1~15`의 정수. 기본값: 5.
quality	필수	string	동영상 선명도입니다. 값 범위: `360p` / `540p` / `720p` / 1080p.
camera_movement	선택	string	카메라 움직임입니다(예: zoom_in, 필요에 따라 사용).
seed	선택	integer	난수 시드입니다. 값 범위: `0`~2147483647. 지정하지 않거나 `0`으로 설정하면 난수를 사용합니다.
generate_audio_switch	선택	boolean	오디오 스위치입니다. true=소리 있음, false=음소거. 기본값: false.
generate_multi_clip_switch	선택	boolean	다중 숏 스위치이며, `pixverse-video-v6.0`만 지원합니다. true=다중 숏, false=단일 숏. 기본값: false.

요청 예시

LANGUAGE
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/image-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "pixverse-video-v6.0",
  "prompt": "Make the subject in the image turn its head naturally",
  "img_id": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png",
  "duration": 5,
  "quality": "360p"
}'

참고: 해당 모델을 호출하려면 예시의 model을 pixverse-video-c1로 바꾸십시오.

응답 파라미터

필드	타입	설명
ErrCode	integer	오류 코드이며, `0`은 성공을 나타냅니다.
ErrMsg	string	오류 또는 안내 정보입니다.
Resp	object	응답 데이터 객체입니다.
Resp.video_id	string	생성 작업의 동영상 ID이며, 작업 상태 조회를 위한 폴링에 사용합니다.
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.

응답 예시

LANGUAGE
{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
  },
  "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

오류 코드

status	설명	처리 권장 사항
`1`	생성 성공	`Resp.url`에서 결과 동영상을 가져옵니다.
`5`	생성 중	status=`1`이 될 때까지 `3~5초`마다 한 번씩 폴링합니다.
`6`	삭제됨	작업 결과가 삭제되었습니다. 작업을 다시 시작하십시오.
`7`	콘텐츠 검토 실패	프롬프트/이미지에 금지된 콘텐츠가 포함되어 있는지 확인하고 수정한 후 다시 시도하십시오.
`8`	생성 실패	서버 측 생성 오류가 발생했습니다. 요청을 다시 시도하십시오. 계속 실패하면 기술 지원팀에 문의하고 작업 ID를 제공합니다.

시작 및 마지막 프레임-동영상

Start End To Video

두 이미지를 시작 및 마지막 프레임(공개적으로 액세스 가능한 URL)으로 지정하여 두 프레임 사이를 자연스럽게 전환하는 동영상을 생성합니다. 출력 동영상의 비율은 입력 이미지의 비율을 따릅니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/start-end-to-video

참고: 최상의 전환 효과를 위해 시작 및 마지막 프레임 이미지의 비율을 동일하게 유지하는 것이 좋습니다.

요청 파라미터

파라미터	필수	타입	설명
prompt	필수	string	전환 콘텐츠를 설명하는 텍스트 프롬프트입니다. 값 범위: ≤ `5000`자. 예: "첫 프레임에서 마지막 프레임으로 자연스럽게 전환"
first_frame_img	필수	string	첫 프레임 이미지 주소이며, 공개적으로 액세스 가능한 이미지 URL 또는 base64 이미지 데이터일 수 있습니다.
last_frame_img	필수	string	마지막 프레임 이미지 주소이며, 공개적으로 액세스 가능한 이미지 URL 또는 base64 이미지 데이터일 수 있습니다.
model	필수	string	모델 버전입니다. 값 범위: `pixverse-video-v6.0`, `pixverse-video-c1`
duration	필수	integer	동영상 길이(초)입니다. 값 범위: `1~15`의 정수. 기본값: 5.
quality	필수	string	동영상 선명도입니다. 값 범위: `360p` / `540p` / `720p` / 1080p.
seed	선택	integer	난수 시드입니다. 값 범위: `0`~2147483647. 지정하지 않거나 `0`으로 설정하면 난수를 사용합니다.
generate_audio_switch	선택	boolean	오디오 스위치입니다. true=소리 있음, false=음소거. 기본값: false.

요청 예시

LANGUAGE
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/start-end-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "pixverse-video-v6.0",
  "prompt": "Transition naturally from the first frame to the last frame",
  "first_frame_img": "https://example.com/start.jpg",
  "last_frame_img": "https://example.com/end.jpg",
  "duration": 5,
  "quality": "360p"
}'

참고: 해당 모델을 호출하려면 예시의 model을 pixverse-video-c1로 바꾸십시오.

응답 파라미터

필드	타입	설명
ErrCode	integer	오류 코드이며, `0`은 성공을 나타냅니다.
ErrMsg	string	오류 또는 안내 정보입니다.
Resp	object	응답 데이터 객체입니다.
Resp.video_id	string	작업 상태 폴링에 사용하는 작업 ID입니다.
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.

응답 예시

LANGUAGE
{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
  },
  "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

오류 코드

status	설명	처리 권장 사항
`1`	생성 성공	`Resp.url`에서 결과 동영상을 가져옵니다.
`5`	생성 중	status=`1`이 될 때까지 `3~5초`마다 한 번씩 폴링합니다.
`6`	삭제됨	작업 결과가 삭제되었습니다. 작업을 다시 시작하십시오.
`7`	콘텐츠 검토 실패	프롬프트/이미지에 금지된 콘텐츠가 포함되어 있는지 확인하고 수정한 후 다시 시도하십시오.
`8`	생성 실패	서버 측 생성 오류가 발생했습니다. 요청을 다시 시도하십시오. 계속 실패하면 기술 지원팀에 문의하고 작업 ID를 제공합니다.

참조-동영상 생성

API 설명

참조 이미지 세트(참조 대상/배경)와 프롬프트를 결합하여 참조 대상의 일관성이 유지되는 동영상을 생성합니다. 참조 이미지는 공개적으로 액세스 가능한 URL로 직접 전달하며, 프롬프트에서 @ref_name을 사용하여 특정 참조 이미지를 지칭할 수 있습니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/reference-to-video

요청 파라미터

파라미터	필수	타입	설명
image_references	필수	array[object]	참조 이미지 배열입니다. 최대 `7개` 항목을 지원합니다. 하위 필드는 다음 표를 참조합니다.
prompt	필수	string	텍스트 프롬프트입니다. 값 범위: `5000`자 이하. `@ref_name`을 사용하여 이미지를 참조합니다(@ 뒤에 공백 사용). 예: "@dog가 @room에서 논다".
model	필수	string	모델 버전입니다. 값 범위: `pixverse-video-v6.0`, `pixverse-video-c1`
duration	필수	integer	동영상 길이(초)입니다. 값 범위: `1~15`의 정수. 기본값: 5.
quality	필수	string	동영상 선명도입니다. 값 범위: `360p` / `540p` / `720p` / 1080p.
aspect_ratio	선택	string	비율입니다. 값 범위: `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `2:3` / `3:2` / `21`:9. 기본값: `16`:9.
generate_audio_switch	선택	boolean	오디오 스위치입니다. true=소리 있음, false=음소거. 기본값: false.
seed	선택	integer	난수 시드입니다. 값 범위: `0`~2147483647.

image_references 배열 요소의 하위 필드:

파라미터	필수	타입	설명
img_id	필수	string	참조 이미지 주소이며, 공개적으로 액세스 가능한 이미지 URL 또는 base64 이미지 데이터일 수 있습니다.
type	선택	string	참조 이미지 유형입니다. 값: subject/background.
ref_name	선택	string	참조 이미지 이름이며 `30`자 이하여야 합니다. 프롬프트에서 `@ref_name`으로 참조하는 데 사용합니다.

요청 예시

LANGUAGE
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/reference-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "pixverse-video-v6.0",
  "prompt": "Make the subject in the reference image wave naturally",
  "image_references": [
    {
      "img_id": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png",
      "type": "subject"
    }
  ],
  "duration": 5,
  "quality": "360p",
  "aspect_ratio": "16:9"
}'

참고: 해당 모델을 호출하려면 예시의 model을 pixverse-video-c1로 바꾸십시오.

응답 파라미터

필드	타입	설명
ErrCode	integer	오류 코드이며, `0`은 성공을 나타냅니다.
ErrMsg	string	오류 또는 안내 정보입니다.
Resp	object	응답 데이터 객체입니다.
Resp.video_id	string	작업 상태 폴링에 사용하는 작업 ID입니다.
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.

응답 예시

LANGUAGE
{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
  },
  "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

오류 코드

status	설명	처리 권장 사항
`1`	생성 성공	`Resp.url`에서 결과 동영상을 가져옵니다.
`5`	생성 중	status=`1`이 될 때까지 `3~5초`마다 한 번씩 폴링합니다.
`6`	삭제됨	작업 결과가 삭제되었습니다. 작업을 다시 시작하십시오.
`7`	콘텐츠 검토 실패	프롬프트/이미지에 금지된 콘텐츠가 포함되어 있는지 확인하고 수정한 후 다시 시도하십시오.
`8`	생성 실패	서버 측 생성 오류가 발생했습니다. 요청을 다시 시도하십시오. 계속 실패하면 기술 지원팀에 문의하고 작업 ID를 제공합니다.

작업 결과 조회

API 설명

네 가지 기능 API에서 공통으로 사용하는 작업 조회 API로, 생성 결과를 폴링하는 데 사용합니다.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/{task_id}

참고: 경로의 {task_id}는 작업 제출 시 반환된 Resp.video_id입니다. 동영상 생성에는 약 수분이 걸리므로 3~5초마다 폴링하는 것이 좋습니다.

요청 파라미터

파라미터	필수	타입	설명
task_id	필수	string	작업 ID(경로 파라미터)이며, 작업 제출 시 반환되는 `Resp.video_id`입니다.

요청 예시

LANGUAGE

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

응답 파라미터

필드	타입	설명
ErrCode	integer	오류 코드이며, `0`은 성공을 나타냅니다.
ErrMsg	string	오류 또는 안내 정보
Resp	object	응답 데이터 객체(작업 세부 정보)
Resp.id	string	동영상 ID(video_id)
Resp.status	integer	동영상 상태: `1` 성공 / `5` 생성 중 / `6` 삭제됨 / `7` 검토 실패 / `8` 생성 실패
Resp.url	string	생성 성공 후 동영상 결과 URL
Resp.prompt	string	이 생성에 사용된 프롬프트
Resp.negative_prompt	string	네거티브 프롬프트
Resp.seed	integer	난수 시드
Resp.style	string	스타일
Resp.resolution_ratio	integer	동영상 선명도
Resp.outputWidth	integer	동영상 너비
Resp.outputHeight	integer	동영상 높이
Resp.size	integer	동영상 파일 크기
Resp.create_time	string	작업 생성 시간입니다.
Resp.modify_time	string	작업 업데이트 시간입니다.
tokenhub_usage	object	사용량
tokenhub_usage.total_tokens	integer	사용된 토큰 수
request_id	string	문제 해결에 사용하는 고유 요청 식별자입니다.

응답 예시

생성 성공:

LANGUAGE
{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
    "status": 1,
    "url": "https://example.com/output-video.mp4?q-sign=xxxxxx",
    "prompt": "An orange kitten on the windowsill looks toward the camera",
    "negative_prompt": "",
    "seed": 0,
    "style": "",
    "resolution_ratio": 720,
    "outputWidth": 1280,
    "outputHeight": 720,
    "size": 0,
    "create_time": "2026-07-29 15:41:31",
    "modify_time": "2026-07-29 15:42:10"
  },
  "tokenhub_usage": {
    "total_tokens": 102655
  },
  "request_id": "2524bc44-5c6f-4114-9b94-6c57eb85f54a-query-1785393236"
}

6. 상태 코드

status	설명	처리 권장 사항
`1`	생성 성공	`Resp.url`에서 결과 동영상을 가져옵니다.
`5`	생성 중	status=`1`이 될 때까지 `3~5초`마다 한 번씩 폴링합니다.
`6`	삭제됨	작업 결과가 삭제되었습니다. 작업을 다시 시작하십시오.
`7`	콘텐츠 검토 실패	프롬프트/이미지에 금지된 콘텐츠가 포함되어 있는지 확인하고 수정한 후 다시 시도하십시오.
`8`	생성 실패	서버 측 생성 오류가 발생했습니다. 요청을 다시 시도하십시오. 계속 실패하면 기술 지원팀에 문의하고 작업 ID를 제공합니다.

부록: 일반 파라미터 제한 빠른 참조

파라미터	설명
duration	`1~15`의 정수입니다(`1080p`도 최대 `15초` 지원).
aspect_ratio	텍스트-동영상 및 참조-동영상에서만 지원합니다. 값: `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `2:3` / `3:2` / `21:9`, 기본값: `16`:9. 이미지-동영상 및 시작/마지막 프레임-동영상에서는 이 파라미터를 지원하지 않으며, 출력 비율은 입력 이미지의 비율을 따릅니다.
generate_multi_clip_switch	`pixverse-video-v6.0`의 텍스트-동영상 및 이미지-동영상에서만 지원하며, 시작/마지막 프레임 및 참조-동영상에서는 지원하지 않습니다.

자주 묻는 질문

1. 두 모델 중 어떤 모델을 선택해야 합니까?

일반 시나리오 또는 다중 숏 지능형 스토리보드가 필요한 경우: pixverse-video-v6.0.
전투, 마법 효과, 고속 움직임과 같은 역동적인 장면의 경우: pixverse-video-c1.

2. 이미지-동영상, 시작/마지막 프레임 및 참조-동영상 API에 이미지를 전달하려면 어떻게 해야 합니까?

공개적으로 액세스 가능한 이미지 URL을 직접 전달할 수 있습니다. img_id(이미지-동영상), first_frame_img / last_frame_img(시작 및 마지막 프레임), image_references[].img_id(참조-동영상)는 모두 업로드 API를 먼저 호출하지 않고 이미지 URL 문자열을 받을 수 있습니다.

3. 생성된 동영상 링크에 만료 기한이 있습니까?

URL은 만료됩니다. 작업 성공 후 Resp.url에서 동영상 파일을 즉시 다운로드합니다. 유효 기간은 12시간을 초과하지 않으므로 가능한 한 빨리 다운로드하여 저장합니다.