OmyPPT Logo
返回博客
AI PPT SDK 集成指南：在你的应用中嵌入演示生成能力
开发者指南2025-10-295 min readOmyPPT 团队

AI PPT SDK 集成指南：在你的应用中嵌入演示生成能力

从零开始，用 OmyPPT SDK 在你的 Web 应用、移动端或桌面软件中集成 AI 演示生成功能。完整代码示例和最佳实践。

核心结论

OmyPPT 提供 Python 和 JavaScript 两种 SDK，支持从简单的"上传文档生成 PPT"到复杂的"多步骤自动化工作流"的完整集成。10 行代码就能实现基本的演示生成功能，完整的品牌定制和批量处理也只需要 50 行以内的代码。本文覆盖从安装到部署的完整流程。

深度分析

快速开始：5 分钟集成

Python SDK 安装和初始化

pip install omyppt-sdk

from omyppt import OmyPPT

# 初始化客户端
client = OmyPPT(api_key="your-api-key")

# 最简单的用法：从文件生成 PPT
result = client.generate("./report.pdf")

# 下载生成的 PPTX
result.download("./output/report.pptx")

print(f"生成完成！共 {result.page_count} 页")

JavaScript SDK 安装和初始化

npm install @omyppt/sdk

import { OmyPPT } from '@omyppt/sdk';

// 初始化客户端
const client = new OmyPPT({ apiKey: 'your-api-key' });

// 从文件生成 PPT
const result = await client.generate('./report.pdf');

// 下载生成的 PPTX
await result.download('./output/report.pptx');

console.log(`生成完成！共 ${result.pageCount} 页`);

这就是最基本的集成——3 行核心代码。

进阶功能：完整的项目管理

OmyPPT 的 SDK 支持完整的项目管理生命周期：

from omyppt import OmyPPT

client = OmyPPT(api_key="your-api-key")

# 1. 创建项目
project = client.projects.create(
    name="Q2 季度汇报",
    format="ppt169",  # 16:9 宽屏
    locale="zh-CN"
)

# 2. 导入源文档
project.import_sources([
    "./q2_report.pdf",
    "./sales_data.xlsx",
    "https://example.com/market-analysis"
])

# 3. 设置品牌
project.set_brand("company-brand-id")

# 4. 生成演示文稿
generation = project.generate(
    auto_confirm=False,  # 手动确认策略
    quality_check=True   # 启用质量检查
)

# 5. 查看策略提案
for proposal in generation.strategy.proposals:
    print(f"{proposal.name}: {proposal.description}")
    # 可以修改提案
    if proposal.name == "color_scheme":
        proposal.override(colors=["#1a5276", "#2e86c1", "#85c1e9"])

# 6. 确认并继续生成
generation.confirm()

# 7. 等待生成完成
generation.wait_for_completion()

# 8. 质量检查报告
report = generation.quality_report
print(f"质量评分: {report.score}/100")
if report.issues:
    for issue in report.issues:
        print(f"  - {issue.severity}: {issue.description}")

# 9. 下载 PPTX
generation.download("./output/q2_report.pptx")

# 10. 下载 SVG 预览
generation.download_previews("./output/previews/")

Webhook 集成：异步模式

对于生产环境，推荐使用异步模式 + Webhook 回调：

from flask import Flask, request

app = Flask(__name__)
client = OmyPPT(api_key="your-api-key")

# 提交生成任务
@app.post("/api/generate")
def start_generation():
    data = request.json

    generation = client.generations.create(
        source_url=data["source_url"],
        brand_id=data.get("brand_id"),
        webhook_url="https://your-app.com/webhook/omyppt",
        metadata={"user_id": data["user_id"]}
    )

    return {"generation_id": generation.id, "status": "processing"}

# 接收回调
@app.post("/webhook/omyppt")
def handle_webhook():
    event = client.webhooks.verify(request.json, request.headers)

    if event.type == "generation.completed":
        # 获取下载链接
        download_url = event.data.download_url
        user_id = event.data.metadata["user_id"]

        # 通知用户
        notify_user(user_id, download_url)

    elif event.type == "generation.failed":
        # 处理失败
        log_error(event.data.error)

    return {"status": "ok"}

批量生成：处理大量文件

import os
from pathlib import Path
from omyppt import OmyPPT

client = OmyPPT(api_key="your-api-key")

def batch_generate(
    source_dir: str,
    output_dir: str,
    brand_id: str | None = None
) -> list[dict]:
    """批量从目录中的文件生成 PPT。"""
    sources = Path(source_dir).glob("*.pdf")
    results = []

    for source in sources:
        try:
            result = client.generate(
                source=str(source),
                brand_id=brand_id,
                quality_check=True
            )

            output_path = Path(output_dir) / f"{source.stem}.pptx"
            result.download(str(output_path))

            results.append({
                "source": str(source),
                "output": str(output_path),
                "pages": result.page_count,
                "score": result.quality_report.score,
                "status": "success"
            })

        except Exception as e:
            results.append({
                "source": str(source),
                "status": "failed",
                "error": str(e)
            })

    return results

# 使用示例
results = batch_generate(
    source_dir="./reports/",
    output_dir="./presentations/",
    brand_id="company-brand"
)

# 打印结果摘要
successes = [r for r in results if r["status"] == "success"]
failures = [r for r in results if r["status"] == "failed"]
print(f"成功: {len(successes)}, 失败: {len(failures)}")

错误处理和重试

from omyppt import OmyPPT, OmyPPTError, RateLimitError, GenerationError
import time

client = OmyPPT(api_key="your-api-key")

def generate_with_retry(
    source: str,
    max_retries: int = 3,
    brand_id: str | None = None
) -> object:
    """带重试的生成函数。"""
    for attempt in range(max_retries):
        try:
            result = client.generate(
                source=source,
                brand_id=brand_id
            )
            return result

        except RateLimitError as e:
            # 速率限制，等待后重试
            wait_time = e.retry_after or (2 ** attempt)
            print(f"速率限制，等待 {wait_time} 秒...")
            time.sleep(wait_time)

        except GenerationError as e:
            # 生成失败，检查是否可重试
            if e.retryable and attempt < max_retries - 1:
                print(f"生成失败（尝试 {attempt + 1}/{max_retries}）: {e}")
                time.sleep(2 ** attempt)
            else:
                raise

    raise GenerationError("超过最大重试次数")

集成到 Web 框架

Django 集成示例：

# views.py
from django.http import JsonResponse
from django.views import View
from omyppt import OmyPPT

client = OmyPPT(api_key=settings.OMYPPT_API_KEY)

class GeneratePresentationView(View):
    def post(self, request):
        uploaded_file = request.FILES.get("file")
        if not uploaded_file:
            return JsonResponse({"error": "请上传文件"}, status=400)

        # 保存上传的文件
        temp_path = f"/tmp/{uploaded_file.name}"
        with open(temp_path, "wb") as f:
            for chunk in uploaded_file.chunks():
                f.write(chunk)

        try:
            result = client.generate(
                source=temp_path,
                brand_id=request.POST.get("brand_id"),
                webhook_url=settings.OMYPPT_WEBHOOK_URL,
                metadata={"user_id": request.user.id}
            )

            return JsonResponse({
                "generation_id": result.id,
                "status": "processing"
            })

        except OmyPPTError as e:
            return JsonResponse({"error": str(e)}, status=500)

Next.js 集成示例：

// app/api/generate/route.ts
import { OmyPPT } from '@omyppt/sdk';
import { NextRequest, NextResponse } from 'next/server';

const client = new OmyPPT({
  apiKey: process.env.OMYPPT_API_KEY!
});

export async function POST(request: NextRequest) {
  const formData = await request.formData();
  const file = formData.get('file') as File;
  const brandId = formData.get('brandId') as string;

  if (!file) {
    return NextResponse.json(
      { error: '请上传文件' },
      { status: 400 }
    );
  }

  const buffer = Buffer.from(await file.arrayBuffer());

  const result = await client.generate({
    source: buffer,
    filename: file.name,
    brandId,
    webhookUrl: `${process.env.APP_URL}/api/webhook/omyppt`
  });

  return NextResponse.json({
    generationId: result.id,
    status: 'processing'
  });
}

实用建议

API Key 管理

  • 不要在代码中硬编码 API Key，使用环境变量
  • 为不同环境（开发、测试、生产）使用不同的 Key
  • 定期轮换 API Key
  • 使用只读 Key 用于前端展示场景

性能优化

  • 对于批量生成，使用异步模式避免阻塞
  • 缓存已生成的 PPTX，避免重复生成
  • 预热品牌配置，减少每次生成的初始化时间
  • 使用 CDN 分发生成的 PPTX 文件

常见问题

SDK 支持 Node.js 吗？

支持。JavaScript SDK 兼容 Node.js 18+ 和现代浏览器环境。

生成速率限制是多少？

Pro 版每分钟 10 次请求，Team 版每分钟 30 次，Enterprise 版可定制。超过限制会返回 429 状态码，SDK 内置自动重试机制。

文件大小有限制吗？

单文件最大 50MB。超过这个限制建议先压缩文件或拆分为多个文件。

写在最后

SDK 集成的核心原则是"简单的事简单做，复杂的事能做"。OmyPPT SDK 的设计遵循这个原则——3 行代码完成基本功能，完整的 API 覆盖所有高级场景。

获取 API Key，开始你的集成。注册开发者账号。

SDK集成开发者指南API集成代码示例

准备好体验 AI 驱动的演示文稿了吗？

输入主题或上传文档，OmyPPT 帮你几分钟生成专业级 PPT

免费开始使用

相关文章

开发者指南

开源 PPT 工具生态：社区力量驱动的演示未来

2025-11-12开发者指南

Python PPT 自动化：用代码批量生成演示文稿的完整方案

2025-11-10开发者指南

PPT 生成工作流编排：从源文件到成品的自动化实践

2025-11-07