logo
API docs by Redocly

火星电波 OpenAPI User 接口文档 (1.0.0)

Download OpenAPI specification:

Marswave Team: dev@marswave.ai License: Apache 2.0

此文档是火星电波 OpenAPI 接口文档。

完整接入指南：https://blog.listenhub.ai/openapi-docs

Authentication

使用 APIKey 认证, 格式为 Authorization: Bearer < your api key >

获取 API Key：访问 API Keys 设置页面

user

用户相关接口

获取用户订阅详情

获取当前用户的订阅状态以及积分使用情况。

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

speakers

音色相关接口

获取音色列表（含私有音色）

获取可用音色列表。若提供 API Key，则返回该用户可用的私有音色；未提供时仅返回公开音色。

query Parameters
language
string
Example: language=en/zh/ja

过滤语言类型

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

podcast

Podcast 相关接口

创建 Podcast Episode

根据提供的文本和其他设置创建新的播客模式 Episode。

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
query
string

要合成的文本

Array of objects

可选, 其他来源

required
Array of objects [ 1 .. 2 ] items

必填, 语音类型

language
string
Enum: "en" "zh" "ja"

可选，en/zh/ja, 语言类型。默认值：en（英文）

mode
string
Enum: "deep" "quick" "debate"

生成模式 deep: 深度模式, quick: 快速模式, debate: 辩论模式。默认值：quick（快速模式）

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "sources": [
    ],
  • "speakers": [
    ],
  • "language": "en",
  • "mode": "deep"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

查询 Podcast 单集信息

查询指定 Podcast 单集的详细信息，包括博客文本、音频内容等。

Authorizations:
ApiKeyAuth
path Parameters
episodeId
required
string

Podcast 单集的唯一标识符

Responses

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

获取 Podcast 单集文本流信息

获取指定 Podcast 单集的大纲或脚本文本流内容，以Server-Sent Events (SSE) 格式返回。

Authorizations:
ApiKeyAuth
path Parameters
episodeId
required
string

Podcast 单集的唯一标识符

query Parameters
event
required
string
Enum: "script" "outline"

查询的事件类型 (script 或 outline)

Responses

创建 Podcast Episode（仅生成内容）

两阶段生成 - 第一阶段：仅生成播客内容（scripts、outline等），不生成音频。

生成完成后，可以：

  1. 调用查询接口获取生成的 scripts
  2. 修改 scripts（可选）
  3. 调用 /v1/podcast/episodes/{episodeId}/audio 接口生成音频
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
query
string

要合成的文本

Array of objects

可选, 其他来源

required
Array of objects [ 1 .. 2 ] items

必填, 语音类型

language
required
string
Enum: "en" "zh" "ja"

必填，en/zh/ja, 语言类型。speaker 的语言必须与此参数匹配

mode
string
Enum: "deep" "quick" "debate"

生成模式 deep: 深度模式, quick: 快速模式, debate: 辩论模式。默认值：quick（快速模式）

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "sources": [
    ],
  • "speakers": [
    ],
  • "language": "en",
  • "mode": "deep"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

生成 Podcast 音频

两阶段生成 - 第二阶段：在已生成内容的基础上生成音频。

前置条件：

  • 必须先调用 /v1/podcast/episodes/text-content 生成内容
  • 文本生成状态 (contentStatus) 必须为 text-success

使用场景：

  1. 先调用 /v1/podcast/episodes/text-content 生成内容
  2. 查询并获取生成的 scripts
  3. 修改 scripts（可选）
  4. 调用本接口，可以传入修改后的 scripts 或使用原有 scripts
Authorizations:
ApiKeyAuth
path Parameters
episodeId
required
string

Podcast 单集的唯一标识符

Request Body schema: application/json
optional
Array of objects

可选, 自定义脚本数组（如果不提供则使用已有脚本）。播客脚本中必须包含 1-2 个不同的音色。

Responses

Request samples

Content type
application/json
{
  • "scripts": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

flowspeech

Flowspeech 相关接口

创建 Flowspeech Episode

根据提供的文本和其他设置创建新的流式语音模式 Episode。

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects = 1 items

必填, 来源信息

required
Array of objects [ 1 .. 2 ] items

必填, 语音类型

language
string
Enum: "en" "zh" "ja"

可选，en/zh/ja, 语言类型

mode
string
Enum: "smart" "direct"

生成模式 smart: 智能模式（AI修复语句、错别字等）, direct: 直接模式（不修改内容直接转语音）

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "speakers": [
    ],
  • "language": "en",
  • "mode": "smart"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "",
  • "data": {
    }
}

查询 Flowspeech 单集信息

查询指定 Flowspeech 单集的详细信息，包括文本、音频内容等。

Authorizations:
ApiKeyAuth
path Parameters
episodeId
required
string

Flowspeech 单集的唯一标识符

Responses

Response samples

Content type
application/json
Example
{}

获取 Flowspeech 单集文本流信息

获取指定 Flowspeech 单集的大纲或脚本文本流内容，以Server-Sent Events (SSE) 格式返回。

Authorizations:
ApiKeyAuth
path Parameters
episodeId
required
string

Flowspeech 单集的唯一标识符

query Parameters
event
required
string
Enum: "script" "outline"

查询的事件类型 (script 或 outline)

Responses

Response samples

Content type
text/event-stream
Example
id: 689ef06042a332af99cd5781
event: script
data: {"code":0, "message":"", "data": {"chunk":"突然变成了一副巨型水印框。"}}

id: 689ef06042a332af99cd5781
event: script
data: {"code":0, "message":"", "data": {"chunk":"这栋百年建筑的每一扇窗户"}}

id: 689ef06042a332af99cd5781
event: script
data: {"code":0, "message":"", "data": {"chunk":"[END]"}}

text-to-speech

文本转语音接口

直接调用 Speech 引擎生成音频（同步）

直接从脚本生成音频，无需创建 Episode，支持多人对话。

特点：

  • 同步返回：调用后立即返回音频 URL 和详细信息
  • 无 Episode：不创建任何 Episode 记录
  • 直接转换：不对文本内容进行 AI 修改，直接转语音
  • 支持多音色：可使用多个不同的音色
  • 积分扣除：根据实际生成的音频长度扣除积分

使用场景：

  • 已有完整的脚本内容，需要快速转为语音
  • 需要精确控制每句话的音色和内容
  • 不需要保存 Episode 记录，只需要音频文件

积分计算：

  • 在调用前会预先检查用户积分是否足够
  • 根据实际生成的 audioUnits 扣除积分
  • 如果积分不足，返回错误码 26004
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects non-empty

必填, 脚本数组

Responses

Request samples

Content type
application/json
{
  • "scripts": [
    ]
}

Response samples

Content type
application/json
Example
{}

single-speaker-tts

单音色 TTS 生成接口

单音色 TTS 生成接口（流式二进制输出）

文本转语音接口，直接返回音频二进制流。

特点：

  • 流式输出：直接返回二进制音频流，无需等待完整生成
  • 单音色：仅支持单个音色的文本转语音
  • 实时响应：音频以流式方式实时返回

使用场景：

  • 简单的单音色文本转语音需求
  • 需要流式音频输出的场景

与 /v1/speech 的区别：

  • /v1/tts: 流式二进制输出，单音色，实时返回
  • /v1/speech: JSON 响应，多音色支持，同步返回 URL

积分计算：

  • 根据实际生成的音频长度扣除积分
  • 如果积分不足，返回错误码 26004
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
input
required
string

要转换为语音的文本内容

voice
required
string

音色ID（speakerId）

model
string
Default: "flowtts"

模型名称（可选，默认值：flowtts）。注：此参数暂不做任何处理，仅用于兼容性

Responses

Request samples

Content type
application/json
{
  • "input": "今天天气真不错，适合出去散步。",
  • "voice": "speaker_001",
  • "model": "flowtts"
}

Response samples

Content type
No sample

📘 错误码说明

系统级错误码

错误码 说明 处理建议
21007 API Key 无效 检查 API Key 是否正确配置
25002 资源不存在 检查请求的资源 ID 是否正确
25008 单集状态不正确 检查单集是否已完成文本内容生成，确认 contentStatus 为 text-success
26004 积分不足 检查账户积分余额，升级套餐或联系客服
29003 参数错误 验证请求参数格式和必填项
29998 请求过于频繁 实现指数退避重试，建议间隔 20-30 秒

内容生成错误码

错误码 说明 适用接口
91001 内容过短 Podcast, FlowSpeech
91002 内容违规 无法显示 Podcast, FlowSpeech
91003 查询失败 Podcast, FlowSpeech
91004 无法获取内容 Podcast, FlowSpeech
91005 无法获取URL内容 Podcast, FlowSpeech
91006 处理失败 Podcast, FlowSpeech
91007 文件体积过大 Podcast, FlowSpeech

错误响应格式

所有错误都在 HTTP 200 响应中返回，通过 code 字段区分：

{
  "code": 21007,
  "message": "Invalid user APIKey",
  "data": {}
}

错误处理示例

系统级错误

当接口返回系统级错误码时，通常需要修正请求参数或检查账户状态。

内容生成错误

当查询接口返回成功（code: 0），但 data.failCode 有值时，表示内容生成失败：

{
  "code": 0,
  "message": "",
  "data": {
    "episodeId": "xxx",
    "processStatus": "failed",
    "failCode": 91001,
    "message": "Content is too short"
  }
}