ListenHubDocs
API 参考AI 视频

PixVerse 视频

调用 PixVerse 的九种能力生成 AI 视频——文生视频、图生视频、转场、融合、风格化、模仿、对口型，以及营销 Agent。

PixVerse 支持九种能力的异步视频生成。提交生成请求后，轮询任务直到状态变为 success 或 failed。这里创建的任务，复用与 AI 视频 相同的任务详情、列表、分享、删除接口查询。

本页所有接口都使用 OpenAPI 基础地址 https://api.marswave.ai/openapi，并通过请求头 Authorization: Bearer $LISTENHUB_API_KEY 携带 API Key 鉴权。

接口

方法路径作用
POST/v1/video-generation/pixverse/generate创建 PixVerse 生成任务。
POST/v1/video-generation/pixverse/estimate-credits生成前预估积分。

服务区域由 language 决定：默认 en 走 PixVerse 国际站，zh 走国内站。PixVerse 的 provider key、内部素材 ID、trace id 和原始 provider 响应都不会返回给客户端。

能力一览

capability 必填，决定生成模式，也决定了需要哪些素材和嵌套字段。

能力作用所需输入
text_to_video仅凭文本提示词生成prompt，不传素材
image_to_video由一张或多张图片生成动态视频prompt + 1-10 张 images
transition在两张图片之间做转场恰好 2 张 images + prompt
multi_transition多段图片转场序列pixverse.multiTransition（2-7 段），不传顶层素材
fusion按引用合成主体/背景pixverse.imageReferences（1-8 个）+ 提示词包含每个 @refName
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是-上述九种能力之一。
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_transition默认 quality 为 360p。用 pixverse.multiTransition，不传顶层 images/videos/audios。
fusionprompt 必须为 pixverse.imageReferences 里的每个引用都带上对应的 @refName。
transition恰好 2 张图。
restyle需要源（sourceTaskId 或 pixverse.sourceVideoId）加 pixverse.restyleId。
lip_sync需要源视频（1 段 video 或 sourceTaskId），再加恰好一路音源——要么 1 段 audio（5-60 秒），要么 pixverse.tts，二者不能同时传。

计费

PixVerse 走 provider 积分计费：ListenHub 的积分由 provider 报价折算而来。由于成本取决于能力、清晰度、时长和素材组合，生成前请务必调用 estimate-credits，向用户展示准确的积分消耗。积分在创建任务时预扣，生成失败会自动退回。

创建 PixVerse 任务

POST /v1/video-generation/pixverse/generate

返回 taskId 和 episodeId。轮询 GET /v1/video-generation/tasks/{taskId}，直到任务状态为 success 或 failed。

文生视频

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": "雨夜霓虹街道，电影感缓慢推镜",
    "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: '雨夜霓虹街道，电影感缓慢推镜',
      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': '雨夜霓虹街道，电影感缓慢推镜',
        'quality': '720p',
        'aspectRatio': '16:9',
        'duration': 5,
    },
)
data = response.json()
print('Task ID:', data['data']['taskId'])

对口型

传一段源视频（或 sourceTaskId），再加恰好一路音源：要么一项 audios，要么 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": "zh_female_001",
        "content": "欢迎回到频道，今天我们上线了一个新功能。"
      }
    }
  }'
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: 'zh_female_001',
          content: '欢迎回到频道，今天我们上线了一个新功能。',
        },
      },
    }),
  },
)
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': 'zh_female_001',
                'content': '欢迎回到频道，今天我们上线了一个新功能。',
            }
        },
    },
)
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,
    "estimatedCostUsd": 0.11
  }
}

与共用的预估接口一样，这个接口只返回 tokens 和 estimatedCostUsd。ListenHub 积分是内部单位，不包含在 OpenAPI 响应中。

频率限制

PixVerse 生成与 AI 视频生成共用每用户 5 RPM 的限流，作用在 generate 接口上。超限返回错误码 29998（429），重试请配合指数退避。

错误码

下表中的每个错误码都以 HTTP 400 返回，数字错误码在响应体中——请根据 code 分支处理，而不是 HTTP 状态码。唯一的例外是每用户请求速率限制 29998，限流器会以真正的 429 返回。

错误码含义
32001任务不存在。
32002积分不足。
32003生成过程中 provider 报错。
32004参数无效或能力组合不被支持。
32005任务存在但不属于当前 API 用户。
32006音频输入需要至少一张图片或一段视频配合。
32007上游 provider 限流或视频并发槽位耗尽（区别于每用户请求速率限制 29998）。
32008内容被审核拦截。

HappyHorse

HappyHorse 在共用 AI 视频生成接口上的专属模型、限制与约束。

图片生成

在 Nano Banana、GPT-Image、Seedream、Wan 2.7 模型系列上，通过文本提示词和参考图同步或异步生成图片。

本页内容

接口能力一览请求参数嵌套 pixverse 对象refName 格式各能力约束计费创建 PixVerse 任务文生视频对口型预估积分频率限制错误码