OpenAPI 接入指南

• 以下文档面向企业开发者和产品经理，介绍 ListenHub 音频生成服务的接入架构、任务流程、鉴权、API 接口及示例，并涵盖错误处理等内容。

一、系统架构与整体流程

• ListenHub 基于云端音频生成服务构建。客户端通过 OpenAPI 网关进行通信，在语音内容生成过程中涉及多模块协同。大致流程为：

  • 客户端发起请求：应用调用 ListenHub OpenAPI 网关创建音频生成任务。
  • 核心业务处理：后端接收请求后，内部将任务分发给预处理、内容生成、多模态合成等引擎模块。这些模块协同工作，将输入文本转换为语音数据。
  • 实时文本数据获取：系统提供接口以获取单集实时文本流式信息，包含大纲与脚本数据。Podcast（播客模式）文本流生成存在20-60秒延迟，而 FlowSpeech（流式语音）模式的文本流式数据则可在创建单集后约3秒即可获取。
  • 结果推送：音频生成完成后，系统将结果上传到云端存储，客户端可通过查询接口获取结果。

• 术语定义：

  • Episode（单集）：ListenHub 系统的基本内容单元，所有功能均以单集为维度向用户开放。用户可通过唯一标识符 EpisodeId 获取单集的完整信息，包括音频、文本脚本及元数据。
  • 内容生成模式：
    • Podcast（播客模式）：以结构化博客形式生成的音频内容，支持单主持人、双主持人播报形式，能够模拟专业播客的对话风格和节奏。系统计划后续扩展支持辩论（Debate）模式。
    • FlowSpeech（流式语音）：另一种内容生成模式，与 Podcast 模式在处理逻辑和输出形式上存在差异。
  • Speaker（音色）：音频生成的核心参数，定义了单集的声学特性。每个 Speaker 包含以下关键属性：
    • SpeakerId：音色的唯一标识符
    • SpeakerName：音色的显示名称
    • Language：音色支持的语言类型

  用户在创建单集时需指定 speakerId 参数以选择目标音色进行内容生成。

下图示意 ListenHub 流程：

sequenceDiagram
    participant C as 用户
    participant G as API网关
    participant F as 生成引擎
	  participant S as 云存储
    
    Note over C, G: Episode创建
    C->>G: 创建单集接口调用
    G->>G: 验证Token/配额/权益等
    G->>F: 创建语音任务
    F-->>G: 任务完成(episodeID)
    G-->>C: 返回结果(200 OK, episodeID)

    F->>F: 处理文本(<1min)
    F->>F: 生成语音(1-2min)
    F->>S: 上传音频文件
    S-->>F: 上传确认
    F->>C: webhook确认生成完毕
 
    Note over C, G: Episode查询 - 单集所有信息
    C->>G: 查询单集详情接口调用
    G-->>C: Episode 相关信息（audioStreamUrl+单集信息）
    C->>S: GET 音频URL(播放)
    S-->>C: 返回音频流
    
    Note over C, G: Episode查询 - 文本流式
    C->>G: 查询单集文本流式接口调用
    G-->>C: 返回 Episode 脚本（script）/ 大纲 （outline）流式数据

二、OpenAPI 服务方案与定价

功能支持：

ListenHub OpenAPI V1.0 提供全面的音频内容生成能力，支持以下核心功能：

• 播客模式(Podcast)与流式语音(FlowSpeech)单集创建
• 单集内容实时查询与状态追踪
• 文本流式数据实时获取(大纲与脚本)

后续版本将陆续支持：

• 多格式音频输出支持(MP3/WAV/AAC等)
• 专业脚本编辑与优化工具
• 企业级自定义音色克隆授权(5个)

计费标准：

OpenAPI 服务仅支持 Business 和 Enterprise 套餐用户 使用