ListenHubOpenAPI
API 레퍼런스AI 비디오

AI 비디오

텍스트, 이미지, 비디오, 오디오 입력으로 Seedance, HappyHorse, PixVerse 모델에서 짧은 AI 비디오를 비동기로 생성합니다.

AI 비디오 API는 짧은 비디오를 비동기로 생성합니다. 먼저 생성 요청을 보내고, 작업이 success 또는 failed에 도달할 때까지 폴링(polling)하세요.

Seedance와 HappyHorse는 하나의 엔드포인트 POST /v1/video-generation/generate를 공유하며, model 필드로 모델을 선택합니다. PixVerse는 전용 엔드포인트를 사용하고 요청 구조도 다릅니다. 세 시리즈에서 만들어진 작업은 모두 동일한 작업 조회, 목록, 상세 엔드포인트로 읽어 옵니다.

이 페이지의 모든 엔드포인트는 OpenAPI Base URL https://api.marswave.ai/openapi를 사용하며, Authorization: Bearer $LISTENHUB_API_KEY 헤더로 API 키를 인증합니다. 키는 listenhub.ai/settings/api-keys에서 만드세요.

모델 선택

세 시리즈에 걸쳐 네 개의 모델이 있습니다. 아래 표에서 하나를 고른 다음, 해당 모델 페이지에서 정확한 제한과 요금 관련 참고 사항을 확인하세요.

모델시리즈생성 엔드포인트적합한 용도해상도길이
doubao-seedance-2-fast (기본값)Seedance/v1/video-generation/generate빠른 텍스트 / 이미지 / 비디오 생성480p, 720p4-15초
doubao-seedance-2-proSeedance/v1/video-generation/generate더 높은 품질의 Seedance 생성, 1080p까지 지원480p, 720p, 1080p4-15초
happyhorseHappyHorse/v1/video-generation/generate참조 비디오 편집, 세로 화면 비율, 더 긴 참조 클립720p, 1080p3-15초
pixversePixVerse/v1/video-generation/pixverse/generate아홉 가지 기능 모드: 전환, 융합, 스타일 변환, 동작 모방, 립싱크, 마케팅 agent360p, 540p, 720p, 1080p1-60초

공유 엔드포인트에서 model을 생략하면 doubao-seedance-2-fast가 기본값입니다. PixVerse는 공유 엔드포인트에서 자체 model 기본값을 갖지 않습니다. 전용 pixverse/generate 경로로 접근한 다음, 그 엔드포인트의 자체 model 필드에서 버전(pixverse, v6, v5, v4.5)을 선택합니다.

모델화면 비율레이트 리밋
doubao-seedance-2-fast16:9, 4:3, 1:1, 3:4, 9:16, 21:95 RPM
doubao-seedance-2-pro16:9, 4:3, 1:1, 3:4, 9:16, 21:95 RPM
happyhorse16:9, 4:3, 1:1, 3:4, 9:16, 21:9, 4:5, 5:45 RPM
pixverse9:16, 16:9, 1:1, 4:3, 3:45 RPM

모델마다 제한이 다릅니다. doubao-seedance-2-fast는 1080p를 지원하지 않습니다. Seedance 모델은 4:5와 5:4를 지원하지 않습니다. happyhorse는 480p, last_frame, audio_url을 지원하지 않습니다. 지원되지 않는 모델, 화면 비율, 해상도, 길이를 조합한 요청은 400을 반환합니다.

Seedance

doubao-seedance-2-pro와 doubao-seedance-2-fast: 제한과 요금 관련 참고 사항.

HappyHorse

happyhorse: 세로 화면 비율, 참조 비디오 편집, 더 긴 입력 윈도우.

PixVerse

전용 엔드포인트에서 제공하는 아홉 가지 기능 모드, 립싱크부터 마케팅 agent까지.

호출 흐름

공유 엔드포인트는 Seedance와 HappyHorse를 담당합니다. PixVerse도 자체 generate / estimate 경로에서 동일한 3단계 흐름을 따릅니다. PixVerse 페이지를 참고하세요.

크레딧 예상

생성 전에 비용 확인 화면을 보여줘야 한다면 POST /v1/video-generation/estimate-credits(PixVerse는 POST /v1/video-generation/pixverse/estimate-credits)를 호출하세요.

작업 생성

POST /v1/video-generation/generate(PixVerse는 POST /v1/video-generation/pixverse/generate)를 호출합니다. 응답으로 taskId와 episodeId가 반환됩니다.

결과 폴링

status가 success 또는 failed가 될 때까지 GET /v1/video-generation/tasks/{taskId}를 폴링합니다. 이 엔드포인트는 모든 모델 시리즈에 공통으로 사용됩니다.

입력 콘텐츠

content 배열은 1-16개의 요소를 받습니다. 텍스트 프롬프트는 최대 1개, 이미지는 최대 9장, 비디오는 최대 3개, 오디오 파일은 최대 3개까지 포함할 수 있습니다. 이 배열은 Seedance / HappyHorse 공유 엔드포인트에 적용됩니다. PixVerse는 대신 최상위 images, videos, audios 필드를 사용합니다.

유형필수 필드role비고
texttext없음최대 2500자. Seedance 모델은 최대 500자까지 허용합니다.
image_urlimage_url.urlfirst_frame, last_frame, reference_imagelast_frame을 쓰려면 first_frame이 필요합니다. 프레임 role과 참조 role은 섞어 쓸 수 없습니다.
video_urlvideo_url.urlreference_videoinputVideoDuration이 필요합니다. Seedance는 2-15초, HappyHorse는 3-60초 입력을 허용합니다.
audio_urlaudio_url.urlreference_audio이미지 또는 비디오 요소가 최소 하나 필요합니다. happyhorse는 지원하지 않습니다.

이미지에서 비디오를 만들 때는 프레임 role(first_frame, 선택적으로 last_frame)을 사용하세요. 멀티모달 참조 생성에는 참조 role(reference_image, reference_video, reference_audio)을 사용하세요. 한 번의 요청에서 프레임 role과 참조 role을 섞어 쓰지 마세요.

비디오 작업 생성

POST /v1/video-generation/generate

Seedance / HappyHorse 공유 엔드포인트에서 비동기 비디오 생성 작업을 만듭니다. 크레딧은 작업 생성 시점에 차감되며, 생성에 실패하면 자동으로 환불됩니다. PixVerse는 POST /v1/video-generation/pixverse/generate를 사용하세요.

텍스트에서 비디오

curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/generate" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-fast",
    "content": [
      {
        "type": "text",
        "text": "A cinematic aerial shot of a quiet coastal city at sunrise"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generateAudio": true
  }'
const response = await fetch(
  'https://api.marswave.ai/openapi/v1/video-generation/generate',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'doubao-seedance-2-fast',
      content: [
        {
          type: 'text',
          text: 'A cinematic aerial shot of a quiet coastal city at sunrise',
        },
      ],
      resolution: '720p',
      ratio: '16:9',
      duration: 5,
      generateAudio: true,
    }),
  },
)
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/generate',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'model': 'doubao-seedance-2-fast',
        'content': [
            {
                'type': 'text',
                'text': 'A cinematic aerial shot of a quiet coastal city at sunrise',
            }
        ],
        'resolution': '720p',
        'ratio': '16:9',
        'duration': 5,
        'generateAudio': True,
    },
)
data = response.json()
print('Task ID:', data['data']['taskId'])

응답:

{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "665f1d4e8b3a3f001234abcd",
    "episodeId": "665f1d4e8b3a3f001234abce",
    "status": "generating"
  }
}

이미지에서 비디오

이미지 한 장에서 시작하려면 first_frame을 사용하세요. 마지막 프레임을 제어하고 싶을 때만 last_frame을 추가하세요.

curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/generate" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-pro",
    "content": [
      {
        "type": "text",
        "text": "The camera slowly pushes in while mist moves through the scene"
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {
          "url": "https://example.com/start-frame.jpg"
        }
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

비디오 참조

content에 video_url이 포함되면 inputVideoDuration에 참조 비디오의 길이를 초 단위로 지정하세요.

curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/generate" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "content": [
      {
        "type": "text",
        "text": "Restyle the subject as a polished product launch clip"
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://example.com/reference.mp4"
        }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://example.com/style-reference.jpg"
        }
      }
    ],
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5,
    "inputVideoDuration": 8,
    "audioSetting": "auto"
  }'

요청 파라미터

파라미터타입필수기본값설명
modelstring아니오doubao-seedance-2-fastdoubao-seedance-2-pro, doubao-seedance-2-fast 또는 happyhorse.
contentarray예-입력 요소 배열. 입력 콘텐츠 참고.
resolutionstring아니오720p480p, 720p 또는 1080p. 모델 제한을 따릅니다.
ratiostring아니오16:916:9, 4:3, 1:1, 3:4, 9:16, 21:9, 4:5 또는 5:4. 모델 제한을 따릅니다.
durationinteger아니오5출력 길이(초). Seedance는 4-15, HappyHorse는 3-15를 허용합니다.
generateAudioboolean아니오true비디오와 함께 오디오를 생성할지 여부.
seedinteger아니오-1랜덤 시드, -1부터 4294967295까지. -1이면 랜덤 생성.
inputVideoDurationinteger아니오0video_url을 사용할 때 필수. Seedance는 2-15, HappyHorse는 3-60을 허용합니다.
audioSettingstring아니오auto비디오 편집 워크플로에서 사용. auto는 오디오를 생성하고, origin은 원본 비디오 오디오를 유지합니다.

해상도, 화면 비율, 길이, inputVideoDuration의 제한은 모델마다 다릅니다. 모델별 규칙은 Seedance와 HappyHorse를 참고하세요.

작업 조회

GET /v1/video-generation/tasks/{taskId}

작업이 종료 상태에 이를 때까지 작업 상세 엔드포인트를 폴링하세요. 이 엔드포인트는 PixVerse를 포함한 모든 모델 시리즈의 작업을 반환합니다.

curl "https://api.marswave.ai/openapi/v1/video-generation/tasks/{taskId}" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

작업 상태:

상태의미
pending작업이 생성되어 제출을 기다리는 중입니다.
generating모델 제공자가 생성을 진행하는 중입니다.
uploading제공자 결과물이 준비되어 ListenHub가 저장하는 중입니다.
success비디오가 준비되었습니다. 저장된 결과물은 videoUrl을 사용하세요.
failed생성에 실패했습니다. 해당하는 경우 크레딧은 자동으로 환불됩니다.

응답:

{
  "code": 0,
  "message": "",
  "data": {
    "id": "665f1d4e8b3a3f001234abcd",
    "taskId": "665f1d4e8b3a3f001234abcd",
    "episodeId": "665f1d4e8b3a3f001234abce",
    "status": "success",
    "model": "doubao-seedance-2-fast",
    "params": {
      "content": [
        {
          "type": "text",
          "text": "A cinematic aerial shot of a quiet coastal city at sunrise"
        }
      ],
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5,
      "generateAudio": true,
      "seed": -1
    },
    "videoUrl": "https://assets.listenhub.ai/video-generation/output.mp4",
    "coverUrl": "https://assets.listenhub.ai/video-generation/cover.jpg",
    "providerVideoUrl": "https://provider.example/video.mp4",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "seed": 123456,
    "creditCharged": 12,
    "enabledShare": false,
    "createdAt": 1700000000000,
    "updatedAt": 1700000300000
  }
}

작업 목록 조회

GET /v1/video-generation/tasks

현재 API 사용자의 비디오 생성 작업을 최신순으로 조회합니다. 모든 모델 시리즈의 작업이 같은 목록에 나타납니다.

curl "https://api.marswave.ai/openapi/v1/video-generation/tasks?page=1&pageSize=20&status=success" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

쿼리 파라미터

파라미터타입필수기본값설명
pageinteger아니오1페이지 번호.
pageSizeinteger아니오20페이지당 항목 수, 최대 100.
statusstring아니오-선택 필터: pending, generating, uploading, success 또는 failed.

응답:

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "665f1d4e8b3a3f001234abcd",
        "episodeId": "665f1d4e8b3a3f001234abce",
        "status": "success",
        "model": "doubao-seedance-2-fast",
        "title": "A cinematic aerial shot of a quiet coastal city at sunrise",
        "prompt": "A cinematic aerial shot of a quiet coastal city at sunrise",
        "params": {
          "content": [],
          "resolution": "720p",
          "ratio": "16:9",
          "duration": 5,
          "generateAudio": true,
          "seed": -1
        },
        "videoUrl": "https://assets.listenhub.ai/video-generation/output.mp4",
        "coverUrl": "https://assets.listenhub.ai/video-generation/cover.jpg",
        "providerVideoUrl": "https://provider.example/video.mp4",
        "seed": 123456,
        "creditCharged": 12,
        "createdAt": 1700000000000
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

크레딧 예상

POST /v1/video-generation/estimate-credits

Seedance / HappyHorse 공유 엔드포인트에서 작업을 만들기 전에 크레딧 소비량을 예상합니다. PixVerse에는 자체 예상 엔드포인트 POST /v1/video-generation/pixverse/estimate-credits가 있습니다. 크레딧 소비량은 고정되어 있지 않습니다. 사용할 파라미터의 정확한 값을 확인하려면 반드시 대응하는 예상 엔드포인트를 호출하세요.

curl -X POST "https://api.marswave.ai/openapi/v1/video-generation/estimate-credits" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-fast",
    "resolution": "720p",
    "duration": 5,
    "hasVideoInput": false,
    "ratio": "16:9"
  }'

요청 파라미터

파라미터타입필수기본값설명
modelstring예-doubao-seedance-2-pro, doubao-seedance-2-fast 또는 happyhorse.
resolutionstring예-480p, 720p 또는 1080p. 모델 제한을 따릅니다.
durationinteger예-출력 길이(초).
hasVideoInputboolean아니오false생성 요청에 video_url이 포함되면 true로 설정합니다.
inputVideoDurationinteger아니오0hasVideoInput이 true일 때 필수.
ratiostring아니오16:9화면 비율.

응답:

{
  "code": 0,
  "message": "",
  "data": {
    "tokens": 155520,
    "credits": 12
  }
}

에러

HTTP 상태 코드의미
400잘못된 파라미터, 지원되지 않는 모델/화면 비율/해상도 조합, 또는 필수 미디어 길이 누락.
402크레딧 부족.
403작업은 존재하지만 현재 API 사용자의 것이 아닙니다.
404작업을 찾을 수 없습니다.
429레이트 리밋 초과(생성 엔드포인트에서 사용자당 5 RPM).

PixVerse는 이 HTTP 상태 코드와 함께 자체 숫자 code 값을 반환합니다. PixVerse 에러 코드를 참고하세요.

설명 영상

모든 콘텐츠를 AI가 생성한 비주얼과 음성 내레이션이 포함된 설명 영상으로 변환합니다.

Seedance

공유 AI 비디오 생성 엔드포인트에서 쓰는 Seedance 전용 모델, 제한, 요금 관련 참고 사항.

이 페이지의 내용

모델 선택호출 흐름크레딧 예상작업 생성결과 폴링입력 콘텐츠비디오 작업 생성텍스트에서 비디오이미지에서 비디오비디오 참조요청 파라미터작업 조회작업 목록 조회쿼리 파라미터크레딧 예상요청 파라미터에러