ListenHubOpenAPI
EN中文
API 参考

AI 视频

通过文本、图片、视频参考和音频参考创建异步 AI 视频生成任务。

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

本页所有接口都使用 OpenAPI Base URL：https://api.marswave.ai/openapi。

调用流程

预估积分

如果需要在创建前展示费用确认，先调用 POST /v1/video-generation/estimate-credits。

创建任务

调用 POST /v1/video-generation/generate。响应会返回 taskId 和 episodeId。

轮询结果

轮询 GET /v1/video-generation/tasks/{taskId}，直到 status 变为 success 或 failed。

模型与限制

模型适用场景时长分辨率宽高比限流
doubao-seedance-2-fast快速文本/图片/视频生成4-15 秒480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:92 RPM
doubao-seedance-2-pro更高质量的 Seedance 生成4-15 秒480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:92 RPM
happyhorseHappyHorse 模型工作流3-15 秒720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, 4:5, 5:45 RPM

doubao-seedance-2-fast 不支持 1080p。Seedance 模型不支持 4:5 或 5:4。happyhorse 不支持 480p、last_frame 或 audio_url。

输入内容

content 数组接受 1-16 个元素。最多包含 1 个文本提示词、9 张图片、3 个视频和 3 个音频。

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

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

创建视频任务

POST /v1/video-generation/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 表示随机生成。
inputVideoDurationinteger否0使用 video_url 时必填。Seedance 接受 2-15；HappyHorse 接受 3-60。
audioSettingstring否auto视频编辑场景的音频设置。auto 生成音频；origin 保留原视频音频。

查询任务

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

轮询任务详情接口，直到任务进入终态。

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

在创建任务前预估积分消耗。

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触发限流。

On this page

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