2slides API 教程 - AI 演示文稿生成完整指南

欢迎阅读 2slides API 综合指南！本教程将引导您了解所需的一切，以便将 AI 驱动的演示文稿生成功能集成到您的应用程序中。

概述

2slides API 允许您使用 AI 以编程方式生成专业的演示文稿。它支持多种演示文稿类型，包括时间轴、路线图、思维导图等，您可以通过简单的文本输入创建精美的幻灯片。

主要功能

• AI 驱动生成：从文本自动创建专业演示文稿
• 多种模板类型：支持时间轴、路线图、思维导图、商业演示文稿 (pitch decks)、信息图表等
• 多语言支持：生成多种语言的内容
• 丰富的模板库：访问数百个专业设计的模板
• 自定义模板：上传并使用您自己的自定义幻灯片模板
• 搜索模板：通过名称、关键词和标签搜索模板
• 下载选项：以 PowerPoint (.pptx) 格式获取演示文稿
• 实时状态跟踪：通过任务状态端点监控生成进度

特色演示文稿类型

所有演示文稿模板均可在此处获取：2slides Templates。具体来说，有一些特色演示文稿类型非常适合特定目的和场景。

1. 时间轴幻灯片 - 非常适合项目时间轴和历史事件
2. 路线图幻灯片 - 产品路线图和项目规划的理想选择
3. 思维导图幻灯片 - 非常适合概念映射和知识结构

开始使用

基础 URL

所有 API 请求都应发送至：

https://2slides.com

先决条件

1. 账户设置：在 2slides.com 创建账户
2. API 密钥：从您的 API 管理页面 生成 API 密钥
3. 积分：确保您有足够的积分用于幻灯片生成（每页幻灯片 10 积分）

快速入门

1. 获取您的 API 密钥：从 API 管理页面
2. 搜索主题：使用主题搜索端点，或浏览 模板 以获取幻灯片主题 ID
3. 生成幻灯片：使用您的内容和选定的主题 ID，这支持同步调用（返回结果幻灯片）和异步调用（返回任务 ID）。如果使用同步调用，则无需执行步骤 4 和 5。
4. 检查任务状态：直到完成，届时将提供生成的幻灯片下载 URL
5. 下载您的演示文稿：使用提供的下载 URL

身份验证

所有 API 端点都需要使用 API 密钥进行身份验证。您可以通过 API 管理界面 管理您的 API 密钥。

API 密钥格式

API 密钥遵循以下格式：

sk-2slides-{64-character-hex-string}

身份验证方法

授权请求头

Authorization: Bearer sk-2slides-your-api-key-here

API 密钥管理

• 最大密钥数量：每个用户最多可以创建 10 个 API 密钥
• 密钥命名：为您的密钥提供描述性名称以便于识别
• 安全性：妥善保管您的 API 密钥，切勿公开分享
• 轮换：定期轮换您的 API 密钥以增强安全性

⚠️ 重要安全提示：出于安全原因，2slides 平台不会以明文形式存储您的 API 密钥。生成后，您必须立即复制并安全存储您的 API 密钥。如果您丢失了 API 密钥，则需要生成一个新的，因为原始密钥无法恢复。

API 端点

1. 生成幻灯片 (Fast PPT)

使用特定主题从文本输入生成幻灯片 (Fast PPT)。

端点：

请求头：

Authorization: Bearer sk-2slides-your-api-key-here
Content-Type: application/json

请求体：

{
  "userInput": "Your presentation content here...",
  "themeId": "theme-uuid-here",
  "responseLanguage": "Auto"
}

参数：

• userInput
  (必需)：您要生成幻灯片的内容
• themeId
  (必需)：用于幻灯片生成的主题 ID。这可以是：
  • 来自 模板库 的公共主题
  • 您自己上传的自定义主题（可通过您的账户访问）
• responseLanguage
  (可选)：生成幻灯片的语言。使用“Auto”进行自动检测
• mode
  (可选)：同步 (sync) 或异步 (async) 调用，默认为“sync”

可用语言：

• Auto
  - 从输入自动检测语言（默认）
• English
  - 英语
• Simplified Chinese
  - 简体中文
• Traditional Chinese
  - 繁體中文
• Spanish
  - 西班牙语
• Arabic
  - 阿拉伯语
• Portuguese
  - 葡萄牙语
• Indonesian
  - 印度尼西亚语
• Japanese
  - 日语
• Russian
  - 俄语
• Hindi
  - 印地语
• French
  - 法语
• German
  - 德语
• Vietnamese
  - 越南语
• Turkish
  - 土耳其语
• Polish
  - 波兰语
• Italian
  - 意大利语
• Korean
  - 韩语

异步模式下的响应：

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "processing",
    "message": "Slides generation started. Use the jobId to check status.",
    "credits": {
      "current": 150,
      "required": 30
    }
  }
}

同步模式下的响应：

{
  "success": true,
  "data": {
    "jobId": "1pFqIww3JjquQ1T3Ysmw1",
    "status": "success",
    "message": "Slides generated successfully",
    "downloadUrl": "https://presigned-url-here",
    "createdAt": 1760347015388,
    "updatedAt": 1760347048261,
    "duration": 32694,
    "slidePageCount": 9
  }
}

2. 检查任务状态 (Fast PPT)

检查幻灯片生成任务 (Fast PPT) 的状态，并在完成后获取结果。

端点：

请求头：

Authorization: Bearer sk-2slides-your-api-key-here

响应示例：

处理中：

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "processing",
    "message": "Slides generation in progress",
    "createdAt": 1703123456789,
    "updatedAt": 1703123460000
  }
}

成功：

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "success",
    "message": "Slides generated successfully",
    "downloadUrl": "https://presigned-url-here",
    "createdAt": 1703123456789,
    "updatedAt": 1703123500000,
    "duration": 33211,
    "slidePageCount": 3
  }
}

失败：

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "failed",
    "message": "Slides generation failed",
    "errorMessage": "Insufficient credits for generation",
    "createdAt": 1703123456789,
    "updatedAt": 1703123460000
  }
}

3. 参照此样式创建幻灯片 (Nano Banana Pro)

从参考图片生成幻灯片 (Nano Banana Pro)。此端点使用同步模式，并在所有幻灯片完成后自动生成 PDF。

端点：

请求头：

Authorization: Bearer sk-2slides-your-api-key-here
Content-Type: application/json

请求体：

{
  "userInput": "Your presentation content here...",
  "referenceImageUrl": "https://example.com/reference-image.jpg",
  "responseLanguage": "Auto",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "page": 1
}

参数：

• userInput
  (必需)：您要生成幻灯片的内容
• referenceImageUrl
  (必需)：用于遵循设计风格的参考图片 URL。支持：
  • HTTP/HTTPS URL
  • Base64 数据 URL (data:image/...)
• responseLanguage
  (可选)：生成幻灯片的语言。使用“Auto”进行自动检测（默认：“Auto”）
• aspectRatio
  (可选)：幻灯片的宽高比。格式：“width:height”（默认：“16:9”）
• resolution
  (可选)：幻灯片图片的清晰度。选项：“1K”、“2K”、“4K”（默认：“2K”）
• page
  (可选)：要生成的幻灯片数量。使用 0 进行自动检测。指定一个数字（>=1，最大值：100）以强制生成该数量的幻灯片。默认值：1。
• contentDetail
  (可选)：幻灯片内容详细程度。选项：“concise”（简洁，侧重关键词）或“standard”（全面，详细）。默认：“concise”。

响应：

{
  "success": true,
  "data": {
    "jobId": "job-uuid-here",
    "status": "success",
    "message": "Successfully generated 5 slides",
    "downloadUrl": "https://presigned-url-to-pdf.pdf",
    "jobUrl": "https://2slides.com/workspace?jobId=job-uuid-here",
    "createdAt": 1703123456789,
    "updatedAt": 1703123500000,
    "slidePageCount": 5,
    "successCount": 5,
    "failedCount": 0
  }
}

状态值：

• success
  ：所有幻灯片成功生成，PDF 可用
• partial
  ：部分幻灯片生成失败
• failed
  ：所有幻灯片生成失败

注意：此端点以同步模式运行，并将在所有幻灯片生成完毕后才返回。

4. 搜索主题 (Fast PPT)

通过关键词搜索可用的幻灯片主题 (Fast PPT)。这包括公共主题和您自己上传的自定义主题。

端点：

请求头：

Authorization: Bearer sk-2slides-your-api-key-here

查询参数：

• query
  (必需)：用于在主题名称、描述和标签中搜索的关键词
• limit
  (可选)：最大结果数量（1-100，默认 20）

请求示例：

GET /api/v1/themes/search?query=timeline&limit=10

响应：

{
  "success": true,
  "data": {
    "total": 25,
    "themes": [
      {
        "id": "theme-uuid-1",
        "name": "Modern Timeline",
        "description": "Clean and modern timeline template for project presentations",
        "tags": "timeline, modern, project, clean",
        "themeURL": "https://2slides.com/templates/st-1759917935785-nx0z6ae54"
      },
      {
        "id": "theme-uuid-2",
        "name": "Business Roadmap",
        "description": "Professional roadmap template for business planning",
        "tags": "roadmap, business, planning, professional",
        "themeURL": "https://2slides.com/templates/st-1755509077270-sftfm616s"
      }
    ]
  }
}

速率限制

API 实施了速率限制，以确保公平使用和系统稳定性。不同的端点有不同的速率限制：

速率限制请求头

当超出速率限制时，API 将返回

响应，并包含以下请求头：

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 6
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1703123600
Retry-After: 45

处理速率限制

您需要仔细处理 API 调用速率限制，以下是 Javascript 中的一个示例。

async function makeApiRequest(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeApiRequest(url, options); // Retry
    }
    
    return response;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

积分系统

2slides 使用基于积分的系统进行幻灯片生成。每页幻灯片消耗 10 积分。

积分规则

• 新用户：注册后获得 880 免费积分
• 费用：每页幻灯片 10 积分 (Fast PPT)，每页 1K/2K Nano Banana Pro 幻灯片 100 积分，每页 4K Nano Banana Pro 幻灯片 200 积分
• 最低要求：用户至少需要 10 积分才能开始生成
• 扣除：积分仅在成功生成后扣除
• 退款：如果生成失败，积分将退还

查询积分

您可以通过 账户仪表板 或查看 API 响应中的积分信息来查询您的积分余额。

购买积分

可以通过 定价页面 使用各种支付方式购买额外积分。

示例

完整工作流程示例

以下是使用 2slides API 在 Javascript 和 Python 中生成幻灯片的完整示例：

const API_KEY = 'sk-2slides-your-api-key-here';
const BASE_URL = 'https://2slides.com';

async function generateSlides() {
  try {
    // Step 1: Search for a theme
    const themeResponse = await fetch(
      `${BASE_URL}/api/v1/themes/search?query=timeline&limit=5`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    const themeData = await themeResponse.json();
    const themeId = themeData.data.themes[0].id;
    
    // Step 2: Generate slides
    const generateResponse = await fetch(
      `${BASE_URL}/api/v1/slides/generate`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userInput: "Create a timeline for our product development: Q1 - Research and planning, Q2 - MVP development, Q3 - Beta testing, Q4 - Public launch",
          themeId: themeId,
          responseLanguage: "English",
          mode: "async"
        })
      }
    );
    
    const generateData = await generateResponse.json();
    const jobId = generateData.data.jobId;
    
    // Step 3: Poll for completion
    let jobStatus;
    do {
      await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
      
      const statusResponse = await fetch(
        `${BASE_URL}/api/v1/jobs/${jobId}`,
        {
          headers: {
            'Authorization': `Bearer ${API_KEY}`
          }
        }
      );
      
      jobStatus = await statusResponse.json();
      console.log(`Status: ${jobStatus.data.status}`);
      
    } while (jobStatus.data.status === 'processing' || jobStatus.data.status === 'pending');
    
    // Step 4: Handle result
    if (jobStatus.data.status === 'success') {
      console.log('Slides generated successfully!');
      console.log('Download URL:', jobStatus.data.downloadUrl);
      console.log('Pages generated:', jobStatus.data.slidePageCount);
      
      // Download the file
      const downloadResponse = await fetch(jobStatus.data.downloadUrl);
      const blob = await downloadResponse.blob();
      
      // Create download link
      const url = window.URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = 'presentation.pptx';
      a.click();
      window.URL.revokeObjectURL(url);
      
    } else {
      console.error('Generation failed:', jobStatus.data.errorMessage);
    }
    
  } catch (error) {
    console.error('Error:', error);
  }
}

// Run the example
generateSlides();

Python 示例

import requests
import time
import json

API_KEY = 'sk-2slides-your-api-key-here'
BASE_URL = 'https://2slides.com'

def generate_slides():
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    try:
        # Step 1: Search for a theme
        theme_response = requests.get(
            f'{BASE_URL}/api/v1/themes/search',
            params={'query': 'roadmap', 'limit': 5},
            headers=headers
        )
        theme_data = theme_response.json()
        theme_id = theme_data['data']['themes'][0]['id']
        
        # Step 2: Generate slides
        generate_payload = {
            'userInput': 'Create a product roadmap for our mobile app: Phase 1 - Core features, Phase 2 - Advanced features, Phase 3 - AI integration',
            'themeId': theme_id,
            'responseLanguage': 'English',
            'mode': 'async'
        }
        
        generate_response = requests.post(
            f'{BASE_URL}/api/v1/slides/generate',
            headers=headers,
            json=generate_payload
        )
        generate_data = generate_response.json()
        job_id = generate_data['data']['jobId']
        
        # Step 3: Poll for completion
        while True:
            time.sleep(2)  # Wait 2 seconds
            
            status_response = requests.get(
                f'{BASE_URL}/api/v1/jobs/{job_id}',
                headers=headers
            )
            status_data = status_response.json()
            status = status_data['data']['status']
            
            print(f'Status: {status}')
            
            if status in ['success', 'failed']:
                break
        
        # Step 4: Handle result
        if status == 'success':
            print('Slides generated successfully!')
            print(f'Download URL: {status_data["data"]["downloadUrl"]}')
            print(f'Pages generated: {status_data["data"]["slidePageCount"]}')
            
            # Download the file
            download_response = requests.get(status_data['data']['downloadUrl'])
            with open('presentation.pptx', 'wb') as f:
                f.write(download_response.content)
            print('File downloaded as presentation.pptx')
            
        else:
            print(f'Generation failed: {status_data["data"]["errorMessage"]}')
            
    except Exception as error:
        print(f'Error: {error}')

# Run the example
generate_slides()

cURL 示例

搜索主题：

curl -X GET "https://2slides.com/api/v1/themes/search?query=timeline&limit=5" \
  -H "Authorization: Bearer sk-2slides-your-api-key-here" \
  -H "Content-Type: application/json"

生成幻灯片：

curl -X POST "https://2slides.com/api/v1/slides/generate" \
  -H "Authorization: Bearer sk-2slides-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "Create a timeline for our project milestones",
    "themeId": "theme-uuid-here",
    "responseLanguage": "English",
    "mode": "async"
  }'

检查任务状态：

curl -X GET "https://2slides.com/api/v1/jobs/job-uuid-here" \
  -H "Authorization: Bearer sk-2slides-your-api-key-here"

错误处理

API 使用标准的 HTTP 状态码，并以 JSON 格式返回详细的错误信息。

常见错误响应

400 错误请求：

{
  "success": false,
  "error": "userInput is required and must be a non-empty string"
}

401 未授权：

{
  "success": false,
  "error": "Authentication required"
}

403 禁止访问：

{
  "success": false,
  "error": "Access denied"
}

404 未找到：

{
  "success": false,
  "error": "Theme not found"
}

429 请求过多：

{
  "success": false,
  "error": "Rate limit exceeded"
}

500 内部服务器错误：

{
  "success": false,
  "error": "Internal server error"
}

错误处理最佳实践

async function handleApiRequest(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (!response.ok) {
      switch (response.status) {
        case 400:
          throw new Error(`Bad Request: ${data.error}`);
        case 401:
          throw new Error('Authentication failed. Please check your API key.');
        case 403:
          throw new Error('Access denied. You may not have permission for this resource.');
        case 404:
          throw new Error('Resource not found.');
        case 429:
          throw new Error('Rate limit exceeded. Please try again later.');
        case 500:
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(`API Error: ${data.error || 'Unknown error'}`);
      }
    }
    
    return data;
  } catch (error) {
    if (error.name === 'TypeError' && error.message.includes('fetch')) {
      throw new Error('Network error. Please check your internet connection.');
    }
    throw error;
  }
}

最佳实践

1. API 密钥安全

• 切勿暴露 API 密钥：在客户端代码或公共仓库中
• 使用环境变量：安全存储 API 密钥
• 定期轮换密钥：以增强安全性
• 监控密钥使用情况：通过 API 管理仪表板
• 安全存储密钥：请记住 2slides 不会存储您的 API 密钥，因此您必须妥善保管它们
• 备份您的密钥：将 API 密钥存储在安全的密码管理器或加密存储中

2. 高效使用 API

• 缓存主题搜索结果：以避免重复请求
• 实施适当的轮询间隔：用于任务状态检查（2-5 秒）
• 优雅地处理速率限制：采用指数退避策略
• 批量操作：在可能的情况下减少 API 调用

3. 错误处理

• 始终检查响应状态码
• 实现重试逻辑：针对瞬时故障
• 适当地记录错误：以便调试
• 提供用户友好的错误消息

4. 性能优化

• 使用适当的轮询间隔：以避免不必要的请求
• 实施请求超时：以防止请求挂起
• 缓存常用数据：例如主题信息
• 监控您的积分使用情况：以避免意外费用

5. 内容指南

• 提供清晰、结构化的输入：以获得更好的幻灯片生成效果
• 为您的内容类型使用适当的主题
• 在需要时指定语言：用于国际化内容
• 保持内容简洁：以实现最佳幻灯片布局

支持与资源

文档与资源

• API 文档 - 交互式 API 文档和演练场
• 模板库 - 浏览可用幻灯片模板
• 定价信息 - 积分套餐和定价
• 博客 - 最新更新和技巧

获取帮助

• API 演练场：在 2slides.com/api 直接在浏览器中测试您的 API 调用
• 账户仪表板：在 2slides.com/account 管理您的积分使用情况
• 支持：通过 主网站 联系支持

社区与更新

• 功能更新：及时了解新功能和改进
• 模板库：定期添加新的专业模板
• API 增强：持续改进 API 性能和功能

---

总结

2slides API 提供了一种强大而灵活的方式，以编程方式生成专业的演示文稿。凭借其全面的功能集、强大的错误处理能力和丰富的模板库，您可以将 AI 驱动的幻灯片生成功能集成到任何应用程序或工作流程中。

立即使用 2slides API 开始构建精美的演示文稿吧！访问 2slides.com/api 获取您的 API 密钥并开始创作。