ListenHubDocs
API 参考AI 视频

AI 视频

在 Seedance、Wan 3.0、MiniMax H3、HappyHorse、PixVerse 模型上，通过文本、图片、视频和音频输入异步生成短视频。

AI 视频接口用于异步生成短视频。先提交生成请求创建任务，再轮询任务状态，直到任务进入 success 或 failed。

Seedance、Wan 3.0、MiniMax H3 和 HappyHorse 共用一个接口 POST /v1/video-generation/generate，用 model 字段选择具体模型。PixVerse 走独立接口，请求结构也不同。五个系列产生的任务都通过同一组任务、列表、详情接口查询。

本页所有接口都使用 OpenAPI Base URL https://api.marswave.ai/openapi，并通过 Authorization: Bearer $LISTENHUB_API_KEY 请求头用 API Key 鉴权。在 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 生成，支持 1080p480p, 720p, 1080p4-15 秒
wan3.0-videoWan 3.0/v1/video-generation/generate最长 30 秒、原生同步出声的片段480p, 720p, 1080p2-30 秒
wan3.0-video-primeWan 3.0/v1/video-generation/generate能力相同，端到端速度明显更快480p, 720p, 1080p2-30 秒
MiniMax-H3MiniMax/v1/video-generation/generate原生带音轨、可单独给尾帧、支持参考音频768p, 2k4-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
wan3.0-video16:9, 4:3, 1:1, 3:4, 9:165 RPM
wan3.0-video-prime16:9, 4:3, 1:1, 3:4, 9:165 RPM
MiniMax-H316: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。Wan 3.0 除这两档外还不支持 21:9。 MiniMax-H3 是唯一接受 768p 和 2k 的模型，也是唯一不接受 480p、720p、 1080p 的模型；它拒绝 4:5 和 5:4，图生视频时更是整个忽略 ratio。 happyhorse 不支持 480p、last_frame 或 audio_url。如果请求 组合了不支持的模型、宽高比、分辨率或时长，会返回 400。

Seedance

doubao-seedance-2-pro 和 doubao-seedance-2-fast：限制与计费说明。

Wan 3.0

wan3.0-video 与 wan3.0-video-prime：最长 30 秒、原生出声，以及分档计费。

MiniMax H3

MiniMax-H3：768p 与 2k、原生音轨，以及可单独给出的尾帧。

HappyHorse

happyhorse：竖屏宽高比、参考视频编辑，以及更长的输入窗口。

PixVerse

独立接口上的九种能力模式，从对口型到营销 agent。

调用流程

共用接口覆盖 Seedance、Wan 3.0、MiniMax H3 和 HappyHorse。PixVerse 在自己的 generate 和 estimate 路径上遵循相同的三步流程，详见 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。

轮询结果

轮询 GET /v1/video-generation/tasks/{taskId}，直到 status 变为 success 或 failed。该接口对所有模型系列通用。

输入内容

content 数组接受 1-16 个元素。最多包含 1 个文本提示词、9 张图片、3 个视频和 3 个音频；MiniMax-H3 的图片上限是 5 张。该数组用于 Seedance / Wan 3.0 / MiniMax H3 / HappyHorse 共用接口；PixVerse 改用顶层的 images、videos、audios 字段。

类型必填字段role说明
texttext无最多 2500 字符。Seedance 模型会拒绝超过 1500 字符的提示词。
image_urlimage_url.urlfirst_frame, last_frame, reference_imagelast_frame 必须搭配 first_frame，MiniMax-H3 除外——它允许单独给尾帧。首尾帧角色不能和参考素材角色混用。
video_urlvideo_url.urlreference_video必须提供 inputVideoDuration。Seedance 与 MiniMax H3 接受 2-15 秒输入；HappyHorse 接受 3-60 秒输入；Wan 3.0 接受 1-15 秒输入，且 inputVideoDuration 与 duration 之和上限为 30 秒。
audio_urlaudio_url.urlreference_audio必须同时提供至少一个图片或视频输入，Wan 3.0 和 MiniMax-H3 除外——它们允许只提供提示词加参考音频。happyhorse 不支持。

图片生视频使用帧角色（first_frame，可选 last_frame）。多模态参考生视频使用参考角色（reference_image、reference_video、reference_audio）。同一次请求不能混用帧角色和参考角色。

创建视频任务

POST /v1/video-generation/generate

在 Seedance / Wan 3.0 / MiniMax H3 / 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、wan3.0-video、wan3.0-video-prime、MiniMax-H3 或 happyhorse。
contentarray是-输入内容数组。见 输入内容。
resolutionstring否720p480p、720p、1080p，以及仅 MiniMax-H3 支持的 768p、2k，受模型限制。
ratiostring否16:916:9、4:3、1:1、3:4、9:16、21:9、4:5 或 5:4，受模型限制。
durationinteger否5输出视频时长，单位秒。Seedance 与 MiniMax H3 需要 4-15 秒；Wan 3.0 接受 2-30 秒；HappyHorse 接受 3-15 秒。
generateAudioboolean否true是否同时生成音频。MiniMax-H3 忽略该字段，输出一定带音轨。
seedinteger否-1随机种子，范围 -1 到 4294967295。-1 表示随机生成。MiniMax-H3 忽略该字段。
inputVideoDurationinteger否0使用 video_url 时必填。Seedance 与 MiniMax H3 接受 2-15；HappyHorse 接受 3-60；Wan 3.0 接受 1-15，且 inputVideoDuration + duration ≤ 30。
audioSettingstring否auto视频编辑场景的音频设置。auto 生成音频；origin 保留原视频音频。

分辨率、宽高比、时长以及 inputVideoDuration 的取值范围因模型而异，逐模型规则见 Seedance、 Wan 3.0、 MiniMax H3 和 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.app/video-generation/output.mp4",
    "coverUrl": "https://assets.listenhub.app/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.app/video-generation/output.mp4",
        "coverUrl": "https://assets.listenhub.app/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 / Wan 3.0 / MiniMax H3 / 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、wan3.0-video、wan3.0-video-prime、MiniMax-H3 或 happyhorse。
resolutionstring是-480p、720p、1080p、768p 或 2k，受模型限制。
durationinteger是-输出视频时长，单位秒。
hasVideoInputboolean否false如果生成请求包含 video_url，设为 true。
inputVideoDurationinteger否0hasVideoInput 为 true 时必填。
ratiostring否16:9宽高比。

响应：

{
  "code": 0,
  "message": "",
  "data": {
    "tokens": 155520,
    "estimatedCostUsd": 0.11
  }
}

OpenAPI 的预估接口有意只返回 tokens 和 estimatedCostUsd。ListenHub 积分是内部单位， 不包含在该响应中——请通过 GET /v1/user/subscription 查询自己的余额。

错误

这些路由上的业务错误统一以 HTTP 400 返回，真实原因在响应体的数字 code 字段中。请根据 code 分支处理，而不是 HTTP 状态码。

HTTP 状态码含义
400参数错误、模型/宽高比/分辨率组合不支持、缺少媒体时长、积分不足、任务不属于你，或任务不存在。
401缺少或无效的 API Key。
429触发限流（生成接口每用户 5 RPM）。

PixVerse 在这些 HTTP 状态码之外还会返回自己的数字 code 值，详见 PixVerse 错误码。

内容审核

同步错误对象，以及任务详情或列表中的失败任务对象，可能附带可选的 contentModeration。只有确认是审核拒绝时才会出现。已有字段及其取值（包括 code、status、message）保持不变；在原有错误处理之上读取这份元数据即可。

字段类型说明
rejectedboolean固定为 true。
reasonsstring[]已知分类：political、sexual、violence、copyright、privacy。空数组表示已确认审核拒绝，但没有明确分类。
stagestringinput、output 或 unknown。
providerCodestring可选的原始错误码，不是展示文案。

原因为空或无法识别时，显示通用审核拒绝提示。展示时使用自己的简短本地化文案，不直接展示供应商错误原文。元数据示例：

{
  "contentModeration": {
    "rejected": true,
    "reasons": [],
    "stage": "unknown"
  }
}

演示文稿

slides 模式——演示布局、演讲旁白文稿，以及为什么 API 上没有 PPT 导出。

Seedance

Seedance 在共用 AI 视频生成接口上的专属模型、限制与计费说明。

本页内容

选择模型调用流程预估花费创建任务轮询结果输入内容创建视频任务文生视频图生视频视频参考请求参数查询任务查询任务列表查询参数预估积分请求参数错误内容审核