2slides API 教學 - AI 簡報生成完整指南

歡迎來到 2slides API 的綜合指南！本教學將引導您了解整合 AI 驅動簡報生成到您的應用程式所需的一切。

概覽

2slides API 讓您能夠以程式化的方式，利用 AI 生成專業簡報。透過支援多種簡報類型，包括時間軸、路線圖、心智圖等，您可以從簡單的文字輸入建立令人驚豔的投影片。

主要功能

• AI 驅動生成：自動從文字建立專業簡報
• 多種範本類型：支援時間軸、路線圖、心智圖、募資簡報、資訊圖表等
• 多語言支援：生成多語言內容
• 豐富的範本庫：存取數百個專業設計的範本
• 自訂範本：上傳並使用您自己的自訂投影片範本
• 搜尋範本：透過名稱、關鍵字和標籤搜尋範本
• 下載選項：以 PowerPoint (.pptx) 格式取得簡報
• 即時狀態追蹤：透過任務狀態端點監控生成進度

精選簡報類型

所有簡報範本都可以在這裡找到：2slides 範本。特別是，有一些精選的簡報類型非常適合特定目的和情境。

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 Header

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

API 金鑰管理

• 最多金鑰數量：每個用戶最多可以建立 10 個 API 金鑰
• 金鑰命名：為您的金鑰提供描述性名稱以便於識別
• 安全性：確保您的 API 金鑰安全，切勿公開分享
• 輪換：定期輪換您的 API 金鑰以增強安全性

⚠️ 重要安全提示：2slides 平台基於安全原因，不以明文形式儲存您的 API 金鑰。一旦生成，您必須立即複製並安全儲存您的 API 金鑰。如果您遺失了 API 金鑰，您將需要生成一個新的，因為原始金鑰無法恢復。

API 端點

1. 生成投影片 (Fast PPT)

從文字輸入使用特定主題生成投影片 (Fast PPT)。

端點：

Headers：

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) 的狀態，並在完成時取得結果。

端點：

Headers：

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。

端點：

Headers：

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)。這包括公開主題和您自己上傳的自訂主題。

端點：

Headers：

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 實施了速率限制，以確保公平使用和系統穩定性。不同的端點有不同的速率限制：

速率限制 Headers

當超出速率限制時，API 會返回

回應，並帶有以下 Headers：

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 點免費點數
• 費用：Fast PPT 每頁投影片 10 點，1K/2K Nano Banana Pro 每頁投影片 100 點，4K Nano Banana Pro 每頁投影片 200 點
• 最低要求：用戶至少需要 10 點才能開始生成
• 扣除：點數僅在成功生成後扣除
• 退款：如果生成失敗，點數將退還

檢查點數

您可以透過 帳戶儀表板 或檢查 API 回應中的點數資訊來查看您的點數餘額。

購買點數

可以透過 定價頁面 使用各種支付方式購買額外點數。

範例

完整工作流程範例

以下是使用 Javascript 和 Python 的 2slides API 生成投影片的完整範例：

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

async function generateSlides() {
  try {
    // 步驟 1：搜尋主題
    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;
    
    // 步驟 2：生成投影片
    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;
    
    // 步驟 3：輪詢以等待完成
    let jobStatus;
    do {
      await new Promise(resolve => setTimeout(resolve, 2000)); // 等待 2 秒
      
      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');
    
    // 步驟 4：處理結果
    if (jobStatus.data.status === 'success') {
      console.log('Slides generated successfully!');
      console.log('Download URL:', jobStatus.data.downloadUrl);
      console.log('Pages generated:', jobStatus.data.slidePageCount);
      
      // 下載檔案
      const downloadResponse = await fetch(jobStatus.data.downloadUrl);
      const blob = await downloadResponse.blob();
      
      // 建立下載連結
      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);
  }
}

// 執行範例
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:
        # 步驟 1：搜尋主題
        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']
        
        # 步驟 2：生成投影片
        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']
        
        # 步驟 3：輪詢以等待完成
        while True:
            time.sleep(2)  # 等待 2 秒
            
            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
        
        # 步驟 4：處理結果
        if status == 'success':
            print('Slides generated successfully!')
            print(f'Download URL: {status_data["data"]["downloadUrl"]}')
            print(f'Pages generated: {status_data["data"]["slidePageCount"]}')
            
            # 下載檔案
            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}')

# 執行範例
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 Bad Request：

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

401 Unauthorized：

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

403 Forbidden：

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

404 Not Found：

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

429 Too Many Requests：

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

500 Internal Server Error：

{
  "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 試驗場：直接在瀏覽器中測試您的 API 呼叫：2slides.com/api
• 帳戶儀表板：在 2slides.com/account 管理您的點數使用情況
• 支援：透過 主網站 聯繫支援

社群與更新

• 功能更新：隨時了解新功能和改進
• 範本庫：定期新增專業範本
• API 增強功能：持續改進 API 效能和功能

---

結論

2slides API 提供了一種強大而靈活的方式，以程式化的方式生成專業簡報。憑藉其全面的功能集、穩健的錯誤處理和廣泛的範本庫，您可以將 AI 驅動的投影片生成整合到任何應用程式或工作流程中。

立即使用 2slides API 開始建立令人驚豔的簡報！請造訪 2slides.com/api 取得您的 API 金鑰並開始創作。