PixVerse 비디오
텍스트에서 비디오, 이미지에서 비디오, 전환, 융합, 스타일 변환, 동작 모방, 립싱크, 마케팅 agent까지 아홉 가지 기능으로 PixVerse AI 비디오 작업을 만듭니다.
PixVerse는 아홉 가지 기능으로 짧은 비디오를 비동기로 생성합니다. 생성 요청을 보낸 다음, 작업이 success 또는 failed에 도달할 때까지 폴링(polling)하세요. 여기서 만들어진 작업은 AI 비디오와 동일한 작업 조회, 목록, 공유, 삭제 엔드포인트로 읽어 옵니다.
이 페이지의 모든 엔드포인트는 OpenAPI Base URL
https://api.marswave.ai/openapi를 사용하며,
Authorization: Bearer $LISTENHUB_API_KEY 헤더로 API 키를 인증합니다.
엔드포인트
| 메서드 | 경로 | 용도 |
|---|---|---|
POST | /v1/video-generation/pixverse/generate | PixVerse 생성 작업을 만듭니다. |
POST | /v1/video-generation/pixverse/estimate-credits | 생성 전에 크레딧을 예상합니다. |
리전 라우팅은 language를 따릅니다. 기본값 en은 PixVerse 국제 서비스를,
zh는 중국 서비스를 사용합니다. PixVerse 제공자 키, 내부 미디어 ID, 트레이스
ID, 제공자 원본 응답은 클라이언트에 반환되지 않습니다.
기능
capability는 필수입니다. 생성 모드를 선택하고, 어떤 에셋과 중첩 필드가 필요한지를 결정합니다.
| 기능 | 내용 | 필수 입력 |
|---|---|---|
text_to_video | 텍스트 프롬프트만으로 생성 | prompt, 에셋 불필요 |
image_to_video | 이미지 1장 이상을 움직이게 함 | prompt + images 1-10장 |
transition | 이미지 2장 사이의 전환 | 정확히 2장의 images + prompt |
multi_transition | 여러 클립의 전환 시퀀스 | pixverse.multiTransition(2-7 클립), 최상위 에셋 불필요 |
fusion | 참조로 피사체/배경을 합성 | pixverse.imageReferences(1-8개) + 각 @refName을 포함한 prompt |
restyle | 기존 PixVerse 비디오의 스타일 변환 | sourceTaskId(또는 pixverse.sourceVideoId) + pixverse.restyleId, 에셋 불필요 |
mimic | 모션 비디오를 피사체 이미지에 적용 | 정확히 image 1개 + video 1개 |
lip_sync | 비디오를 오디오 또는 TTS에 립싱크 | video 1개(또는 sourceTaskId) + audio 1개 또는 pixverse.tts |
agent | 마케팅 agent(ad_master / promo_mix) | pixverse.agentType + 제품 이미지 |
요청 파라미터
POST /v1/video-generation/pixverse/generate
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
capability | string | 예 | - | 위 아홉 가지 기능 중 하나. |
model | string | 아니오 | pixverse | PixVerse 모델 버전: pixverse, v6, v5, v4.5. |
language | string | 아니오 | en | 서비스 리전: en(국제) 또는 zh(중국). |
prompt | string | 아니오 | - | 최대 2048자. text_to_video, image_to_video, transition, fusion, agent에서는 필수. |
quality | string | 아니오 | 720p | 360p, 540p, 720p, 1080p. multi_transition의 기본값은 360p. |
aspectRatio | string | 아니오 | 16:9 | 9:16, 16:9, 1:1, 4:3, 3:4. agent의 기본값은 9:16. |
duration | integer | 아니오 | 5 | 출력 길이(초), 1-60. agent는 20, 30, 60만 허용합니다(기본값 30). |
sourceTaskId | string | 아니오 | - | 재사용할, 이미 성공한 PixVerse 작업(restyle / lip_sync 소스 비디오). |
images | array | 아니오 | [] | 최대 10개, 각 항목은 { url, duration? }. |
videos | array | 아니오 | [] | 최대 2개, 각 항목은 { url, duration? }. |
audios | array | 아니오 | [] | 최대 1개, { url, duration? }. |
pixverse | object | 아니오 | {} | 기능별 전용 옵션. 중첩 pixverse 객체를 참고하세요. |
각 에셋의 url은 필수입니다. 선택 항목인 duration은 초 단위입니다(0-180).
중첩 pixverse 객체
| 필드 | 타입 | 적용 기능 | 설명 |
|---|---|---|---|
agentType | string | agent | ad_master 또는 promo_mix. |
motionMode | string | 선택 | 모션 프리셋. |
cameraMovement | string | 선택 | 카메라 움직임 프리셋. |
templateId | string/number | 선택 | 템플릿 식별자. |
sourceVideoId | string/number | restyle/lip_sync | 제공자 측 소스 비디오 id(sourceTaskId의 대안). |
restyleId | string/number | restyle | 필수 스타일 변환 스타일 id. |
multiTransition | array | multi_transition | 2-7 클립, 각 클립은 { imageUrl, duration (0-30), prompt }. |
imageReferences | array | fusion | 1-8개의 참조, 각 참조는 { type: subject|background, imageUrl, refName }. |
tts | object | lip_sync | { speakerId, content }. 합성 음성으로 립싱크를 구동합니다. |
soundEffectSwitch | boolean | 선택 | 효과음 생성을 활성화합니다. |
soundEffectContent | string | 선택 | 효과음 설명. |
lipSyncTtsSwitch | boolean | 선택 | TTS 기반 립싱크를 활성화합니다. |
lipSyncTtsSpeakerId | string | 선택 | TTS 립싱크에 사용할 화자 id. |
lipSyncTtsContent | string | 선택 | TTS 립싱크로 읽어 줄 텍스트. |
brandSticker | object | agent | { imageUrl, position }. position은 up, down, left, right, upper_left, lower_left, upper_right, lower_right 중 하나입니다. |
introOutroClip | object | agent | { videoUrl, position }. position은 start 또는 end입니다. |
refName 형식
refName은 ^[A-Za-z][A-Za-z0-9_]{0,31}$와 일치해야 합니다 — 영문자로 시작하고 영문자, 숫자, 밑줄만 포함합니다.
기능별 제약
생성 요청은 기능별로 검증됩니다. 가장 흔한 규칙은 다음과 같습니다:
| 기능 | 제약 |
|---|---|
mimic | quality는 720p로 고정됩니다. 이미지 정확히 1장 + 비디오 1개가 필요합니다. 비디오 길이를 지정하는 경우 5-30초여야 합니다. |
agent | quality는 720p 또는 1080p여야 하고, duration은 20, 30, 60 중 하나여야 합니다. |
agent promo_mix | 제품 이미지가 최소 4장 필요합니다. |
agent ad_master | 제품 이미지가 최소 1장 필요하며 비디오는 사용할 수 없습니다. |
multi_transition | quality 기본값은 360p입니다. pixverse.multiTransition을 사용하고, 최상위 images/videos/audios는 지정하지 않습니다. |
fusion | prompt에는 pixverse.imageReferences의 모든 항목에 대응하는 @refName이 포함되어야 합니다. |
transition | 이미지는 정확히 2장. |
restyle | 소스(sourceTaskId 또는 pixverse.sourceVideoId)와 pixverse.restyleId가 필요합니다. |
lip_sync | 소스 비디오(video 1개 또는 sourceTaskId)와 오디오 소스 정확히 하나가 필요합니다 — audio 1개(5-60초)이거나 pixverse.tts이며, 둘 다는 안 됩니다. |
요금
PixVerse는 제공자 크레딧 기반 요금 모델을 사용합니다. ListenHub 크레딧은 제공자가 제시한 비용에서 환산됩니다. 비용은 기능, 화질, 길이, 에셋 조합에 따라 달라지므로, 사용자에게 정확한 비용을 보여주려면 항상 generate 전에 estimate-credits를 호출하세요. 크레딧은 작업 생성 시점에 차감되며, 생성에 실패하면 자동으로 환불됩니다.
PixVerse 작업 생성
POST /v1/video-generation/pixverse/generate
taskId와 episodeId를 반환합니다. 작업이 success 또는 failed가 될 때까지 GET /v1/video-generation/tasks/{taskId}를 폴링하세요.
텍스트에서 비디오
curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/pixverse/generate" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"capability": "text_to_video",
"model": "pixverse",
"language": "en",
"prompt": "A neon-lit street in the rain, cinematic slow dolly shot",
"quality": "720p",
"aspectRatio": "16:9",
"duration": 5
}'const response = await fetch(
'https://api.marswave.ai/openapi/v1/video-generation/pixverse/generate',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
capability: 'text_to_video',
model: 'pixverse',
language: 'en',
prompt: 'A neon-lit street in the rain, cinematic slow dolly shot',
quality: '720p',
aspectRatio: '16:9',
duration: 5,
}),
},
)
const data = await response.json()
console.log('Task ID:', data.data.taskId)import os
import requests
response = requests.post(
'https://api.marswave.ai/openapi/v1/video-generation/pixverse/generate',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'capability': 'text_to_video',
'model': 'pixverse',
'language': 'en',
'prompt': 'A neon-lit street in the rain, cinematic slow dolly shot',
'quality': '720p',
'aspectRatio': '16:9',
'duration': 5,
},
)
data = response.json()
print('Task ID:', data['data']['taskId'])립싱크
소스 비디오 1개(또는 sourceTaskId)와 오디오 소스 정확히 하나를 제공하세요. audios 항목 1개이거나 pixverse.tts입니다.
curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/pixverse/generate" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"capability": "lip_sync",
"quality": "720p",
"videos": [
{ "url": "https://example.com/talking-head.mp4", "duration": 12 }
],
"pixverse": {
"tts": {
"speakerId": "en_male_001",
"content": "Welcome back to the channel. Today we are shipping something new."
}
}
}'const response = await fetch(
'https://api.marswave.ai/openapi/v1/video-generation/pixverse/generate',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
capability: 'lip_sync',
quality: '720p',
videos: [
{ url: 'https://example.com/talking-head.mp4', duration: 12 },
],
pixverse: {
tts: {
speakerId: 'en_male_001',
content:
'Welcome back to the channel. Today we are shipping something new.',
},
},
}),
},
)
const data = await response.json()
console.log('Task ID:', data.data.taskId)import os
import requests
response = requests.post(
'https://api.marswave.ai/openapi/v1/video-generation/pixverse/generate',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'capability': 'lip_sync',
'quality': '720p',
'videos': [
{'url': 'https://example.com/talking-head.mp4', 'duration': 12}
],
'pixverse': {
'tts': {
'speakerId': 'en_male_001',
'content': 'Welcome back to the channel. Today we are shipping something new.',
}
},
},
)
data = response.json()
print('Task ID:', data['data']['taskId'])응답:
{
"code": 0,
"message": "",
"data": {
"taskId": "665f1d4e8b3a3f001234abcd",
"episodeId": "665f1d4e8b3a3f001234abce",
"status": "generating"
}
}크레딧 예상
POST /v1/video-generation/pixverse/estimate-credits
작업을 만들기 전에 크레딧 비용을 예상합니다.
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
capability | string | 예 | - | 아홉 가지 기능 중 하나. |
model | string | 아니오 | pixverse | pixverse, v6, v5, v4.5. |
language | string | 아니오 | en | en(국제) 또는 zh(중국). |
duration | integer | 아니오 | 5 | 1-60초(agent: 20, 30, 60). |
quality | string | 아니오 | 720p | 360p, 540p, 720p, 1080p(multi_transition: 360p). |
pixverse.agentType | string | 아니오 | - | ad_master 또는 promo_mix(agent에서는 필수). |
curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/pixverse/estimate-credits" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"capability": "text_to_video",
"model": "pixverse",
"quality": "720p",
"duration": 5
}'응답:
{
"code": 0,
"message": "",
"data": {
"tokens": 155520,
"credits": 12
}
}레이트 리밋
PixVerse 생성은 generate 엔드포인트에서 사용자당 5 RPM인 AI 비디오 생성 레이트 리밋을 공유합니다. 이를 초과하면 에러 29998(429)이 반환됩니다. 재시도에는 지수 백오프를 구현하세요.
에러 코드
| 코드 | HTTP | 의미 |
|---|---|---|
32001 | 404 | 작업을 찾을 수 없습니다. |
32002 | 402 | 크레딧이 부족합니다. |
32003 | 500 | 생성 중 제공자 오류가 발생했습니다. |
32004 | 400 | 잘못된 파라미터이거나 지원되지 않는 기능 조합입니다. |
32005 | 403 | 작업은 존재하지만 현재 API 사용자의 것이 아닙니다. |
32006 | 400 | 오디오 입력에는 이미지 또는 비디오가 최소 하나 필요합니다. |
32007 | 429 | 업스트림 제공자의 스로틀링 또는 비디오 동시 실행 슬롯 소진(사용자당 요청 레이트 리밋인 29998과는 다릅니다). |
32008 | 400 | 콘텐츠 검수에서 거부되었습니다. |