slidespeak-slide-editor

SlideSpeak Slide Editor

Edit generated PPTs in the SlideSpeak system, supporting intelligent addition, regeneration, or deletion of slides.

API Documentation: https://docs.slidespeak.co/basics/api-references/edit-slide/

API Specification Summary

Endpoint

POST https://api.slidespeak.co/api/v1/presentation/edit/slide

Three Editing Operations

Operation	Description	Credits Consumed	Prompt Required
INSERT	Insert a new slide at the specified position	✅ 1 credit	✅ Yes
REGENERATE	Regenerate an existing slide	✅ 1 credit	✅ Yes
REMOVE	Delete the slide at the specified position	❌ 0 credit	❌ No

Required Parameters

presentation_id (string): The ID of the PPT (obtained at generation time)
edit_type (enum): INSERT | REGENERATE | REMOVE
position (number): Slide position index (starting from 0)
prompt (string): Content description (required for INSERT/REGENERATE)

Optional Parameters

document_uuids: List of UUIDs of reference documents
fetch_images: Whether to include images (inherited from PPT settings)
verbosity: concise | standard | text-heavy
tone: default | casual | professional | funny | educational | sales_pitch
add_speaker_notes: Whether to add speaker notes
use_general_knowledge: Whether to use general knowledge expansion
use_wording_from_document: Whether to use the original document text
use_document_images: Whether to use images from the document

Asynchronous Processing

1. 发送编辑请求 → 返回 task_id
2. 轮询 /task_status/{task_id} 直到 status = "SUCCESS"
3. 使用 task_result 中的 url 下载编辑后的 PPT

Use Cases

1. Continuously refine the PPT in conversation

用户: "帮我生成一个产品介绍 PPT"
Agent: [生成 PPT，保存 presentation_id]

用户: "在第3页后添加一页关于定价方案的内容"
Agent: [使用 slidespeak_edit_slide]
      → INSERT at position=3
      → prompt="添加定价方案页，包含三个套餐"

用户: "把第5页重新生成，要更详细一些"
Agent: [使用 slidespeak_edit_slide]
      → REGENERATE at position=4
      → prompt="重新生成，添加更多技术细节"

用户: "删除第7页"
Agent: [使用 slidespeak_edit_slide]
      → REMOVE at position=6

2. Rapid iterative optimization

用户: "这个 PPT 的市场分析页面太简单了，帮我扩展成两页"
Agent: 
  1. REGENERATE 原页面（更详细）
  2. INSERT 新页面（添加补充内容）

3. Dynamically adjust the structure

用户: "把所有关于竞争对手的内容集中到一起"
Agent:
  1. INSERT 新的"竞争分析"页
  2. 整合现有相关内容
  3. REMOVE 旧的分散页面

Usage Flow

Automatic Flow (Recommended)

The system will automatically extract from the conversation history presentation_id：

# 第一步：生成 PPT
用户: "生成一个关于 AI 的 PPT"
Agent: [slidespeak-generator] → presentation_id = "xxx"
       [自动保存到对话上下文]

# 第二步：编辑 PPT（自动识别）
用户: "在第2页后添加一页关于机器学习的内容"
Agent: [自动提取 presentation_id]
       [理解意图：INSERT at position=2]
       [调用 slidespeak_edit_slide]

Manual Specification (Advanced Usage)

If you need to edit a previous PPT:

用户: "编辑 presentation_id 为 cmgt32cut0000h3ovex8dbzmn 的 PPT，
      在第5页后添加总结页"
Agent: [使用指定的 presentation_id]

Intent Recognition Rules

INSERT Keywords

"Add a page..."
"Insert a slide..."
"Add after page X..."
"Add a new page..."
"Supplement a page..."

Example：

用户: "在第3页后添加一页关于团队介绍的内容"
→ edit_type: INSERT
→ position: 3
→ prompt: "添加团队介绍页，包含核心成员和角色"

REGENERATE Keywords

"Regenerate page X..."
"Change page X to..."
"Optimize page X..."
"Page X should be more detailed..."
"Adjust the content of page X..."

Example：

用户: "把第5页重新生成，要包含图表"
→ edit_type: REGENERATE
→ position: 4 (索引从0开始)
→ prompt: "重新生成，使用图表布局展示数据"

REMOVE Keywords

"Delete page X"
"Remove page X"
"Remove page X"
"No longer need page X"

Example：

用户: "删除第7页"
→ edit_type: REMOVE
→ position: 6
→ prompt: null

Position Index Explanation

⚠️ Important: SlideSpeak uses absolute indexing (starting from 0)

幻灯片结构：
[0] 封面（Cover）              ← 不能编辑
[1] 目录（Table of Contents）   ← 不能编辑
[2] 第一页内容                  ← 可以编辑
[3] 第二页内容                  ← 可以编辑
[4] 第三页内容                  ← 可以编辑
...

If the user says "page 3", what is the actual index?

It depends on whether the PPT has a cover and table of contents:

What the user says	Has cover + table of contents	Cover only	No cover
Page 1 content	position=2	position=1	position=0
Page 2 content	position=3	position=2	position=1
Page 3 content	position=4	position=3	position=2

Recommended Strategy：

Ask the user: Does the cover count as page 1?
Automatically calculate the offset based on the configuration at generation time
Provide friendly error messages

Prompt Writing Principles

Good Prompt

# ✅ 清晰、具体、可执行
"添加一页关于产品定价的幻灯片，包含三个套餐（基础版、专业版、企业版），
 每个套餐列出价格、核心功能和适用场景。使用对比布局。"

# ✅ 指定布局和风格
"重新生成这一页，使用 CHART 布局展示季度销售数据，
 包含柱状图和增长趋势线。采用专业商务风格。"

# ✅ 明确内容要求
"插入一页团队介绍，包含5位核心成员的姓名、职位、
 主要职责和代表性成就。使用 ITEMS 布局。"

Bad Prompt

# ❌ 太模糊
"添加一页内容"
→ AI 不知道要生成什么

# ❌ 太长太复杂
"添加一页关于市场分析的内容，要包括市场规模、增长趋势、
 竞争格局、用户画像、痛点分析、解决方案、商业模式、
 竞争优势、风险分析、未来展望..."
→ 一页放不下，应该拆分成多页

# ❌ 缺少上下文
"把这一页改一下"
→ 改成什么样？

Tool Call Format

Basic Usage

slidespeak_edit_slide(
    presentation_id="cmgt32cut0000h3ovex8dbzmn",
    edit_type="INSERT",
    position=3,
    prompt="添加一页关于市场分析的内容，包含市场规模、增长趋势、竞争格局三个要点",
    fetch_images=True,
    tone="professional",
    verbosity="standard"
)

Insert New Slide

slidespeak_edit_slide(
    presentation_id="cmgt32cut0000h3ovex8dbzmn",
    edit_type="INSERT",
    position=2,  # 在第2页后插入
    prompt="添加产品特性页，列出5个核心功能：AI驱动、实时协作、云端存储、跨平台、安全加密",
    fetch_images=True,
    verbosity="standard",
    tone="professional"
)

Regenerate Slide

slidespeak_edit_slide(
    presentation_id="cmgt32cut0000h3ovex8dbzmn",
    edit_type="REGENERATE",
    position=4,  # 重新生成第5页
    prompt="重新生成这一页，使用 COMPARISON 布局对比传统方案和我们的方案，突出我们的优势",
    verbosity="text-heavy"  # 更详细
)

Delete Slide

slidespeak_edit_slide(
    presentation_id="cmgt32cut0000h3ovex8dbzmn",
    edit_type="REMOVE",
    position=6,  # 删除第7页
    prompt=None  # REMOVE 不需要 prompt
)

Using document content

# 先上传文档，获得 document_uuid
# 然后在编辑时引用
slidespeak_edit_slide(
    presentation_id="cmgt32cut0000h3ovex8dbzmn",
    edit_type="INSERT",
    position=5,
    prompt="根据上传的市场报告，添加一页总结市场趋势",
    document_uuids=["b12f2c9c-1a2b-4d3e-9f4a-5b6c7d8e9f01"],
    use_wording_from_document=True,
    use_document_images=True
)

Asynchronous processing mechanism

The Edit Slide API is asynchronous and requires polling the task status:

# 1. 发送编辑请求
response = slidespeak_edit_slide(...)
task_id = response["task_id"]

# 2. 轮询任务状态（由工具自动处理）
while True:
    status = check_task_status(task_id)
    
    if status == "SUCCESS":
        # 任务完成
        download_url = get_download_url(task_id)
        break
    elif status == "FAILED":
        # 任务失败
        raise Exception("Edit failed")
    else:
        # 继续等待
        await sleep(2)  # 每2秒检查一次

User experience optimization：

用户: "在第3页后添加一页"
Agent: 
  → "正在添加幻灯片... 🔄"
  → [轮询中]
  → "添加成功！已更新 PPT ✅"
  → [提供下载链接]

Error handling

Common errors

Error	Cause	Solution
`presentation_id not found`	ID does not exist	Check whether the ID is correct
`Invalid position`	Position out of range	Use a valid index
`Cannot edit cover/TOC`	Attempting to edit the cover/table of contents	Only edit content pages
`Prompt required for INSERT`	INSERT is missing prompt	Provide a content description
`Task timeout`	Task timeout	Check the network and retry

Fault tolerance strategy

# 建议：增加重试机制
max_retries = 3
for attempt in range(max_retries):
    try:
        result = slidespeak_edit_slide(...)
        if result["success"]:
            break
    except Exception as e:
        if attempt == max_retries - 1:
            raise
        print(f"重试 {attempt + 1}/{max_retries}...")
        await sleep(5)

Best practices

1. Maintain conversation state

# 在生成 PPT 时保存 presentation_id
class ConversationState:
    def __init__(self):
        self.current_presentation_id = None
        self.presentation_metadata = {}
    
    def save_presentation(self, pres_id, metadata):
        self.current_presentation_id = pres_id
        self.presentation_metadata[pres_id] = metadata

2. Intelligent index calculation

def calculate_position(user_page_number, has_cover, has_toc):
    """
    计算实际的 position 索引
    
    Args:
        user_page_number: 用户说的页码（1-based）
        has_cover: 是否有封面
        has_toc: 是否有目录
    
    Returns:
        实际的 position 索引（0-based）
    """
    offset = 0
    if has_cover:
        offset += 1
    if has_toc:
        offset += 1
    
    return user_page_number - 1 + offset

3. Batch operations

# 场景：一次性进行多个编辑
edits = [
    {"type": "INSERT", "position": 3, "prompt": "..."},
    {"type": "REGENERATE", "position": 5, "prompt": "..."},
    {"type": "REMOVE", "position": 8}
]

for edit in edits:
    result = slidespeak_edit_slide(
        presentation_id=pres_id,
        edit_type=edit["type"],
        position=edit["position"],
        prompt=edit.get("prompt")
    )
    # 等待每个操作完成
    wait_for_completion(result["task_id"])

4. User confirmation mechanism

# 对于重要操作，先确认
用户: "删除第5页"
Agent: "确认要删除第5页（市场分析）吗？这个操作不可撤销。"
用户: "确认"
Agent: [执行删除]

Collaboration with other Skills

Working with slidespeak-generator

1. slidespeak-generator: 生成初始 PPT
   → 返回 presentation_id
   
2. slidespeak-slide-editor: 迭代完善
   → INSERT: 添加缺失内容
   → REGENERATE: 优化现有页面
   → REMOVE: 删除多余页面
   
3. slidespeak-editor: 批量个性化
   → 替换客户名称、数据等

Typical workflow

用户: "生成一个产品 PPT"
  ↓ slidespeak-generator
  [生成基础 PPT，10页]
  
用户: "添加一页定价方案"
  ↓ slidespeak-slide-editor (INSERT)
  [在合适位置插入定价页]
  
用户: "第3页太简单了，重新生成详细一点"
  ↓ slidespeak-slide-editor (REGENERATE)
  [重新生成第3页]
  
用户: "把公司名称都改成'ABC科技'"
  ↓ slidespeak-editor
  [批量替换所有页面的公司名]

Success criteria

✅ Functional correctness：

Correctly identify the editing intent (INSERT/REGENERATE/REMOVE)
Accurately calculate the position index
Successfully handle asynchronous tasks

✅ Content quality：

Prompt is clear and explicit
Generated content meets requirements
Layout selection is reasonable

✅ User experience：

Fast response (reasonable waiting time)
Friendly progress prompts
Clear error messages

Troubleshooting

Issue 1: presentation_id cannot be found

现象: "Presentation not found"

可能原因:
1. PPT 刚生成，ID 还未保存
2. 对话历史被清空
3. ID 输入错误

解决方案:
1. 检查对话历史中的 ID
2. 让用户提供下载链接中的 ID
3. 重新生成 PPT

Issue 2: The task stays PENDING

现象: 轮询超时

可能原因:
1. 服务器负载高
2. Prompt 太复杂
3. 网络问题

解决方案:
1. 延长超时时间
2. 简化 Prompt
3. 检查网络连接
4. 联系 SlideSpeak 支持

Issue 3: Index error

现象: "Invalid position"

可能原因:
1. position 超出范围
2. 封面/目录偏移量计算错误

解决方案:
1. 检查 PPT 总页数
2. 确认是否有封面和目录
3. 使用正确的索引计算

Reference resources

Official API documentation: SlideSpeak Edit Slide
Asynchronous task processing: Get Task Status
Download PPT: Download Presentation
Architecture documentation: 00-ARCHITECTURE-OVERVIEW.md

About this skill

API Specification Summary

Endpoint

Three Editing Operations

Required Parameters

Optional Parameters

Asynchronous Processing

Use Cases

1. Continuously refine the PPT in conversation

2. Rapid iterative optimization

3. Dynamically adjust the structure

Usage Flow

Automatic Flow (Recommended)

Manual Specification (Advanced Usage)

Intent Recognition Rules

INSERT Keywords

REGENERATE Keywords

REMOVE Keywords

Position Index Explanation

Prompt Writing Principles

Good Prompt

Bad Prompt

Tool Call Format

Basic Usage

Insert New Slide

Regenerate Slide

Delete Slide

Using document content

Asynchronous processing mechanism

Error handling

Common errors

Fault tolerance strategy

Best practices

1. Maintain conversation state

2. Intelligent index calculation

3. Batch operations

4. User confirmation mechanism

Collaboration with other Skills

Working with slidespeak-generator

Typical workflow

Success criteria

Troubleshooting

Issue 1: presentation_id cannot be found

Issue 2: The task stays PENDING

Issue 3: Index error

Reference resources