解说视频与幻灯片

一组接口，把文本或 URL 变成带旁白的分页内容——解说、故事或演示幻灯片——并渲染成视频。

解说视频、故事视频和演示幻灯片是同一组接口的三种模式。你提交一个内容来源和一个音色，ListenHub 撰写旁白并为每一页生成画面，你可以把这些页面当作素材使用，也可以把它们渲染成带旁白的视频。

三个接口在所有模式下共用：

接口	用途
`POST /v1/storybook/episodes`	创建单集。`mode` 选择解说、故事或幻灯片
`GET /v1/storybook/episodes/{episodeId}`	轮询进度，然后读取各页与资源 URL
`POST /v1/storybook/episodes/{episodeId}/video`	把已完成的各页渲染成视频

本页所有接口都使用 OpenAPI Base URL https://api.marswave.ai/openapi，并通过 Authorization: Bearer $LISTENHUB_API_KEY 请求头用 API Key 鉴权。在 listenhub.ai/settings/api-keys 创建密钥。

选择模式

mode 可选，默认为 info。它是三种模式之间唯一不同的字段——本页其余内容对三者都适用。

`mode`	产出	第 1 页	适用场景
`info` (默认)	信息图、插画、数据可视化	杂志式封面	知识讲解、产品介绍
`story`	故事场景插画	故事封面	故事分享、案例研究
`slides`	PPT 布局（网格、流程图、大数字展示）	演讲标题页	会议演示、商业汇报、大会演讲

解说视频与故事

info 与 story 两种模式：各自画什么，以及该怎么选。

演示文稿

slides 模式：演示布局，以及如何拿到 PPT 文件。

工作流

创建单集

调用 POST /v1/storybook/episodes，传入内容来源、音色和需要的 mode。保存返回的 episodeId。

轮询等待完成

初始等待 60 秒后，每 10 秒轮询一次 GET /v1/storybook/episodes/{episodeId}，直到 processStatus 为 success。

使用素材（可选）

pages[] 中是生成的图片和旁白文稿。如果你只需要这些，到此为止即可。

渲染视频

调用 POST /v1/storybook/episodes/{episodeId}/video，把各页合成为带旁白的视频。

轮询视频状态

轮询直到 videoStatus 为 success，然后下载 videoUrl。

创建单集

POST /v1/storybook/episodes

curl -X POST "https://api.marswave.ai/openapi/v1/storybook/episodes" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {"type": "url", "content": "https://example.com/article"}
    ],
    "speakers": [
      {"speakerId": "<SPEAKER_ID>"}
    ],
    "language": "en",
    "mode": "info"
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/storybook/episodes',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sources: [{ type: 'url', content: 'https://example.com/article' }],
      speakers: [{ speakerId: '<SPEAKER_ID>' }],
      language: 'en',
      mode: 'info',
    }),
  },
)
const { data } = await response.json()
const episodeId = data.episodeId

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/storybook/episodes',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'sources': [{'type': 'url', 'content': 'https://example.com/article'}],
        'speakers': [{'speakerId': '<SPEAKER_ID>'}],
        'language': 'en',
        'mode': 'info',
    },
)
episode_id = response.json()['data']['episodeId']

响应：

{
  "code": 0,
  "message": "",
  "data": { "episodeId": "665f1d4e8b3a3f001234abcd" }
}

请求参数

参数	类型	必填	说明
`sources`	array(1)	是	内容来源。正好 1 项
`sources[].type`	string	是	`"text"` 或 `"url"`
`sources[].content`	string	是	文本内容；`type` 为 `"url"` 时则是 URL 本身
`sources[].uri`	string	否	接受但会被忽略——对 `url` 类型的来源，服务端从 `content` 推导 `uri`
`sources[].metadata`	object	否	来源元数据
`speakers`	array(1)	是¹	语音配置。最多 1 项
`speakers[].speakerId`	string	是	说话人 ID（参见音色列表）
`skipAudio`	boolean	否	默认为 `false`。为 `true` 时只产出图片和文本——不生成旁白音频
`language`	string	否	语言代码，如 `"en"`、`"zh"`。默认为 `en`——不会从来源内容推断
`mode`	string	否	`"info"`（默认）、`"story"` 或 `"slides"`
`style`	string	否	视觉风格 ID。省略即使用该模式的默认风格；可接受的 ID 不属于公开契约

¹ 除非 skipAudio 为 true，否则 speakers 必填；为 true 时可以省略。

language 不会从你的内容中检测。不传时，无论来源是什么语言都会生成英文单集，因此任何非英文来源都要显式传入。

只需要画面和文稿时，把 skipAudio: true 传上——单集上依然会返回每页图片和旁白文本，只是不做音频渲染。

轮询单集状态

GET /v1/storybook/episodes/{episodeId}

用返回的 episodeId 轮询查询，直到 processStatus 为 success。

curl "https://api.marswave.ai/openapi/v1/storybook/episodes/{episodeId}" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

响应（processStatus 为 success 时）：

{
  "code": 0,
  "message": "",
  "data": {
    "episodeId": "{episodeId}",
    "createdAt": 1700000000,
    "mode": "info",
    "processStatus": "success",
    "credits": 30,
    "title": "How AI Is Changing the World",
    "cover": "https://assets.listenhub.app/covers/{episodeId}.png",
    "audioUrl": "https://assets.listenhub.app/storybook/{episodeId}.mp3",
    "audioDuration": 180,
    "videoUrl": "",
    "videoStatus": "not_generated",
    "pages": [
      {
        "text": "Artificial intelligence has transformed industries worldwide...",
        "pageNumber": 1,
        "imageUrl": "https://assets.listenhub.app/pages/{episodeId}-1.png",
        "audioTimestamp": 0
      },
      {
        "text": "From healthcare to finance, AI applications continue to expand...",
        "pageNumber": 2,
        "imageUrl": "https://assets.listenhub.app/pages/{episodeId}-2.png",
        "audioTimestamp": 25.3
      }
    ]
  }
}

素材：pages[] 中的每一项都带有 imageUrl（生成的画面）、text（旁白文稿）和 audioTimestamp（该页在 audioUrl 中的起始位置）。下载这些素材，自己组装分页内容或二次编辑，完全不必渲染视频。

响应字段

字段	类型	说明
`episodeId`	string	你用于轮询的单集标识
`mode`	string	该单集创建时使用的模式
`processStatus`	string	见下表
`videoStatus`	string	见下表
`credits`	number	该单集到目前为止已消耗的积分
`failCode`	number	失败码，`processStatus` 为 `fail` 时出现
`message`	string	关于当前状态的可读说明
`title` / `cover`	string	生成的标题与封面图
`audioUrl` / `audioDuration`	string / number	旁白音频及其时长（秒）
`videoUrl`	string	渲染完成的视频，`videoStatus` 为 `success` 后可用
`pages[]`	array	每页的 `text`、`pageNumber`、`imageUrl`、`audioTimestamp`

积分按单集事后报告，而不是事先报价——平台如何对生成计费，见积分与定价。

processStatus

值	含义
`pending`	处理中
`success`	已完成
`fail`	失败——查看 `failCode` 和 `message`，并参见错误处理

videoStatus

值	含义
`not_generated`	未触发视频生成
`pending`	视频生成中
`success`	视频就绪（`videoUrl` 可用）
`fail`	视频生成失败

生成通常需要 2–5 分钟。推荐轮询策略：等待 60 秒后开始，每 10 秒查询一次。

渲染视频

POST /v1/storybook/episodes/{episodeId}/video

为已完成的单集触发视频生成。processStatus 必须先为 success。

curl -X POST "https://api.marswave.ai/openapi/v1/storybook/episodes/{episodeId}/video" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

响应：

{
  "code": 0,
  "message": "",
  "data": { "success": true }
}

触发后，轮询 GET /v1/storybook/episodes/{episodeId}，直到 videoStatus 为 success，然后读取 videoUrl。

选择模式

解说视频与故事

演示文稿

工作流

创建单集

轮询等待完成

使用素材（可选）

渲染视频

轮询视频状态

创建单集

请求参数

轮询单集状态

响应字段

processStatus

videoStatus

渲染视频

相关

音色列表

AI 视频

解说视频 skill

本页内容