クイックスタート

前提条件

API キーを取得する：

API キー設定ページを開く
API キーを作成 をクリックする
API キーをコピーし、安全な場所に保管する

API キーは作成時に一度だけ表示されます。すぐにコピーして安全な場所に保存してください。

環境変数を設定する：

API キーを環境変数として保存します。本ガイドのコード例はすべてこの環境変数を参照します：

# Add to ~/.zshrc or ~/.bashrc to persist across sessions
export LISTENHUB_API_KEY="your_api_key_here"

その他の設定方法は認証を参照してください。

最初の呼び出し

API キーの検証

簡単なリクエストを送信して、API キーが使えることを確認します：

curl -X GET "https://api.marswave.ai/openapi/v1/speakers/list?language=en" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

const response = await fetch('https://api.marswave.ai/openapi/v1/speakers/list?language=en', {
  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': 'en'}
)
data = response.json()
print(data)

成功レスポンス：

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "name": "Ethan",
        "speakerId": "EN-Man-General-01",
        "demoAudioUrl": "https://example.com/demo-ethan.mp3",
        "gender": "male",
        "language": "en"
      },
      {
        "name": "Sophia",
        "speakerId": "EN-Woman-General-01",
        "demoAudioUrl": "https://example.com/demo-sophia.mp3",
        "gender": "female",
        "language": "en"
      }
    ]
  }
}

最初のポッドキャストを作成する

quick モードで、スピーカー 1 人のエピソードを生成します：

curl -X POST "https://api.marswave.ai/openapi/v1/podcast/episodes" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Give a concise introduction to the history of artificial intelligence.",
    "speakers": [{"speakerId": "EN-Man-General-01"}],
    "language": "en",
    "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: 'Give a concise introduction to the history of artificial intelligence.',
    speakers: [{ speakerId: 'EN-Man-General-01' }],
    language: 'en',
    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': 'Give a concise introduction to the history of artificial intelligence.',
        'speakers': [{'speakerId': 'EN-Man-General-01'}],
        'language': 'en',
        '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": "Give a concise introduction to the history of artificial intelligence.",
      "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": "Give a concise introduction to the history of artificial intelligence.",
      "references": []
    },
    "title": "A Brief History of Artificial Intelligence",
    "outline": "...",
    "cover": "https://static.listenhub.ai/listenhub_default_cover061804.png",
    "audioUrl": "https://assets.listenhub.ai/listenhub-public-prod/podcast/{episodeId}.mp3",
    "scripts": [
      {
        "speakerId": "EN-Man-General-01",
        "speakerName": "Ethan",
        "content": "Artificial intelligence has evolved from symbolic logic to modern large models..."
      }
    ]
  }
}

processStatus が success になると、audioUrl フィールドに最終的な MP3 音声の URL が入ります。

ポーリングのベストプラクティス

ポッドキャストの生成には通常 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();

  // Generation takes time, wait 60 seconds first
  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):
    """Poll episode result until completion. Default timeout is 5 minutes."""
    url = f"https://api.marswave.ai/openapi/v1/podcast/episodes/{episode_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    start_time = time.time()

    # Generation takes time, wait 60 seconds first
    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"]
        if status == "failed":
            raise Exception(f"Generation failed: {data['data'].get('message')}")

        time.sleep(10)

    raise TimeoutError("Episode generation timeout")

次のステップ

コアコンセプト — Episode、Speaker、生成モードについて学ぶ
ポッドキャスト生成 API — リクエストパラメータとレスポンスフィールドの詳細
テキスト読み上げ（Text to Speech）API — テキストを自然な音声に変換する