快速开始
前置条件、首个 API 调用与轮询最佳实践。
一、快速开始（5分钟上手）
1. 前置条件
订阅计划要求：
- 所有用户均可使用！
获取 API Key：
- 访问 API Keys 设置页面
- 点击”创建 API Key”
- 复制并妥善保管您的 API Key
2. 第一次 API 调用
2.1 验证 API Key
测试 API 连接是否正常：
curl -X GET "https://api.marswave.ai/openapi/v1/speakers/list?language=zh" \ -H "Authorization: Bearer YOUR_API_KEY"成功响应示例：
{
"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"
}
]
}
}2.2 创建第一个 Podcast
使用 Quick 模式快速生成一个单人播客：
curl -X POST "https://api.marswave.ai/openapi/v1/podcast/episodes" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "介绍人工智能的发展历史",
"speakers": [{"speakerId": "CN-Man-Beijing-V2"}],
"language": "zh",
"mode": "quick"
}'成功响应示例：
{
"code": 0,
"message": "",
"data": {
"episodeId": "68d699ebc4b373bd1ae50dde"
}
}2.3 查询生成结果
使用返回的 episodeId 查询单集状态：
curl -X GET "https://api.marswave.ai/openapi/v1/podcast/episodes/68d699ebc4b373bd1ae50dde" \ -H "Authorization: Bearer YOUR_API_KEY"处理中的响应：
{
"code": 0,
"message": "",
"data": {
"episodeId": "68ef5d2b5d59db3b0909c08c",
"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": []
}
}完成后的响应：
{
"code": 0,
"message": "",
"data": {
"episodeId": "68ef5e78e06b4dd24fbfe69f",
"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/68ef5e78e06b4dd24fbfe69d.mp3",
"scripts": [
{
"speakerId": "chinese-mandarin-radio-host",
"speakerName": "宇航",
"content": "如今我们好像每天都被人工智能的新闻包围着。"
}
]
}
}3. 轮询最佳实践
建议使用以下策略轮询查询结果：
import time
import requests
def poll_episode_result(episode_id, api_key, timeout=300):
"""
轮询查询单集生成结果
Args:
episode_id: 单集ID
api_key: API密钥
timeout: 超时时间（秒），默认5分钟
"""
url = f"https://api.marswave.ai/openapi/v1/podcast/episodes/{episode_id}"
headers = {"Authorization": f"Bearer {api_key}"}
start_time = time.time()
print("⏳ 等待内容生成中...")
time.sleep(60)
# 1分钟后开始轮询，每10秒查询一次
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) # 每10秒查询一次
raise TimeoutError("Episode generation timeout")轮询策略：等待 1 分钟后，每 10 秒轮询一次