• User wants to create a podcast episode on any topic
• User provides a URL or text and wants it turned into a podcast discussion
• User asks for a "debate", "dialogue", or "discussion" format
• User says "podcast", "播客", or "录一期节目"

• User wants text-to-speech reading (use

  /speech

  )
• User wants an explainer video with visuals (use

  /explainer

  )
• User wants to generate an image (use

  /image-gen

  )
• User only wants to extract content from a URL without generating audio (use

  /content-parser

  )

• No shell scripts. Construct curl commands from the API reference files listed in Resources
• Always read

  shared/authentication.md

  for API key and headers
• Follow

  shared/common-patterns.md

  for polling, errors, and interaction patterns
• Never hardcode speaker IDs — always fetch from the speakers API
• Never fabricate API endpoints or parameters
• Always read config following

  shared/config-pattern.md

  before any interaction
• Always follow

  shared/speaker-selection.md

  for speaker selection (text table + free-text input)
• Never save files to

  ~/Downloads/

  — use

  .listenhub/podcast/

  from config

1. outputMode: Follow

   shared/output-mode.md

   § Setup Flow Question.
2. Language (optional): "默认语言？"
   • "中文 (zh)"
   • "English (en)"
   • "每次手动选择" → keep

     null

3. Mode (optional): "默认播客模式？"
   • "Quick — 简短概述"
   • "Deep — 深度分析"
   • "Debate — 辩论对话"
   • "每次手动选择" → keep

     null

4. Method (optional): "默认生成方式？"
   • "一步生成（推荐）" →

     defaultMethod: "one-step"

   • "两步生成（先预览文本）" →

     defaultMethod: "two-step"

   • "每次手动选择" → keep

     null

undefined

What topic or content would you like to turn into a podcast?

shared/speaker-selection.md

• Default from

  config.defaultSpeakers.{language}

  (skip step if set)
• Text table + free-text input
• Input matching and re-prompt on no match

1. Submit (foreground):

   POST /podcast/episodes

   with collected parameters → extract

   episodeId

2. Tell the user the task is submitted
3. Poll (background): Run the following exact bash command with

   run_in_background: true

   and

   timeout: 600000

   . Do NOT use python3, awk, or any other JSON parser — use

   jq

   as shown:
   bash

   EPISODE_ID="<id-from-step-1>"
   for i in $(seq 1 30); do
     RESULT=$(curl -sS "https://api.marswave.ai/openapi/v1/podcast/episodes/$EPISODE_ID" \
       -H "Authorization: Bearer $LISTENHUB_API_KEY" 2>/dev/null)
     STATUS=$(echo "$RESULT" | tr -d '\000-\037\177' | jq -r '.data.processStatus // "pending"')
     case "$STATUS" in
       success|completed) echo "$RESULT"; exit 0 ;;
       failed|error) echo "FAILED: $RESULT" >&2; exit 1 ;;
       *) sleep 10 ;;
     esac
   done
   echo "TIMEOUT" >&2; exit 2

4. When notified of completion, Step 6: Present result
   Read

   OUTPUT_MODE

   from config. Follow

   shared/output-mode.md

   for behavior.

   inline

   or

   both

   : Display

   audioUrl

   as a clickable link.
   Present:

   播客已生成！
   
   在线收听：{audioUrl}
   字幕：{subtitlesUrl}（如有）
   时长：{audioDuration / 1000}s
   消耗积分：{credits}

   download

   or

   both

   : Also download the file.
   bash

   DATE=$(date +%Y-%m-%d)
   JOB_DIR=".listenhub/podcast/${DATE}-{episodeId}"
   mkdir -p "$JOB_DIR"
   curl -sS -o "${JOB_DIR}/{episodeId}.mp3" "{audioUrl}"

   Present the download path in addition to the above summary.
5. Offer to show transcript or provide download URL on request

1. Step 1 — Submit text (foreground):

   POST /podcast/episodes/text-content

   → extract

   episodeId

2. Poll text (background): Use the exact

   jq

   -based polling loop above (substitute endpoint

   podcast/episodes/text-content/{episodeId}

   if needed), with

   run_in_background: true

   and

   timeout: 600000

3. When notified, save draft to config output dir:
   • Create

     .listenhub/podcast/YYYY-MM-DD-{episodeId}/

   • Write

     {episodeId}-draft.md

     (human-readable:

     **{speakerName}**: {content}

     per line)
   • Write

     {episodeId}-draft.json

     (raw

     scripts

     array)
   • Present the draft location and content preview
4. STOP: Present the draft and wait for explicit user approval
5. Step 2 — Submit audio (foreground, after approval):
   • No changes:

     POST /podcast/episodes/{episodeId}/audio

     with

     {}

   • With edits:

     POST /podcast/episodes/{episodeId}/audio

     with modified

     {scripts: [...]}

6. Poll audio (background): Same exact

   jq

   -based loop,

   run_in_background: true

   ,

   timeout: 600000

7. When notified, download audio to same folder:

   • curl -sS -o .listenhub/podcast/{dir}/{episodeId}.mp3 {audioUrl}

   • Present final result (same format as one-step, folder now has draft + final files)

• Speaker list:

  shared/api-speakers.md

• Speaker selection guide:

  shared/speaker-selection.md

• Episode creation:

  shared/api-podcast.md

• Polling:

  shared/common-patterns.md

  § Async Polling
• Config pattern:

  shared/config-pattern.md

• Invokes: speakers API (for speaker selection)
• Invoked by: content-planner (Phase 3)

1. Detect: podcast request, topic = "latest AI developments"
2. Ask mode → user picks "Deep"
3. Ask language → "English"
4. Ask speakers → 1 speaker
5. Fetch speakers list, user picks "cozy-man-english"
6. No references
7. One-step generation

curl -sS -X POST "https://api.marswave.ai/openapi/v1/podcast/episodes" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"type": "text", "content": "The latest AI developments"}],
    "speakers": [{"speakerId": "cozy-man-english"}],
    "language": "en",
    "mode": "deep"
  }'