打造 AI 簡報代理人：完整的開發者指南

AI 代理人正在徹底改變軟體內容的生成方式。AI 簡報代理人能夠生成、客製化並交付專業的簡報投影片，作為自動化工作流程的一部分——從客戶關係管理 (CRM) 管道到內部報告工具，無所不包。

本指南將引導您使用 2Slides API 打造一個可投入生產的簡報代理人。

架構概覽

簡報代理人通常遵循以下流程：

使用者請求 → 代理人邏輯 → 2Slides API → 輪詢任務 → 交付結果
                  ↓
           上下文收集
           (資料、範本、品牌資產)

核心元件

輸入處理器 — 接收簡報請求（文字、資料、檔案）
上下文建構器 — 使用範本、品牌資訊和資料豐富請求
生成引擎 — 呼叫 2Slides API 以建立投影片
狀態監控器 — 輪詢任務狀態直到完成
交付層 — 返回下載連結、透過電子郵件發送、發佈到 Slack

開始使用

1. 取得您的 API 金鑰

請在 2slides.com 註冊，並在 2slides.com/api 建立 API 金鑰。

2. 安裝依賴項

npm install node-fetch dotenv

3. 基本代理人實作

import fetch from 'node-fetch';

class PresentationAgent {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://2slides.com/api/v1';
  }

  async generateSlides({ topic, themeId, language = 'en', resolution = '2K' }) {
    // 步驟 1：開始生成
    const response = await fetch(`${this.baseUrl}/slides/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userInput: topic,
        themeId,
        responseLanguage: language,
        resolution,
        mode: 'async'
      })
    });

    const job = await response.json();
    if (!response.ok) throw new Error(job.error || 'Generation failed');

    // 步驟 2：輪詢直到完成
    return await this.waitForCompletion(job.jobId);
  }

  async waitForCompletion(jobId, maxWait = 300000) {
    const start = Date.now();
    while (Date.now() - start < maxWait) {
      const response = await fetch(`${this.baseUrl}/jobs/${jobId}`, {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      });
      const status = await response.json();

      if (status.status === 'success') return status;
      if (status.status === 'failed') throw new Error('Generation failed');

      await new Promise(r => setTimeout(r, 3000));
    }
    throw new Error('Generation timed out');
  }

  async generateFromFile({ fileUrl, prompt, themeId }) {
    const response = await fetch(`${this.baseUrl}/slides/create-pdf-slides`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fileUrl,
        userInput: prompt,
        themeId,
        mode: 'async'
      })
    });

    const job = await response.json();
    return await this.waitForCompletion(job.jobId);
  }

  async generateWithDesign({ topic, referenceImageUrl, resolution = '2K' }) {
    const response = await fetch(`${this.baseUrl}/slides/create-like-this`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userInput: topic,
        designStyle: {
          global: { referenceImageUrl }
        },
        resolution,
        mode: 'async'
      })
    });

    const job = await response.json();
    return await this.waitForCompletion(job.jobId);
  }

  async addNarration({ jobId, mode = 'single', voice = 'Charon' }) {
    const response = await fetch(`${this.baseUrl}/slides/generate-narration`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ jobId, mode, voice, contentMode: 'concise' })
    });

    return await response.json();
  }
}

// 用法
const agent = new PresentationAgent('sk-2slides-xxx');

const result = await agent.generateSlides({
  topic: 'Q1 2026 Business Review',
  themeId: 'mckinsey-theme-id',
  resolution: '2K'
});

console.log('下載:', result.downloadUrl);

Python 實作

import requests
import time

class PresentationAgent:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://2slides.com/api/v1'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def generate_slides(self, topic, theme_id=None, language='en', resolution='2K'):
        response = requests.post(
            f'{self.base_url}/slides/generate',
            headers=self.headers,
            json={
                'userInput': topic,
                'themeId': theme_id,
                'responseLanguage': language,
                'resolution': resolution,
                'mode': 'async'
            }
        )
        response.raise_for_status()
        job = response.json()
        return self._wait_for_completion(job['jobId'])

    def generate_from_file(self, file_url, prompt, theme_id=None):
        response = requests.post(
            f'{self.base_url}/slides/create-pdf-slides',
            headers=self.headers,
            json={
                'fileUrl': file_url,
                'userInput': prompt,
                'themeId': theme_id,
                'mode': 'async'
            }
        )
        response.raise_for_status()
        job = response.json()
        return self._wait_for_completion(job['jobId'])

    def _wait_for_completion(self, job_id, max_wait=300):
        start = time.time()
        while time.time() - start < max_wait:
            response = requests.get(
                f'{self.base_url}/jobs/{job_id}',
                headers=self.headers
            )
            status = response.json()
            if status['status'] == 'success':
                return status
            if status['status'] == 'failed':
                raise Exception('Generation failed')
            time.sleep(3)
        raise TimeoutError('Generation timed out')

# 用法
agent = PresentationAgent('sk-2slides-xxx')
result = agent.generate_slides('AI Trends 2026', resolution='4K')
print(f"下載: {result['downloadUrl']}")

進階模式

模式 1：基於範本的生成

為不同的使用案例預先配置主題：

const TEMPLATES = {
  'pitch-deck': { themeId: 'apple-id', resolution: '2K' },
  'quarterly-review': { themeId: 'mckinsey-id', resolution: '2K' },
  'training': { themeId: 'corporate-id', resolution: '1K' },
  'social-media': { themeId: 'saul-bass-id', resolution: '4K', aspectRatio: '1:1' },
};

async function generateByType(type, topic) {
  const config = TEMPLATES[type];
  return agent.generateSlides({ topic, ...config });
}

2：資料管道整合

連接到您的資料來源：

async function weeklyReport(dataSource) {
  // 1. 獲取最新資料
  const data = await dataSource.getWeeklyMetrics();

  // 2. 格式化為簡報輸入
  const topic = `Weekly Report: Revenue $${data.revenue}, Users ${data.users}, Churn ${data.churn}%`;

  // 3. 生成投影片
  const result = await agent.generateSlides({ topic, themeId: 'mckinsey-id' });

  // 4. 交付
  await slackBot.postMessage('#team-updates', `Weekly report ready: ${result.downloadUrl}`);
}

模式 3：多格式輸出

在一個管道中生成投影片 + 旁白 + 影片：

async function fullPresentation(topic) {
  // 1. 生成投影片
  const slides = await agent.generateSlides({ topic });

  // 2. 添加語音旁白
  await agent.addNarration({ jobId: slides.jobId, mode: 'multi', voice: 'Charon' });

  // 3. 下載含音訊的檔案
  const download = await fetch(`${agent.baseUrl}/slides/download-slides-pages-voices`, {
    method: 'POST',
    headers: agent.headers,
    body: JSON.stringify({ jobId: slides.jobId })
  });

  return download.json();
}

生產環境考量

速率限制

預設：每分鐘 60 個請求
使用指數退避（exponential backoff）處理 429 響應
對於批次操作使用非同步（async）模式

錯誤處理

將所有 API 呼叫包裝在 try/catch 中
為暫時性故障實作重試邏輯
記錄任務 ID 以便除錯

成本管理

追蹤每次生成的點數使用情況
在您的 2Slides 控制面板中設定預算警報
對於內部/草稿內容使用較低解析度

安全性

將 API 金鑰儲存在環境變數中，絕不寫入程式碼
僅使用伺服器端 API 呼叫 — 絕不將金鑰暴露給客戶端
為 webhook 回呼實作請求簽名

常見問題

我可以在 2Slides API 之上建立 SaaS 產品嗎？

可以 — 該 API 專為生產環境使用而設計。對商業應用沒有任何限制。

最大並行生成限制是多少？

API 透過速率限制處理並行請求。對於高用量需求，請聯繫 2Slides 團隊以獲取企業級限制。

是否有任務完成的 webhook？

目前，請透過 jobs 端點進行輪詢。Webhook 支援已列入開發藍圖。

打造您的簡報代理人 — 在 2Slides 取得您的 API 金鑰並開始以程式化方式生成投影片。