ListenHubOpenAPI
API リファレンスAI 動画

PixVerse 動画

PixVerse の AI 動画タスクを 9 つの能力で作成します——テキストから動画、画像から動画、トランジション、フュージョン、スタイル変換、モーション模倣、リップシンク、マーケティング agent。

PixVerse は 9 つの能力でショート動画を非同期に生成します。生成リクエストを送信し、success または failed になるまでタスクをポーリングします。ここで作成したタスクは、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 の provider キー、内部メディア ID、trace ID、provider の生レスポンスがクライアントに返ることはありません。

能力一覧

capability は必須です。生成モードを選び、どの素材とネストされたフィールドが必要かを決めます。

能力内容必要な入力
text_to_videoテキストプロンプトのみから生成prompt、素材は不要
image_to_video1 枚以上の画像を動かすprompt + 1-10 枚の images
transition2 枚の画像の間でトランジションちょうど 2 枚の images + prompt
multi_transition複数クリップのトランジション列pixverse.multiTransition（2-7 クリップ）、トップレベルの素材は不要
fusion参照によって被写体／背景を合成pixverse.imageReferences（1-8 個）+ 各 @refName を含む prompt
restyle既存の PixVerse 動画をスタイル変換sourceTaskId（または pixverse.sourceVideoId）+ pixverse.restyleId、素材は不要
mimicモーション動画を被写体画像に適用ちょうど 1 つの image + 1 つの video
lip_sync動画を音声または TTS にリップシンク1 つの video（または sourceTaskId）+ 1 つの audio または pixverse.tts
agentマーケティング agent（ad_master / promo_mix）pixverse.agentType + 商品画像

リクエストパラメータ

POST /v1/video-generation/pixverse/generate

パラメータ型必須デフォルト説明
capabilitystringはい-上記 9 つの能力のいずれか。
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。agent は 20、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_syncprovider のソース動画 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}$ にマッチする必要があります。先頭は英字で、英字・数字・アンダースコアのみを含みます。

能力ごとの制約

生成リクエストは能力ごとに検証されます。主なルールは次のとおりです：

能力制約
mimicquality は 720p に固定されます。ちょうど 1 枚の画像 + 1 本の動画が必要です。動画の長さを指定する場合は 5-30 秒。
agentquality は 720p または 1080p、duration は 20、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ソース動画（1 本の video または sourceTaskId）に加えて、音源をちょうど 1 つ——1 本の audio（5-60 秒）か pixverse.tts のどちらか一方で、両方は指定できません。

料金

PixVerse は provider クレジットベースの料金モデルを採用しています。ListenHub のクレジットは provider の提示コストから換算されます。コストは能力、画質、長さ、素材の組み合わせによって変わるため、正確なコストをユーザーに提示するには必ず 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）と、音源をちょうど 1 つ——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はい-9 つの能力のいずれか。
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生成中に provider がエラーを返しました。
32004400パラメータが不正、または能力の組み合わせが未対応です。
32005403タスクは存在しますが、現在の API ユーザーのものではありません。
32006400音声入力には画像または動画が最低 1 つ必要です。
32007429上流 provider のスロットリング、または動画の同時実行スロットの枯渇（ユーザーごとのリクエストレート制限 29998 とは別です）。
32008400コンテンツがモデレーションで拒否されました。

このページの内容

エンドポイント能力一覧リクエストパラメータネストされた pixverse オブジェクトrefName の形式能力ごとの制約料金PixVerse タスクを作成するテキストから動画リップシンククレジットを見積もるレート制限エラーコード