Podcastfy 音频播客 REST API 完整接入指南cURL 与 Python 双端调用实战【免费下载链接】podcastfyAn Open Source Python alternative to NotebookLMs podcast feature: Transforming Multimodal Content into Captivating Multilingual Audio Conversations with GenAI项目地址: https://gitcode.com/GitHub_Trending/po/podcastfy导读本文档系统讲解开源项目 Podcastfy 对外暴露的 REST API——如何通过 cURL 与 Pythongradio_client两种方式将文本、URL、PDF、图片等多模态输入转化为可下载的 MP3 播客音频。读完本文你将掌握 API 的两段式请求调用流程POST 发起 GET 拉取结果、全部 17 个请求参数的含义与默认值、底层生成链路内容抽取 → LLM 对话稿生成 → TTS 合成的源码级实现并能直接照抄文中示例完成第一次调用。说明文档描述的process_inputs端点对应社区 Demo 服务Gradio 封装仓库内还提供了一套自托管 FastAPI 实现见 podcastfy/api/fast_app.py本文在讲清 API 文档主体内容的同时也会结合源码补充这两类接入方式的关系。一、API 概览一条输入两次请求产出 MP3Podcastfy 的 API 设计遵循异步任务 结果拉取模式客户端无法一次性同步拿到音频而是分两步走POST 请求向/process_inputs端点提交待处理的输入文本 / URL / PDF / 图片及生成参数服务端随即返回一个EVENT_IDGET 请求携带上一步拿到的EVENT_ID访问同一端点以流式SSE方式获取任务结果最终返回生成的 MP3 文件信息。两次请求之间存在13 分钟的处理延迟官方文档明确说明项目团队正在努力缩短延迟并规划播客就绪通知机制。延迟主要来源于底层两个耗时的生成阶段这一点从源码调用链可以印证阶段一ContentGenerator.generate_qa_content()调用 LLM默认gemini-2.5-flash见 config.yaml把抽取到的内容改写为双人对话稿Transcript阶段二TextToSpeech.convert_to_speech()按对话稿逐段调用所选 TTS 服务合成音频再通过 pydub 合并导出为 MP3见 text_to_speech.py。整个编排逻辑集中在process_content()见 client.py先由ContentExtractor抽取 URL / 文本内容再由ContentGenerator生成对话稿最后交给TextToSpeech合成音频并落盘到data/audio目录。二、使用 cURL 调用两段式请求全流程2.1 前置检查调用前先确认本机已安装 cURLcurl --version2.2 Step 1POST 发起任务获得 EVENT_ID/process_inputs端点接收一个data数组数组元素按固定顺序与 17 个参数一一对应详见第三节参数表。注意URL 必须带http://或https://前缀# Step 1: POST request to initiate processing curl -X POST https://thatupiso-podcastfy-ai-demo.hf.space/gradio_api/call/process_inputs \ -H Content-Type: application/json \ -d { data: [ text_input, # 直接文本输入 https://yourwebsite.com, # 待处理 URL [], # pdf_files [], # image_files gemini_key, # Google Gemini API key openai_key, # OpenAI API key elevenlabs_key, # ElevenLabs API key 2000, # word_count 目标字数 engaging,fast-paced, # conversation_style 对话风格 main summarizer, # roles_person1 第一说话人角色 questioner, # roles_person2 第二说话人角色 Introduction,Content,Conclusion, # dialogue_structure 对话结构 PODCASTFY, # podcast_name 播客名称 YOUR PODCAST, # podcast_tagline 播客标语 openai, # tts_model 语音合成模型 0.7, # creativity_level 创造力度 0-1 # user_instructions 自定义指令 ] }服务端会返回形如{event_id: ...}的响应其中的event_id即后续拉取结果所需的EVENT_ID。2.3 Step 2GET 拉取结果下载音频用上一步的EVENT_ID发起 GET 请求-N关闭缓冲以实时接收流式输出# Step 2: GET request to fetch results curl -N https://thatupiso-podcastfy-ai-demo.hf.space/gradio_api/call/process_inputs/$EVENT_ID任务完成后返回 SSE 事件流示例输出如下event: complete data: [{path: /tmp/gradio/bcb143f492b1c9a6dbde512557541e62f090bca083356be0f82c2e12b59af100/podcast_81106b4ca62542f1b209889832a421df.mp3, url: https://thatupiso-podcastfy-ai-demo.hf.space/gradio_a/gradio_api/file/tmp/gradio/.../podcast_81106b4ca62542f1b209889832a421df.mp3, size: null, orig_name: podcast_81106b4ca62542f1b209889832a421df.mp3, mime_type: null, is_stream: false, meta: {_type: gradio.FileData}}]文件下载的关键细节请以path字段的值为准进行下载。正确的下载 URL 是把文件服务器前缀https://thatupiso-podcastfy-ai-demo.hf.space/gradio_a/gradio_api/file与path拼接而成。文档特别提醒返回数据中的url字段存在一个 Gradio 引入的已知 bug请忽略url字段直接使用path拼接。下载到的文件即为生成的播客 MP3。三、17 个请求参数详解下表完整列出process_inputs端点data数组中按索引排列的全部参数cURL 模式下顺序即一切字段名仅供对照索引参数类型说明0text_inputstring直接输入用于生成播客的文本1urls_inputstring待处理的 URL必须含 http:// 或 https://2pdf_filesarray待处理的 PDF 文件列表3image_filesarray待处理的图片文件列表4gemini_keystringGoogle Gemini API key5openai_keystringOpenAI API key6elevenlabs_keystringElevenLabs API key7word_countnumber播客目标字数8conversation_stylestring对话风格描述如 engaging,fast-paced9roles_person1string第一说话人角色10roles_person2string第二说话人角色11dialogue_structurestring对话结构如 Introduction,Content,Conclusion12podcast_namestring播客名称13podcast_taglinestring播客标语14tts_modelstring语音合成模型gemini、openai、elevenlabs 或 edge15creativity_levelnumber创造力度0-116user_instructionsstring自定义生成指令参数与底层配置的映射关系这些参数并非凭空设计而是与仓库内的对话配置conversation_config.yaml一一对应见 conversation_config.yaml。其中conversation_style、roles_person1/2、dialogue_structure、podcast_name、podcast_tagline、user_instructions等字符串参数会被ContentGenerator中的StandardContentStrategy.compose_prompt_params()解析后注入 LLM 提示词见 content_generator.py用于控制对话稿的风格、角色分配与结构编排creativity对应 API 的creativity_level会作为LLM 的温度参数传入LLMBackend见 content_generator.py同时presence_penalty与frequency_penalty被固定为 0.75 以鼓励内容多样性、避免重复——这就是创造力度调节的底层机制tts_model决定最终音频由哪个 TTS 提供商合成。TextToSpeech通过TTSProviderFactory.create()按模型名实例化对应 Provider见 text_to_speech.py每个提供商在配置中都有独立的默认音色OpenAI 用echo/shimmer模型tts-1-hd、ElevenLabs 用Chris/Jessica模型eleven_multilingual_v2、Edge 用en-US-JennyNeural/en-US-EricNeural、Gemini 用en-US-Journey-D/en-US-Journey-O。四、使用 Python 调用gradio_client 实战4.1 安装依赖pip install gradio_client4.2 初始化客户端from gradio_client import Client, handle_file client Client(thatupiso/Podcastfy.ai_demo)4.3 调用/process_inputs端点参数签名含默认值参数类型必填默认值说明text_inputstr是-用于生成播客的原始文本urls_inputstr是-逗号分隔的待处理 URL 列表pdf_filesList[filepath]是None待处理的 PDF 文件列表image_filesList[filepath]是None待处理的图片文件列表gemini_keystr否Google Gemini API keyopenai_keystr否OpenAI API keyelevenlabs_keystr否ElevenLabs API keyword_countfloat否2000播客目标字数conversation_stylestr否engaging,fast-paced,enthusiastic对话风格描述roles_person1str否main summarizer第一说话人角色roles_person2str否questioner/clarifier第二说话人角色dialogue_structurestr否Introduction,Main Content Summary,Conclusion对话结构podcast_namestr否PODCASTFY播客名称podcast_taglinestr否YOUR PERSONAL GenAI PODCAST播客标语tts_modelLiteral[openai, elevenlabs, edge]否openai语音合成模型creativity_levelfloat否0.7创造力度0-1user_instructionsstr否自定义生成指令其中各默认值与仓库 conversation_config.yaml 中的默认对话风格engaging、fast-paced、enthusiastic、默认角色main summarizer/questioner/clarifier、默认结构Introduction、Main Content Summary、Conclusion完全对齐说明远程 Demo 与本地库使用同一套默认配置行为可预期。返回类型类型说明filepath生成音频文件的路径完整示例从 URL 生成播客from gradio_client import Client, handle_file client Client(thatupiso/Podcastfy.ai_demo) # Generate podcast from URL result client.predict( text_input, urls_inputhttps://example.com/article, pdf_files[], image_files[], gemini_keyyour-gemini-key, openai_keyyour-openai-key, word_count1500, conversation_stylecasual,informative, podcast_nameTech Talk, tts_modelopenai, creativity_level0.8 ) print(fGenerated podcast: {result})多模态文件上传PDF 与图片属于文件类型参数需要借助handle_file进行上传。以图片为例from gradio_client import Client, handle_file client Client(thatupiso/Podcastfy.ai_demo) result client.predict( text_input, urls_input, pdf_files[], image_files[handle_file(path/to/your/image.jpg)], gemini_keyyour-gemini-key, openai_keyyour-openai-key, word_count1000, conversation_styleengaging,fast-paced, tts_modeledge, creativity_level0.7 )图片输入会作为多模态内容注入 LLM 提示词ContentGenerator.__compose_prompt()会为每张图片生成image_path_{i}占位符并组装进用户消息模板见 content_generator.py底层由 Gemini 等多模态模型完成看图说话式的对话稿生成。五、错误处理与速率限制常见错误场景API 会对以下情况返回明确的错误信息无效的 API keyGemini / OpenAI / ElevenLabs 任一密钥无效对应服务调用阶段会失败输入格式错误JSON 结构不合法、data数组元素顺序错位、URL 缺少协议前缀等文件处理失败PDF 解析失败、图片格式不受支持或上传中断TTS 生成错误所选 TTS 服务超时、额度耗尽或音频合并异常。在本地 FastAPI 实现中这些错误会统一包装为 HTTP 500 响应并携带detail字段返回见 fast_app.py便于调用方捕获定位。底层服务的速率限制请特别留意三个底层服务的配额与限流策略它们的额度将直接影响生产环境下的并发与吞吐Gemini API对话稿生成阶段的主模型默认gemini-2.5-flash受 Google 配额约束OpenAI API既可作为 LLM 后端经 LiteLLM也可作为 TTS 后端tts-1-hd受 OpenAI 双重配额约束ElevenLabs API作为 TTS 后端时受 ElevenLabs 字符额度约束。六、补充仓库自带的 FastAPI 实现自托管方案除远程 Demo 外仓库还提供了一套自托管 REST 服务podcastfy/api/fast_app.py其端点设计与远程 API 同源但更轻量适合本地部署或私有化调用端点方法功能/generatePOST提交播客生成任务返回{audioUrl: /audio/{filename}}/audio/{filename}GET下载生成的 MP3 音频文件/healthGET健康检查返回{status: healthy}/generate端点接收的 JSON 体字段名见 fast_api_example.py与远程 API 的data数组基本对应urls、name、tagline、creativity、conversation_style、roles_person1/2、dialogue_structure、tts_model、output_language、user_instructions等。服务内部通过merge_configs()将用户配置与默认conversation_config.yaml深度合并用户值优先再调用generate_podcast()完成生成见 fast_app.py。仓库的 API 测试用例 tests/test_api.py 验证了/health健康检查与/generate生成链路的正确性使用TestClient模拟请求可作为自托管服务接入时的最小验收参考。完整的 Python 异步调用示例见 usage/fast_api_example.py它展示了用aiohttp提交任务并下载音频的完整流程。七、注意事项汇总输入必填约束文本、URL、PDF、图片四类输入源至少提供一种否则任务无法发起该约束在client.py的generate_podcast()中通过显式校验强制见 client.pyAPI key 对应关系使用哪个 TTS 模型就需提供对应服务的密钥——gemini需要 Gemini key、openai需要 OpenAI key、elevenlabs需要 ElevenLabs key而edge为微软免费服务、无需密钥本地实现中会跳过 API key 获取见 client.py输出格式生成的音频文件统一为MP3格式下载链接陷阱解析 GET 返回结果时务必使用path字段拼接下载前缀忽略有 bug 的url字段时序预期从提交到拿到音频通常需要 13 分钟请为客户端设置合理的超时与重试策略。【免费下载链接】podcastfyAn Open Source Python alternative to NotebookLMs podcast feature: Transforming Multimodal Content into Captivating Multilingual Audio Conversations with GenAI项目地址: https://gitcode.com/GitHub_Trending/po/podcastfy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考