slidespeak-editor

SlideSpeak Presentation Editor

Edit an existing PowerPoint file to achieve batch modification and personalized customization by replacing the content of specified shapes.

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

API Specification Summary

Endpoint

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

Request Format

Content-Type: multipart/form-data
Headers: X-API-Key: YOUR_API_KEY

Required Parameters

pptx_file (file): The PowerPoint file to edit
config (json): A JSON object containing the replacement configuration

Config Structure

{
  "replacements": [
    {
      "shape_name": "TARGET_SHAPE_NAME",
      "content": "新内容"
    }
  ]
}

Response Format

{
  "url": "https://slidespeak-pptx-writer.s3.amazonaws.com/xxx.pptx"
}

Use Cases

1. Batch Personalized Generation

Template-based PPT batch generation (e.g., sales proposals, customer reports)
Replace customer names, data, logos, etc.

2. Content Updates

Update specific parts of an existing PPT
Modify titles, subtitles, body content

3. Multi-language Version Generation

Generate different language versions based on one template
Keep layout and design unchanged

4. Data-driven Reports

Read data from a database and populate it into a PPT template
Automatically generate periodic reports

Usage Workflow

Step 1: Prepare the Template PPT

Name the shapes that need to be replaced in PowerPoint:

Select a shape (text box, title, etc.)
Right-click → "Selection Pane"
Rename the shape to a meaningful name (e.g., TARGET_TITLE、TARGET_SUBTITLE、CLIENT_NAME , etc.)

Naming Suggestions：

Use clear prefixes:TARGET_, DATA_, CLIENT_
Use descriptive names:TITLE, SUBTITLE, CONTENT, DATE
Avoid special characters and spaces

Step 2: Identify the Shapes to Replace

Before using the skill, you need to know the shape names in the template. You can:

Check manually in PowerPoint (Selection Pane)
Extract using a Python script (see helper scripts)
Confirm the agreed naming convention with the template creator

Step 3: Prepare the Replacement Content

Prepare the replacement content according to business needs:

replacements = [
    {
        "shape_name": "CLIENT_NAME",
        "content": "ABC公司"
    },
    {
        "shape_name": "REPORT_DATE",
        "content": "2024年第四季度"
    },
    {
        "shape_name": "KEY_METRIC_1",
        "content": "销售额: ¥1,234,567"
    },
    {
        "shape_name": "SUMMARY_TEXT",
        "content": "本季度业绩表现优异，同比增长35%。主要驱动因素包括：新产品线推出、市场份额扩大、客户满意度提升。"
    }
]

Step 4: Call the Editing Tool

Use the slidespeak_edit tool:

slidespeak_edit(
    pptx_file_path="/path/to/template.pptx",  # 模板文件路径
    config={
        "replacements": [
            {
                "shape_name": "CLIENT_NAME",
                "content": "ABC公司"
            },
            {
                "shape_name": "REPORT_TITLE",
                "content": "2024 Q4 业绩报告"
            },
            # ... 更多替换
        ]
    },
    save_dir="./outputs/edited_ppt"  # 保存目录
)

Best Practices

1. Template Design Principles

Clear Naming Conventions：

# 推荐的命名模式
TITLE_SLIDE_1          # 第一页标题
SUBTITLE_SLIDE_1       # 第一页副标题
CONTENT_SLIDE_2_MAIN   # 第二页主要内容
CONTENT_SLIDE_2_SUB    # 第二页次要内容
DATA_CHART_TITLE       # 图表标题

Naming to Avoid：

# 不推荐（太通用）
TextBox1
Shape2
Rectangle3

2. Content Formatting

Text Content：

Supports line breaks \n
Keep text length moderate (avoid overflow)
Use consistent punctuation

Numeric Format：

# 推荐
"content": "销售额: ¥1,234,567"
"content": "增长率: 35.2%"
"content": "客户数: 1,234 家"

# 不推荐
"content": "1234567"  # 缺少上下文

Date Format：

# 清晰的日期格式
"content": "2024年12月25日"
"content": "2024-12-25"
"content": "Q4 2024"

3. Error Handling

Common Errors：

Error	Cause	Solution
Shape not found	shape_name does not exist	Check the shape names in the template
Content too long	Text exceeds the shape size	Shorten the content or adjust the template
Invalid file	PPT file is corrupted	Use a valid .pptx file
API error	API key or network issue	Check the API configuration

Fault Tolerance Strategy：

# 建议：先验证 shape 是否存在
# 可以使用 helper script 提取所有 shape 名称

replacements = []
for shape_name, content in data.items():
    if shape_name in valid_shape_names:
        replacements.append({
            "shape_name": shape_name,
            "content": content
        })
    else:
        print(f"⚠️ Warning: Shape '{shape_name}' not found in template")

4. Batch Processing Mode

# 场景：为多个客户生成个性化 PPT

clients = [
    {"name": "ABC公司", "sales": "¥1M", "growth": "35%"},
    {"name": "XYZ集团", "sales": "¥2M", "growth": "42%"},
    # ...
]

for client in clients:
    slidespeak_edit(
        pptx_file_path="templates/client_report.pptx",
        config={
            "replacements": [
                {"shape_name": "CLIENT_NAME", "content": client["name"]},
                {"shape_name": "SALES_AMOUNT", "content": client["sales"]},
                {"shape_name": "GROWTH_RATE", "content": client["growth"]},
            ]
        },
        save_dir=f"./outputs/clients/{client['name']}"
    )

Helper Scripts

1. Extract Shape Names

# 查看模板中所有可替换的 shape
python3 scripts/extract_shapes.py /path/to/template.pptx

2. Validate the Replacement Configuration

# 验证 config 是否有效
python3 scripts/validate_config.py --template template.pptx --config config.json

3. Batch Editing

# 从 CSV 批量生成
python3 scripts/batch_edit.py --template template.pptx --data data.csv --output ./outputs

Tool Call Format

# 基本用法
slidespeak_edit(
    pptx_file_path="./templates/quarterly_report.pptx",
    config={
        "replacements": [
            {"shape_name": "REPORT_TITLE", "content": "2024 Q4 财务报告"},
            {"shape_name": "COMPANY_NAME", "content": "科技有限公司"},
            {"shape_name": "QUARTER", "content": "第四季度"},
            {"shape_name": "REVENUE", "content": "¥12,345,678"},
            {"shape_name": "PROFIT", "content": "¥2,345,678"},
            {"shape_name": "GROWTH", "content": "+35.2%"}
        ]
    },
    save_dir="./outputs/reports"
)

Comparison with slidespeak-generator

Feature	slidespeak-generator	slidespeak-editor
Purpose	Generate a new PPT from scratch	Edit an existing PPT template
Input	Content and layout configuration	Template file + replacement content
Flexibility	High (freely create any layout)	Medium (constrained by the template)
Consistency	Medium (may differ each time)	High (based on a fixed template)
Use cases	Creative, diverse content	Standardized, batch generation
Speed	Slower (layout needs to be generated)	Faster (only content is replaced)

Usage recommendations：

Needflexible layoutandcreative design → use slidespeak-generator
Needstandardizationandbatch processing → use slidespeak-editor
Complex scenarios: first use generator to generate a template, then use editor for batch personalization

Success criteria

✅ Correctness：

All shape_name values exist in the template
Content is successfully replaced in the corresponding positions
The generated PPT can be opened normally

✅ Quality：

Text length is moderate, with no overflow
Formatting remains consistent (font, color, etc.)
Content semantics are clear and accurate

✅ Efficiency：

High efficiency during batch processing
Reduce manual operation errors
Reusable templates

Troubleshooting

Issue 1: Shape not found

错误信息: "Shape 'XXX' not found"
解决: 
1. 在 PowerPoint 中打开模板
2. 查看"选择窗格"确认 shape 名称
3. 确保名称拼写正确（区分大小写）

Issue 2: Content overflow

现象: 文本被截断或显示不全
解决:
1. 缩短替换内容
2. 调整模板中形状的大小
3. 使用自动缩放的文本框

Issue 3: API call failed

检查清单:
- [ ] API key 是否正确
- [ ] 文件是否存在且可读
- [ ] 文件格式是否为 .pptx（不支持 .ppt）
- [ ] 网络连接是否正常

Advanced usage

1. Dynamic content generation

# 从数据库读取数据并填充
from database import get_quarterly_data

data = get_quarterly_data(year=2024, quarter=4)

slidespeak_edit(
    pptx_file_path="templates/report.pptx",
    config={
        "replacements": [
            {"shape_name": "REVENUE", "content": f"¥{data.revenue:,.0f}"},
            {"shape_name": "PROFIT", "content": f"¥{data.profit:,.0f}"},
            {"shape_name": "GROWTH", "content": f"+{data.growth:.1f}%"},
            {"shape_name": "SUMMARY", "content": data.generate_summary()}
        ]
    }
)

2. Conditional replacement

# 根据条件决定替换内容
if growth_rate > 30:
    status_text = "🎉 表现优异"
    status_color = "green"
elif growth_rate > 10:
    status_text = "✓ 稳步增长"
    status_color = "blue"
else:
    status_text = "⚠️ 需要关注"
    status_color = "yellow"

slidespeak_edit(
    pptx_file_path="template.pptx",
    config={
        "replacements": [
            {"shape_name": "STATUS_TEXT", "content": status_text}
        ]
    }
)

3. Multi-page replacement

# 对模板中的多个页面进行替换
slidespeak_edit(
    pptx_file_path="multi_page_template.pptx",
    config={
        "replacements": [
            # 封面页
            {"shape_name": "COVER_TITLE", "content": "年度总结报告"},
            {"shape_name": "COVER_SUBTITLE", "content": "2024年度"},
            
            # 内容页
            {"shape_name": "SLIDE2_TITLE", "content": "业绩概览"},
            {"shape_name": "SLIDE2_CONTENT", "content": "..."},
            
            # 总结页
            {"shape_name": "CONCLUSION_TEXT", "content": "感谢观看！"}
        ]
    }
)

Reference resources

Official documentation: SlideSpeak Edit API
API Schema: resources/edit_api_schema.json
Example templates: resources/example_template.pptx
Batch processing scripts: scripts/batch_edit.py