ListenHubOpenAPI
API 레퍼런스AI 비디오

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/generatePixVerse 생성 작업을 만듭니다.
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

파라미터타입필수기본값설명
capabilitystring-위 아홉 가지 기능 중 하나.
modelstring아니오pixversePixVerse 모델 버전: pixverse, v6, v5, v4.5.
languagestring아니오en서비스 리전: en(국제) 또는 zh(중국).
promptstring아니오-최대 2048자. text_to_video, image_to_video, transition, fusion, agent에서는 필수.
qualitystring아니오720p360p, 540p, 720p, 1080p. multi_transition의 기본값은 360p.
aspectRatiostring아니오16:99:16, 16:9, 1:1, 4:3, 3:4. agent의 기본값은 9:16.
durationinteger아니오5출력 길이(초), 1-60. agent20, 30, 60만 허용합니다(기본값 30).
sourceTaskIdstring아니오-재사용할, 이미 성공한 PixVerse 작업(restyle / lip_sync 소스 비디오).
imagesarray아니오[]최대 10개, 각 항목은 { url, duration? }.
videosarray아니오[]최대 2개, 각 항목은 { url, duration? }.
audiosarray아니오[]최대 1개, { url, duration? }.
pixverseobject아니오{}기능별 전용 옵션. 중첩 pixverse 객체를 참고하세요.

각 에셋의 url은 필수입니다. 선택 항목인 duration은 초 단위입니다(0-180).

중첩 pixverse 객체

필드타입적용 기능설명
agentTypestringagentad_master 또는 promo_mix.
motionModestring선택모션 프리셋.
cameraMovementstring선택카메라 움직임 프리셋.
templateIdstring/number선택템플릿 식별자.
sourceVideoIdstring/numberrestyle/lip_sync제공자 측 소스 비디오 id(sourceTaskId의 대안).
restyleIdstring/numberrestyle필수 스타일 변환 스타일 id.
multiTransitionarraymulti_transition2-7 클립, 각 클립은 { imageUrl, duration (0-30), prompt }.
imageReferencesarrayfusion1-8개의 참조, 각 참조는 { type: subject|background, imageUrl, refName }.
ttsobjectlip_sync{ speakerId, content }. 합성 음성으로 립싱크를 구동합니다.
soundEffectSwitchboolean선택효과음 생성을 활성화합니다.
soundEffectContentstring선택효과음 설명.
lipSyncTtsSwitchboolean선택TTS 기반 립싱크를 활성화합니다.
lipSyncTtsSpeakerIdstring선택TTS 립싱크에 사용할 화자 id.
lipSyncTtsContentstring선택TTS 립싱크로 읽어 줄 텍스트.
brandStickerobjectagent{ imageUrl, position }. position은 up, down, left, right, upper_left, lower_left, upper_right, lower_right 중 하나입니다.
introOutroClipobjectagent{ videoUrl, position }. position은 start 또는 end입니다.

refName 형식

refName^[A-Za-z][A-Za-z0-9_]{0,31}$와 일치해야 합니다 — 영문자로 시작하고 영문자, 숫자, 밑줄만 포함합니다.

기능별 제약

생성 요청은 기능별로 검증됩니다. 가장 흔한 규칙은 다음과 같습니다:

기능제약
mimicquality720p로 고정됩니다. 이미지 정확히 1장 + 비디오 1개가 필요합니다. 비디오 길이를 지정하는 경우 5-30초여야 합니다.
agentquality720p 또는 1080p여야 하고, duration20, 30, 60 중 하나여야 합니다.
agent promo_mix제품 이미지가 최소 4장 필요합니다.
agent ad_master제품 이미지가 최소 1장 필요하며 비디오는 사용할 수 없습니다.
multi_transitionquality 기본값은 360p입니다. pixverse.multiTransition을 사용하고, 최상위 images/videos/audios는 지정하지 않습니다.
fusionprompt에는 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

taskIdepisodeId를 반환합니다. 작업이 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

작업을 만들기 전에 크레딧 비용을 예상합니다.

파라미터타입필수기본값설명
capabilitystring-아홉 가지 기능 중 하나.
modelstring아니오pixversepixverse, v6, v5, v4.5.
languagestring아니오enen(국제) 또는 zh(중국).
durationinteger아니오51-60초(agent: 20, 30, 60).
qualitystring아니오720p360p, 540p, 720p, 1080p(multi_transition: 360p).
pixverse.agentTypestring아니오-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의미
32001404작업을 찾을 수 없습니다.
32002402크레딧이 부족합니다.
32003500생성 중 제공자 오류가 발생했습니다.
32004400잘못된 파라미터이거나 지원되지 않는 기능 조합입니다.
32005403작업은 존재하지만 현재 API 사용자의 것이 아닙니다.
32006400오디오 입력에는 이미지 또는 비디오가 최소 하나 필요합니다.
32007429업스트림 제공자의 스로틀링 또는 비디오 동시 실행 슬롯 소진(사용자당 요청 레이트 리밋인 29998과는 다릅니다).
32008400콘텐츠 검수에서 거부되었습니다.

이 페이지의 내용