2slides 演示文稿生成技能实战指南：从文本、参考图与文档到 AI 配音 PPT 的完整工作流

2slides 演示文稿生成技能实战指南：从文本、参考图与文档到 AI 配音 PPT 的完整工作流

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills

本文是 AAS（Agentic Awesome Skills）仓库中2slides-ppt-generator技能的使用与原理指南。该技能将 2slides 的 AI 演示文稿生成 API 封装为可复用的 Agent 工作流，支持基于内容的主题化生成（Fast PPT）、参考图风格匹配、自定义 PDF 设计、文档摘要成稿、AI 语音配音与页面/音频导出，每次生成都会返回在线幻灯片链接与可下载的 PDF。读完本文，你将掌握完整的 7 条生成路径、全部脚本参数与积分成本模型、同步/异步模式选型、MCP 集成方式，以及源码层面的超时与安全防护实现，可以直接上手把一段文字、一张参考图或一份文档变成可分发、可配音的演示文稿。

技能定位与核心能力

2slides-ppt-generator是一个位于 plugins/agentic-awesome-skills-claude/skills/2slides-ppt-generator 的 Agent 技能，其入口定义在 SKILL.md，完整操作手册即本文基于的 detailed-guide.md。

从技能能力上看，它覆盖了演示文稿生产链路的绝大多数环节：

• 内容驱动生成：把用户直接提供的文字、大纲或要点转换为结构化幻灯片；
• 风格模仿生成：基于一张公开可访问的参考图，复刻其版式与设计风格（Nano Banana Pro 模式）；
• 自定义 PDF 设计：不提供参考图，仅凭文本与设计指令（如 "modern minimalist, blue color scheme"）由 AI 自主完成视觉设计；
• 文档摘要成稿：读取 PDF/DOCX/TXT 等文档，提炼要点后按内容生成流程产出幻灯片；
• AI 语音配音：为已完成的幻灯片添加单人或多角色配音（30 种音色、19 种以上语言）；
• 页面/音频导出：把每页幻灯片导出为 PNG、配音导出为 WAV 并附带文稿，打包为 ZIP；
• 主题检索：按关键词查找可用主题，供内容生成阶段选用。

该技能改编自 2slides 官方技能仓库，调用的是云端托管的 2slides API，因此需要用户自行持有 API Key 与积分（credits）。从 api_constants.py 可以看到所有脚本共享的 API 基址为https://2slides.com/api/v1，并集中定义了语言、宽高比、分辨率、内容详细度、生成模式与 30 个配音音色等全部允许取值，是理解参数边界的权威依据。

环境准备：API Key、积分与依赖安装

使用前需要完成四项准备，其中前三项与原文档完全一致，依赖安装环节可结合源码确认细节。

1. 获取 API Key

在 2slides 官网的 API 页面注册账户并创建 API Key。新用户注册后可获得500 免费积分，大约可生成 50 页 Fast PPT。

2. 购买积分（可选）

2slides 采用按需付费（pay-as-you-go）模式，无订阅费用、积分永不过期，大额套餐最高可享 20% 折扣。详细套餐与成本计算见 pricing.md。

3. 配置环境变量

所有脚本统一从环境变量SLIDES_2SLIDES_API_KEY读取密钥。以 bash 为例：

read -r -s SLIDES_2SLIDES_API_KEY export SLIDES_2SLIDES_API_KEY

从源码看，generate_slides.py 中的get_api_key()若检测不到该变量会直接抛出ValueError并提示设置方式；请求时密钥以Authorization: Bearer <key>头随 HTTPS 请求发送。SKILL.md 的安全说明强调：严禁将密钥硬编码进命令、提交到版本库或回显给用户。

4. 安装脚本依赖

在技能目录下安装锁定的本地依赖：

python -m pip install -r requirements.txt

依赖清单位于 requirements.txt，脚本运行需要requests库（所有脚本均通过import requests发起 HTTP 调用）。

积分成本速览

以最常见的三种场景估算：10 页 Fast PPT 约 100 积分；10 页 Nano Banana 2K 约 1000 积分；10 页带配音的演示约 2100 积分。新用户的 500 免费积分约可产出 50 页 Fast PPT，或约 5 页 2K 参考图生成，或约 2 页带完整配音的 2K 页面。

工作流决策树：按用户请求选择生成路径

原文档给出了一张清晰的决策树，用于根据用户意图分流到不同的章节。这里完整保留：

User Request │ ├─ "Create slides from this content/text" │ └─> Use Content-Based Generation (Section 1) │ ├─ "Create slides like this image" │ └─> Use Reference Image Generation (Section 2) │ ├─ "Create custom designed slides" or "Create PDF slides" │ └─> Use Custom PDF Generation (Section 3) │ ├─ "Create slides from this document" │ └─> Use Document Summarization (Section 4) │ ├─ "Add voice narration" or "Generate audio for slides" │ └─> Use Voice Narration (Section 5) │ ├─ "Download slides as images" or "Export slides and voices" │ └─> Use Download Export (Section 6) │ └─ "Search for themes" or "What themes are available?" └─> Use Theme Search (Section 7)

路径一：基于内容的生成（Content-Based Generation）

当用户直接在消息中给出内容、说"帮我做一份关于 X 的演示"，或提供了结构化大纲时，走这条路径。

Step 1：整理内容

清晰的结构是生成质量的前提，推荐按"标题 + 分节 + 要点"组织：

Title: [Main Topic] Section 1: [Subtopic] - Key point 1 - Key point 2 - Key point 3 Section 2: [Subtopic] - Key point 1 - Key point 2

Step 2：选择主题（必选）

主题 ID 是标准生成的必要参数。使用主题检索脚本查找合适主题：

python scripts/search_themes.py --query "business" python scripts/search_themes.py --query "professional" python scripts/search_themes.py --query "creative"

从 search_themes.py 源码看，--query为必填参数，--limit默认 20、上限 100（脚本内部会min(limit, 100)兜底），还提供了--json开关输出原始 JSON 便于程序化处理。

Step 3：生成幻灯片

# 基础生成（theme ID 必填） python scripts/generate_slides.py --content "Your content here" --theme-id "theme123" # 指定输出语言 python scripts/generate_slides.py --content "Your content" --theme-id "theme123" --language "Spanish" # 异步模式，适合较长演示 python scripts/generate_slides.py --content "Your content" --theme-id "theme123" --mode async

Step 4：处理结果

同步模式下脚本直接返回在线幻灯片与 PDF 两个链接：

{ "slideUrl": "https://2slides.com/slides/abc123", "pdfUrl": "https://2slides.com/slides/abc123/download", "status": "completed" }

异步模式下立即返回 jobId，需轮询：

{ "jobId": "job123", "status": "pending" }

python scripts/get_job_status.py --job-id "job123"

从 generate_slides.py 源码可以看到模式切换的底层实现：同步模式请求超时设为90 秒（等待服务端完成生成），异步模式仅 30 秒（只负责创建任务）。对应 API 端点为POST /slides/generate，请求体包含userInput、themeId、responseLanguage、mode四个字段，细节见 api-reference.md。

路径二：参考图风格生成（Reference Image Generation）

当用户提供图片 URL 并说"像这样生成幻灯片"、要求匹配品牌/设计风格或仿制模板时使用。

Step 1：校验图片 URL

参考图必须是：公开可访问的 URL、有效图片格式（PNG/JPG 等）、能代表目标幻灯片风格。SKILL.md 同时提示：参考图会被发送到 2slides 服务端处理，不要提交未经用户授权的机密材料。

Step 2：生成幻灯片

python scripts/generate_slides.py \ --content "Your presentation content" \ --reference-image "https://example.com/template.jpg" \ --language "Auto"

该模式默认走异步（源码中mode=args.mode or "async"），但底层端点POST /slides/create-like-this实际总是同步完成并返回结果。脚本会做一次响应结构归一化：把 API 返回的data.jobUrl映射为slideUrl、data.downloadUrl映射为pdfUrl，见 generate_slides.py。

可选参数（取值以 api_constants.py 为准）：

--language LANG # Auto, English, Spanish, Arabic, Portuguese, Indonesian, # Japanese, Russian, Hindi, French, German, Greek, Vietnamese, # Turkish, Polish, Italian, Korean, Simplified Chinese, # Traditional Chinese, Thai (default: Auto) --mode sync|async # default: sync for theme, async for reference-image --aspect-ratio RATIO # 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 16:9) --resolution 1K|2K|4K # default: 2K --page N # 0=auto, 1-100 (default: 1) --content-detail concise|standard # default: concise

超时设计的源码细节：该模式按页数动态计算请求超时——max(120, page * 40)秒（约每页 30 秒生成、留出余量），详见 generate_slides.py。这与 api-reference.md 给出的"超时建议设为max(120, pages * 40)秒"一致。

注意：该模式走 Nano Banana Pro，积分成本为 1K/2K 每页 100 积分、4K 每页 200 积分。

Step 3：处理结果

{ "slideUrl": "https://2slides.com/workspace?jobId=...", "pdfUrl": "https://...pdf...", "status": "completed", "message": "Successfully generated N slides", "slidePageCount": N }

• slideUrl：在 2slides workspace 中查看在线幻灯片；
• pdfUrl：直接下载 PDF（1 小时后过期）。

典型处理时间约每页 30 秒，1～2 页通常 30～60 秒完成。

路径三：自定义 PDF 生成（Custom PDF Generation）

当用户想自定义设计但没提供参考图、直接要求"create PDF slides"、或希望指定设计特征时使用。相比主题生成，它对设计有更高的灵活度。

Step 1：整理内容

同样按"标题 + 分节 + 要点"的结构化格式准备输入。

Step 2：生成幻灯片

# 基础生成 python scripts/create_pdf_slides.py --content "Your content here" # 指定设计风格（对应 API 字段 designStyle） python scripts/create_pdf_slides.py \ --content "Sales Report Q4 2025" \ --design-style "modern minimalist, blue color scheme" # 高分辨率 + 自动页数检测 python scripts/create_pdf_slides.py \ --content "Marketing Plan" \ --resolution 4K \ --page 0 \ --content-detail standard

可选参数：

--design-style "text" # 设计指令（API 字段 designStyle / designSpec） --language LANG # 同 generate_slides（default: Auto） --aspect-ratio RATIO # 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 16:9) --resolution 1K|2K|4K # default: 2K --page N # 0=auto, 1-100 (default: 1) --content-detail concise|standard # default: standard

实现层面，create_pdf_slides.py 构造POST /slides/create-pdf-slides请求体，design_spec存在时才追加designSpec字段；--design-style与--design-spec是同一参数的两个别名，统一落到design_spec。超时同样按max(120, page * 40)动态计算。

Step 3：处理结果

返回结构与参考图模式一致（slideUrl+pdfUrl+status+message+slidePageCount），并自动生成 PDF。

注意：积分成本与参考图模式相同（1K/2K 每页 100 积分，4K 每页 200 积分）；处理时间约每页 30 秒；AI 会根据内容与设计规格自主生成定制设计。

路径四：文档摘要成稿（Document Summarization）

当用户上传文档（PDF、DOCX、TXT 等）并说"从这份文档生成幻灯片"时使用，适合把长内容压缩成演示格式。

Step 1：读取文档

根据文档类型选择读取工具：PDF 用 PDF 读取工具，DOCX 用 DOCX 读取工具，TXT/MD 直接读全文。

Step 2：提取要点

分析文档并提炼：主题与主旨、每个章节的关键点、重要数据/引文/示例、逻辑流与结构。

Step 3：结构化内容

把提取的信息组织成演示结构（可直接复用路径一的格式）：

Title: [Document Main Topic] Introduction - Context - Purpose - Overview [Section 1 from document] - Key point 1 - Key point 2 - Supporting detail [Section 2 from document] - Key point 1 - Key point 2 - Supporting detail Conclusion - Summary - Key takeaways - Next steps

Step 4：生成幻灯片

复用内容生成流程——先搜主题，再带主题 ID 生成：

# 搜索合适主题 python scripts/search_themes.py --query "business" # 带主题 ID 生成 python scripts/generate_slides.py --content "[Structured content from step 3]" --theme-id "theme123"

提示：每页保持 3～5 个要点；聚焦关键洞察而非全文照搬；用文档标题作幻灯片标题；纳入重要统计或引文；可询问用户是否突出特定章节。

路径五：AI 语音配音（Voice Narration）

为幻灯片添加 AI 语音，支持单人/多角色两种模式。

前置条件（重要）：必须在幻灯片生成任务完成后才能添加配音。先生成幻灯片并拿到 jobId，确认任务状态为completed后再发起配音请求；源码中若任务未完成，API 会返回JOB_NOT_COMPLETED错误码（见 api-reference.md 的错误码列表）。

Step 1：选择音色

共有 30 种音色可选，常见的有 Puck（默认）、Aoede、Charon、Kore、Fenrir、Phoebe 等。完整列表同时维护在 generate_narration.py 的AVAILABLE_VOICES与 api_constants.py 的NARRATION_VOICES中，两个清单略有出入，脚本侧以本地列表为准并会校验输入音色。列出全部音色：

python scripts/generate_narration.py --list-voices

Step 2：生成配音

# 默认音色基础配音 python scripts/generate_narration.py --job-id "abc-123-def-456" # 单角色指定音色 python scripts/generate_narration.py --job-id "abc-123-def-456" --voice Aoede # 多角色模式 python scripts/generate_narration.py --job-id "abc-123-def-456" --multi-speaker

参数说明（与 2slides API 对齐）：

• --job-id：必填，幻灯片生成的 Job ID（Nano Banana 任务需为 UUID 格式）；
• --voice：音色名，默认 Puck，--list-voices查看全部 30 种；
• --language：配音语言，默认 Auto；
• --multi-speaker：启用多角色模式（脚本中以action="store_true"实现，出现即开启）。

Step 3：检查状态

配音生成是异步的，用任务状态脚本轮询：

python scripts/get_job_status.py --job-id "abc-123-def-456"

Step 4：处理结果

任务完成后即可用下载端点（路径六）获取音频文件。

注意：成本为每页 210 积分（文本 10 + 音频 200）；处理时间随页数变化；支持 19 种以上语言与自动检测；多角色模式使用不同音色增加变化。

路径六：下载导出（Download Export）

把幻灯片导出为 PNG 图片、配音导出为 WAV 文件，并附带文稿，打包成 ZIP。

Step 1：确认任务完成

确保幻灯片（以及可选的配音）已生成且任务处于completed状态。

Step 2：下载压缩包

# 默认文件名（<job_id>.zip） python scripts/download_slides_pages_voices.py --job-id "abc-123-def-456" # 指定输出路径 python scripts/download_slides_pages_voices.py \ --job-id "abc-123-def-456" \ --output "my-presentation.zip"

Step 3：解压内容

ZIP 中包含：

• Pages：每页幻灯片的 PNG 文件；
• Voices：配音 WAV 音频（若生成了配音）；
• Transcripts：配音文字稿。

安全实现值得关注：download_slides_pages_voices.py 是安全加固最重的脚本，包含四层防护：

1. URL 校验：下载地址必须为 HTTPS 且解析到公网 IP（validate_public_https_url逐 IP 检查ip.is_global，防 SSRF）；
2. IP 固定下载：对解析出的 IP 建连，同时保留 TLS SNI/主机名校验（download_pinned_https），拒绝重定向；
3. 大小上限：单次下载上限 128 MiB（maximum_bytes = 128 * 1024 * 1024），超限即中止；
4. 原子写入：先写入同目录临时文件（权限 0600），完成后os.replace原子替换，避免半成品；输出路径限定在当前工作目录内（safe_user_path防止路径逃逸）。

注意：完全免费（不消耗积分）；下载 URL 仅1 小时有效；包含全部页面与配音文件；PNG 高清导出、WAV 音频格式。

路径七：主题检索（Theme Search）

用于生成前选择主题、回答"有哪些主题可用"、或需要专业/品牌化外观的场景。

# 按风格检索（query 必填） python scripts/search_themes.py --query "business" python scripts/search_themes.py --query "creative" python scripts/search_themes.py --query "education" python scripts/search_themes.py --query "professional" # 获取更多结果 python scripts/search_themes.py --query "modern" --limit 50

主题选择流程：

1. 向用户展示可用主题的名称与描述；
2. 让用户选择或使用默认主题；
3. 在生成请求中使用主题 ID。

使用 MCP Server 集成

如果已在 Claude Desktop 中配置 2slides MCP 服务，可以直接使用内置工具而非脚本。完整配置见 mcp-integration.md。

两种配置模式：

1. Streamable HTTP 协议（推荐）

   • 无需本地安装，配置最简单，始终使用最新版本；
   • 配置"url": "https://2slides.com/api/mcp?apikey=YOUR_API_KEY"。

2. NPM 包（stdio）

   • 使用本地 npm 包，需安装 Node.js/npm；
   • 配置"command": "npx", "args": ["2slides-mcp"]，并在env中设置 API Key。

可用 MCP 工具：

• slides_generate—— 从内容生成幻灯片；
• slides_create_like_this—— 从参考图生成；
• slides_create_pdf_slides—— 自定义 PDF 幻灯片（较新，需 MCP 服务端更新）；
• slides_generate_narration—— 添加 AI 配音（较新）；
• slides_download_pages_voices—— 导出页面与配音 ZIP（较新）；
• themes_search—— 检索主题；
• jobs_get—— 查询任务状态。

选型建议：Claude Desktop 环境优先用 MCP；Claude Code CLI 或无 MCP 环境用脚本。

脚本参数总览

所有脚本的参数取值均以 api_constants.py 中定义的枚举为准（语言 20 种、宽高比 10 种、分辨率 3 档、内容详细度 2 档、模式 2 种），并在适用处强制校验。

高级特性与生产实践

同步 vs 异步模式

• 同步模式（默认）：等待生成完成（约 30～60 秒），立即返回结果，适合快速演示；Fast PPT 默认同步。
• 异步模式：立即返回 jobId，用get_job_status.py轮询，适合长演示或批处理。推荐每 20～30 秒轮询一次，避免对服务端造成压力——这一建议同时出现在详细指南、API 参考与 SKILL.md 中。

从 API 最佳实践看（api-reference.md）：小于 5 页用同步，大于 5 页或需要集成到可轮询的工作流中用异步。

速率限制

不同端点限流不同：Fast PPT（generate）每分钟 10 次请求；Nano Banana（create-like-this、create-pdf-slides）每分钟 6 次。遇到限流应先等待再重试，或查看套餐限额。限流基于 API 层级而非积分余额。

积分成本模型

• Fast PPT（generate 端点）：每页 10 积分；
• Nano Banana 1K/2K（create-like-this、create-pdf-slides）：每页 100 积分；
• Nano Banana 4K：每页 200 积分；
• 语音配音：每页 210 积分（文本 10 + 音频 200）；
• 下载导出：免费。

积分套餐（当前促销最高 20% 折扣）：2,000 积分 $5.00、4,000 积分 $9.50（5% off）、10,000 积分 $22.50（10% off）、20,000 积分 $42.50（15% off）、40,000 积分 $80.00（20% off）。更多成本计算场景见 pricing.md。

下载链接过期

所有下载 URL（PDF、ZIP）仅 1 小时有效，生成后应立即下载，不可当作长期存储。

语言支持

--language接受完整语言名，除默认自动检测外支持：English、Simplified Chinese（简体中文）、Traditional Chinese（繁體中文）、Spanish、French、German、Japanese、Korean，以及 Arabic、Portuguese、Indonesian、Russian、Hindi、Vietnamese、Turkish、Polish、Italian、Greek、Thai 等。同一参数贯穿内容生成、自定义 PDF 与配音环节。

常见错误与处理

在源码中，get_job_status.py 还会对 Job ID 做字符白名单校验（^[A-Za-z0-9_-]+$），并对 API URL 做主机名/路径白名单校验（仅允许https://2slides.com/api/v1/jobs/前缀），非法输入直接拒绝，属于输入侧的安全加固。

获得最佳结果的实用建议

内容结构：

• 使用清晰的标题与副标题；
• 保持要点简洁；
• 每节控制在 3～5 个要点；
• 包含相关示例或数据。

主题选择：

• 标准生成必须提供主题 ID；
• 用与演示目的匹配的关键词检索（business、professional、creative、education、modern 等常见）；
• 每个主题有独特的样式与版式。

参考图：

• 使用高质量图片以获得最佳效果；
• 支持 URL 或 base64 编码图片；
• 公开 URL 必须可访问；
• 按质量需求选择分辨率（1K/2K/4K）；
• 用page=0自动检测页数。

文档处理：

• 只提取关键信息；
• 不要把整个文档塞进幻灯片；
• 聚焦核心洞察与要点；
• 询问用户希望突出哪些章节。

与其他技能的协作

该技能可与仓库中的youtube-full技能联动：先用@youtube-full抓取视频字幕等源材料，再交给本技能摘要成稿，形成"素材获取 → 演示成稿"的完整链路。

小结

2slides-ppt-generator用一套 7 个 Python 脚本 + 可选 MCP 工具封装了完整的 AI 演示生产流程。理解它的关键是三件事：选对路径（决策树）、算清成本（Fast PPT 10 积分/页，Nano Banana 100～200 积分/页，配音 210 积分/页，导出免费）、管理好异步任务（同步/异步选型、20～30 秒轮询、1 小时下载窗口）。配合脚本源码中的动态超时、参数白名单、SSRF 防护与原子写入等实现细节，你可以在自己的 Agent 工作流中可靠地复现"文字/图片/文档 → 在线幻灯片 + PDF + 配音 + PNG/WAV 导出"的完整链路。

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills