快速开始
获取 API Key，完成第一次调用，5 分钟上手。
前置条件
获取 API Key：
- 访问 API Key 设置页面
- 点击「创建 API Key」
- 复制并妥善保管你的 API Key
请将 API Key 保存到安全位置，一旦泄露将造成积分损耗
设置环境变量：
将 API Key 保存为环境变量，所有代码示例都会使用它：
# 添加到 ~/.zshrc 或 ~/.bashrc 中以持久化
export LISTENHUB_API_KEY="your_api_key_here"更多配置方式见 认证说明。
第一次调用
验证 API Key
发送一个简单请求，确认 API Key 可用：
curl -X GET "https://api.marswave.ai/openapi/v1/speakers/list?language=zh" \
-H "Authorization: Bearer $LISTENHUB_API_KEY"const response = await fetch('https://api.marswave.ai/openapi/v1/speakers/list?language=zh', {
headers: {
'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.get(
'https://api.marswave.ai/openapi/v1/speakers/list',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
params={'language': 'zh'}
)
data = response.json()
print(data)成功响应：
{
"code": 0,
"message": "",
"data": {
"items": [
{
"name": "原野",
"speakerId": "CN-Man-Beijing-V2",
"demoAudioUrl": "https://marswave-podcast-production.s3.us-west-2.amazonaws.com/audios/mars-CN-Man-Beijing-V2.mp3",
"gender": "male",
"language": "zh"
},
{
"name": "晓曼",
"speakerId": "chat-girl-105-cn",
"demoAudioUrl": "https://marswave-podcast-production.s3.us-west-2.amazonaws.com/audios/mars-chat-girl-105-cn.mp3",
"gender": "female",
"language": "zh"
}
]
}
}创建你的第一个播客
用 quick 模式快速生成一个单人播客：
curl -X POST "https://api.marswave.ai/openapi/v1/podcast/episodes" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "介绍人工智能的发展历史",
"speakers": [{"speakerId": "CN-Man-Beijing-V2"}],
"language": "zh",
"mode": "quick"
}'const response = await fetch('https://api.marswave.ai/openapi/v1/podcast/episodes', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
query: '介绍人工智能的发展历史',
speakers: [{ speakerId: 'CN-Man-Beijing-V2' }],
language: 'zh',
mode: 'quick',
}),
});
const data = await response.json();
console.log('Episode ID:', data.data.episodeId);import os
import requests
response = requests.post(
'https://api.marswave.ai/openapi/v1/podcast/episodes',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'query': '介绍人工智能的发展历史',
'speakers': [{'speakerId': 'CN-Man-Beijing-V2'}],
'language': 'zh',
'mode': 'quick',
}
)
data = response.json()
print('Episode ID:', data['data']['episodeId'])成功响应：
{
"code": 0,
"message": "",
"data": {
"episodeId": "{episodeId}"
}
}播客生成是异步任务。episodeId 是你跟踪生成进度的唯一标识。
查询生成结果
用返回的 episodeId 轮询查询状态：
curl -X GET "https://api.marswave.ai/openapi/v1/podcast/episodes/{episodeId}" \
-H "Authorization: Bearer $LISTENHUB_API_KEY"const response = await fetch(
'https://api.marswave.ai/openapi/v1/podcast/episodes/{episodeId}',
{
headers: { 'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}` },
}
);
const data = await response.json();
console.log('Status:', data.data.processStatus);import os
import requests
response = requests.get(
'https://api.marswave.ai/openapi/v1/podcast/episodes/{episodeId}',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'}
)
data = response.json()
print('Status:', data['data']['processStatus'])生成中的响应（processStatus 为 pending）：
{
"code": 0,
"message": "",
"data": {
"episodeId": "{episodeId}",
"createdAt": 1760517419993,
"failCode": 0,
"processStatus": "pending",
"credits": 0,
"sourceProcessResult": {
"content": "介绍人工智能的发展历史\n\n",
"references": []
},
"title": "",
"outline": "",
"cover": "https://static.listenhub.ai/listenhub_default_cover061802.png",
"audioUrl": "",
"scripts": []
}
}完成后的响应（processStatus 为 success）：
{
"code": 0,
"message": "",
"data": {
"episodeId": "{episodeId}",
"createdAt": 1760517752411,
"failCode": 0,
"processStatus": "success",
"credits": 27,
"sourceProcessResult": {
"content": "介绍人工智能的发展历史\n\n",
"references": []
},
"title": "听AI讲自己的故事：智能时代如何诞生",
"outline": "...",
"cover": "https://static.listenhub.ai/listenhub_default_cover061804.png",
"audioUrl": "https://assets.listenhub.ai/listenhub-public-prod/podcast/{episodeId}.mp3",
"scripts": [
{
"speakerId": "CN-Man-Beijing-V2",
"speakerName": "原野",
"content": "如今我们好像每天都被人工智能的新闻包围着。"
}
]
}
}当 processStatus 变为 success 时，audioUrl 即为最终的 MP3 音频地址。
轮询最佳实践
播客生成通常需要 1-4 分钟。推荐的轮询策略：等待 60 秒后开始，每 10 秒查询一次。
async function pollEpisodeResult(episodeId, apiKey, timeout = 300000) {
const url = `https://api.marswave.ai/openapi/v1/podcast/episodes/${episodeId}`;
const headers = { 'Authorization': `Bearer ${apiKey}` };
const startTime = Date.now();
// 生成需要时间，先等待 60 秒
await new Promise(resolve => setTimeout(resolve, 60000));
while (Date.now() - startTime < timeout) {
const response = await fetch(url, { headers });
const data = await response.json();
if (data.code !== 0) throw new Error(`API Error: ${data.message}`);
const status = data.data.processStatus;
if (status === 'success') return data.data;
if (status === 'failed') throw new Error(`Generation failed: ${data.data.message}`);
await new Promise(resolve => setTimeout(resolve, 10000));
}
throw new Error('Episode generation timeout');
}import time
import os
import requests
def poll_episode_result(episode_id, api_key, timeout=300):
"""轮询查询单集生成结果，超时默认 5 分钟。"""
url = f"https://api.marswave.ai/openapi/v1/podcast/episodes/{episode_id}"
headers = {"Authorization": f"Bearer {api_key}"}
start_time = time.time()
# 生成需要时间，先等待 60 秒
time.sleep(60)
while time.time() - start_time < timeout:
response = requests.get(url, headers=headers)
data = response.json()
if data["code"] != 0:
raise Exception(f"API Error: {data['message']}")
status = data["data"]["processStatus"]
if status == "success":
return data["data"]
elif status == "failed":
raise Exception(f"Generation failed: {data['data'].get('message')}")
time.sleep(10)
raise TimeoutError("Episode generation timeout")