AI 视频

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

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

Seedance 和 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`, `720p`	4-15 秒
`doubao-seedance-2-pro`	Seedance	`/v1/video-generation/generate`	更高质量的 Seedance 生成，支持 `1080p`	`480p`, `720p`, `1080p`	4-15 秒
`happyhorse`	HappyHorse	`/v1/video-generation/generate`	参考视频编辑、竖屏宽高比、更长的参考片段	`720p`, `1080p`	3-15 秒
`pixverse`	PixVerse	`/v1/video-generation/pixverse/generate`	九种能力模式：转场、融合、风格化、动作迁移、对口型、营销 agent	`360p`, `540p`, `720p`, `1080p`	1-60 秒

在共用接口上省略 model 时默认使用 doubao-seedance-2-fast。PixVerse 在共用接口上没有自己的 model 默认值——它通过专属的 pixverse/generate 路径访问，并在该接口自己的 model 字段中选择版本（pixverse、v6、v5、v4.5）。

模型	宽高比	限流
`doubao-seedance-2-fast`	`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`	5 RPM
`doubao-seedance-2-pro`	`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`	5 RPM
`happyhorse`	`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `4:5`, `5:4`	5 RPM
`pixverse`	`9:16`, `16:9`, `1:1`, `4:3`, `3:4`	5 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 路径上遵循相同的三步流程，详见 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 个音频。该数组用于 Seedance / HappyHorse 共用接口；PixVerse 改用顶层的 images、videos、audios 字段。

类型	必填字段	role	说明
`text`	`text`	无	最多 2500 字符。Seedance 模型最多 500 字符。
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	`last_frame` 必须搭配 `first_frame`。首尾帧角色不能和参考素材角色混用。
`video_url`	`video_url.url`	`reference_video`	必须提供 `inputVideoDuration`。Seedance 接受 2-15 秒输入；HappyHorse 接受 3-60 秒输入。
`audio_url`	`audio_url.url`	`reference_audio`	必须同时提供至少一个图片或视频输入。`happyhorse` 不支持。

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

创建视频任务

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"
  }'

请求参数

参数	类型	必填	默认值	说明
`model`	string	否	`doubao-seedance-2-fast`	`doubao-seedance-2-pro`、`doubao-seedance-2-fast` 或 `happyhorse`。
`content`	array	是	-	输入内容数组。见输入内容。
`resolution`	string	否	`720p`	`480p`、`720p` 或 `1080p`，受模型限制。
`ratio`	string	否	`16:9`	`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`4:5` 或 `5:4`，受模型限制。
`duration`	integer	否	`5`	输出视频时长，单位秒。Seedance 需要 4-15 秒；HappyHorse 接受 3-15 秒。
`generateAudio`	boolean	否	`true`	是否同时生成音频。
`seed`	integer	否	`-1`	随机种子，范围 `-1` 到 `4294967295`。`-1` 表示随机生成。
`inputVideoDuration`	integer	否	`0`	使用 `video_url` 时必填。Seedance 接受 2-15；HappyHorse 接受 3-60。
`audioSetting`	string	否	`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"

查询参数

参数	类型	必填	默认值	说明
`page`	integer	否	`1`	页码。
`pageSize`	integer	否	`20`	每页数量，最大 100。
`status`	string	否	-	可选过滤：`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"
  }'

请求参数

参数	类型	必填	默认值	说明
`model`	string	是	-	`doubao-seedance-2-pro`、`doubao-seedance-2-fast` 或 `happyhorse`。
`resolution`	string	是	-	`480p`、`720p` 或 `1080p`，受模型限制。
`duration`	integer	是	-	输出视频时长，单位秒。
`hasVideoInput`	boolean	否	`false`	如果生成请求包含 `video_url`，设为 `true`。
`inputVideoDuration`	integer	否	`0`	`hasVideoInput` 为 `true` 时必填。
`ratio`	string	否	`16:9`	宽高比。

响应：

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

错误

HTTP 状态码	含义
`400`	参数错误、模型/宽高比/分辨率组合不支持，或缺少必需的参考视频时长。
`402`	积分不足。
`403`	任务存在，但不属于当前 API 用户。
`404`	任务不存在。
`429`	触发限流（生成接口每用户 5 RPM）。

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

Seedance

HappyHorse

PixVerse

On this page