用 2Slides API 批次生成 100 份單字卡組：2026 內容工廠實戰手冊

手工跑通工作流——生成一份單字卡、配音、匯出資源——之後下一個瓶頸就是體量。一個有 12 個等級、每週 30 個主題的語言學校一年要 360 份卡組。每天發的 faceless TikTok 頻道一年要 365 份卡組加多比例變體。EdTech 公司的內容團隊要按 L1/L2 語對切分上百份。

360 份卡組不是手工做出來的。是建一個內容工廠。

這篇是 2026 年用 2Slides API 程式化批次生成單字卡組（以及任何投影片內容）的實戰手冊。最重要的架構決策——也是最常被搞錯的——是選對生成端點。

先選對端點（這是工廠最容易翻車的地方）

2Slides API 暴露了兩條獨立的生成流。只有其中一條生成的卡組之後能加旁白。

做帶旁白和可匯出音訊的單字卡內容工廠——用

（如果要照著某個版式做就用 ）。不要用 ——那是 Fast PPT，加不了旁白。

如果工廠只要無聲 PPTX（沒音訊、沒影片），用

最便宜。本手冊餘下部分假設是帶旁白工作流。

一圖看架構

[源資料]                  [調度器]                       [2Slides API]                       [產物]
   │                          │                              │                                 │
詞彙表  ──提示詞──▶  作業佇列  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
                       (Cron / 腳本)                       │                                   │
   │                          │                              │                                 │
                          輪詢  ──GET──▶  /api/v1/jobs/{jobId} ◀──────────────────────────────┘
                          每 20-30 秒    status: success                                       │
                                                              │                                 ▼
                                                              │             [pages PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode 等) ——只有非同步
                                                              │
                                                          輪詢  ──GET──▶  /api/v1/jobs/{jobId}
                                                          message: "Voice narration ... in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  （免費；回傳 ZIP）
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   （可選）用戶端用 ffmpeg 拼 MP4
                                                   或者直接走 Workspace UI
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

源資料 → 調度器 → API → pages + voices ZIP → 分發。MP4 拼合是可選的，不是公網 API 端點——目前是 Workspace UI 在瀏覽器裡用 FFmpeg.wasm 拼的。API 這邊給到的是 pages+voices ZIP，需要 MP4 的話工廠裡用 ffmpeg 伺服器端拼。

Step 1 — 先把源 schema 定下來

槓桿最高的一步是API 呼叫之前先把源資料 schema 定清楚。

deck_id: vocab-b1-travel-2026-w14
source_l1: zh-TW       # 學習者母語
target_l2: en          # 學習語言
cefr_level: B1
theme: travel
words:
  - { word: "boarding pass", ipa: "/ˈbɔːrdɪŋ pæs/", pos: noun, l1: "登機證" }
  - { word: "layover",       ipa: "/ˈleɪoʊvər/",     pos: noun, l1: "中轉停留" }
  - { word: "to delay",      ipa: "/dɪˈleɪ/",         pos: verb, l1: "延誤" }
  # ... 27 more
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # 短影片複習用直式
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # 見 /tts_sample_voices 全聲音目錄
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Step 2 — 鑑權

去 API 管理頁 拿 key。Bearer auth：

Authorization: Bearer sk-2slides-...

每個端點的限速見 2slides.com/api.md。

/：圍繞並行上限和 429 指數退避來設計佇列。 輪詢：尊重下面的輪詢節奏——20–30 秒，不要更激進。

Step 3 — 提交 Nano Banana 生成任務

單字卡走非同步模式（30 張卡的逐頁影像生成通常 1–3 分鐘）。

curl -X POST "https://2slides.com/api/v1/slides/create-pdf-slides" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "<卡組形態提示詞>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

回傳

（UUID）。輪詢：

curl -X GET "https://2slides.com/api/v1/jobs/{jobId}" \
  -H "Authorization: Bearer sk-2slides-..."

輪詢節奏：每 20–30 秒。不要更快——API 文件明確寫了，激進輪詢是 429 最常見原因。多數卡組 1–3 分鐘完成。

時，投影片影像已經存到 R2，PDF 合訂有 。這些投影片影像就是後面要和音訊拼的素材。

Step 4 — 寫能在規模下穩住的提示詞模板

為 {{source_l1}} 母語的 {{cefr_level}} 級 {{target_l2}} 學習者生成單字卡組。
主題：{{theme}}。

卡片數：{{word_count}}。

每張卡輸出：
- 目標字（{{target_l2}}）
- 詞性
- IPA
- {{source_l1}} 翻譯
- 兩句自然 {{theme}} 場景例句，B1 句法，每句 8–14 字

要包含的字：
{{word_list_yaml}}

最後用 3 張卡總結全卡組裡最有用的 3 個字。

視覺風格用

參數（自訂提示詞）控制，或者留預設（"乾淨的資訊圖、不要照片、平衡的排版"）。提示詞放進 git 做版本控制——以便回歸歸因。

Step 5 — 加旁白

生成任務

之後啟動旁白。旁白只支援非同步，作用在同一個 ：

curl -X POST "https://2slides.com/api/v1/slides/generate-narration" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "mode": "single",
    "voice": "Puck",
    "speakerName": "Vocabulary Coach",
    "contentMode": "concise",
    "includeIntro": true
  }'

繼續輪詢同一個

，直到 message 從 "Voice narration generation in progress" 變到成功狀態。

兩種聲音模式都有用：

• mode: "single"
  單一聲音——直接讀單字、IPA、例句
• mode: "multi"
  雙人對話——例句在兩個聲音之間分配，對動詞和慣用語特別合適

聲音目錄在

，常用的有 、、、。生產環境固定聲音之前最好對照最新 API 文件 確認。

重要：這個端點一次性生成配音文字和音訊。不要呼叫"配音文字"和"配音音訊"兩個分開的端點——這兩步沒有獨立的公網 API。一次設定 narration 請求，API 把兩步都做完。

Step 6 — 匯出 pages + voices（免費）

旁白完成後，一次拿到所有素材的 ZIP：

curl -X POST "https://2slides.com/api/v1/slides/download-slides-pages-voices" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "550e8400-e29b-41d4-a716-446655440000"
  }'

回應裡的

（1 小時有效）指向一個 ZIP，包含：

pages/
  page_01.png
  page_02.png
  ...
voices/
  page_01.wav
  page_02.wav
  ...
transcript.txt

這步匯出免費——不消耗點數。下載 ZIP 把素材放進自己的物件儲存。預簽名 URL 1 小時過期。

Step 7 — （可選）伺服器端拼 MP4

2Slides API 目前沒有公開 MP4 拼合端點——MP4 拼合在 Workspace UI 瀏覽器端用 FFmpeg.wasm 完成。內容工廠裡用

伺服器端拼：

# 每頁：影像 + 配音音訊 拼成一段
ffmpeg -loop 1 -i pages/page_01.png -i voices/page_01.wav \
       -c:v libx264 -tune stillimage -c:a aac -b:a 192k \
       -pix_fmt yuv420p -shortest clips/page_01.mp4

# 把所有頁的 clip 拼成最終 MP4
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

每頁音訊時長就是旁白生成器產生的——單字卡通常每頁 5–12 秒。結果和 Workspace UI 使用者能下載到的 MP4 一樣，只是在工廠裡無人值守做出來。

要同一份卡組同時出直式（9:16）和橫式（16:9）：最乾淨的方法是生成兩次，slide 生成階段就用不同的

（"9:16" 一次、"16:9" 一次）。事後用 ffmpeg 裁切通常很難看——版式是按特定比例排的。

Step 8 — 寫調度器

最小調度器五個迴圈：

# 虛擬程式碼

while there_is_work():
    deck = pull_one_pending_deck_from_source()
    if not deck:
        sleep(60); continue

    # 1. 透過 Nano Banana 端點生成
    job = post("/api/v1/slides/create-pdf-slides", body=build_payload(deck))
    deck_artifact = poll_until_complete(job.data.jobId)

    # 2. 加旁白（只有非同步）
    if deck.narration.enabled:
        post("/api/v1/slides/generate-narration", body={
            "jobId": deck_artifact.id,
            "voice": deck.narration.voice,
            "mode": deck.narration.mode,
        })
        poll_until_narration_complete(deck_artifact.id)

    # 3. 匯出 pages + voices ZIP（免費）
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. 下載到自己的物件儲存
    download_to_s3(zip_url, deck.id)

    # 5. （可選）用 ffmpeg 拼 MP4，然後分發
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

每天 100 份：1 個 worker 夠。1,000+：分成小型 worker pool，但 pool 總並行不超過端點限速，不是 worker 數。

Step 9 — 分發模式

• LMS：用 Canvas / Moodle / Blackboard / Google Classroom 各自 API 上傳 MP4
• TikTok / Reels / Shorts：把 9:16 MP4 推到發布工具（Buffer、Later、平台原生）
• Newsletter：把 PDF 合訂（來自原始生成任務的
  downloadUrl
  ）作為下載連結嵌進每週電子報
• 業務 / lead magnet：PDF 上 Stan Store / Gumroad，carousel 預告引流

成本核算（最重要的事先規劃）

帶旁白的 Nano Banana 卡組點數加得比 Fast PPT 價格快得多。30 張卡（1K/2K，帶旁白）：

• 規劃：10 點數
• 投影片生成：30 × 100 = 3,000 點數
• 旁白（文字 + 音訊）：30 × 210 = 6,300 點數
• pages + voices 匯出：免費
• 總計：約 9,310 點數 / 30 卡帶旁白卡組

不帶旁白的話同樣卡組約 3,010 點數。4K 解析度：30 × 200 = 6,000 → 約 12,310 點數（帶旁白）。

100 卡組 / 月的工廠：100 × 9,310 = 約 931,000 點數 / 月。對照 價格頁 選檔——4K 只在大螢幕 / 高級影片場景才有必要。TikTok / Reels 複習影片，1K 或 2K 完全夠。

防止現場起火的維運模式

冪等

每次提交對

冪等。worker 中途崩了重啟絕對不能產生重複卡組。最乾淨：在資料庫存 列，遷移狀態（）。

品質門

不要自動分發。推送到 TikTok 或 Canvas 之前跑機器可讀品質檢查：

• 頁數和請求一致
• ZIP 裡
  pages/page_NN.png
  和
  voices/page_NN.wav
  數量正確
• 每頁音訊時長 3–15 秒（30 秒一定是出問題）
• transcript.txt
  非空且包含目標字

前 50 個批次額外人工抽 1/10。系統性提示詞問題在前 50 個批次冒出來。

版本化

每個產物存：提示詞模板版本、影像模型版本（

vs ）、配音聲音、生成時間戳。

成本遙測

每份卡組有已知點數成本（見上）。追蹤每份的點數。突然翻倍說明有什麼變了（頁數變多、重試變多、切到 4K）。

失敗處理

退避 1 次重試。兩次失敗後推到

佇列。別死迴圈。

該不該用 API

API 是對的當：

• 週產 >10 卡組
• 有結構化源資料
• 要伺服器端拼合的旁白 MP4 用於分發
• 整合 LMS、scheduler、CMS
• 要在提示詞版本下做可重現性

API 過度的場景：

• 週產 1 份每次視覺調（UI 更快——Workspace UI 還把 MP4 拼合都幫你做了）
• 學習者給自己做
• 老師每堂課程一份（用 Create Slides from File 或 Create Slides Like This）

常見問題

API key 在哪拿？

2slides.com/api，API 管理 tab。

為什麼

/api/v1/slides/generate

的任務不能加旁白？

是 Fast PPT——模板驅動 PPTX。它產出的是最終 .pptx 檔案，不是旁白生成器能讀的"投影片影像 + 文字"型 job。旁白生成器明確只接受 或 產生的 nano banana job。

能直接從 API 匯出 MP4 嗎？

不能（截至 2026）。MP4 匯出是 Workspace UI 的功能，瀏覽器端用 FFmpeg.wasm 實作。API 等價物是

回傳的 ZIP（投影片影像 + 音訊 + 字幕）——內容工廠裡需要 MP4 的話自己用 拼。見 Step 7。

API 支援多少種生成語言？

22+ 種。透過

傳。

點數怎麼算？

Nano Banana：10（規劃）+ 100/頁（1K/2K）或 200/頁（4K）+ 旁白 210/頁（10 文字 + 200 音訊）。pages+voices 匯出免費。30 卡帶旁白 2K ≈ 9,310 點數。詳見 價格頁 和上面的成本核算。

怎麼處理 429？

指數退避——1 秒起步、2 倍遞增到 60 秒。連續 3 次 429 把並行 worker 數砍半。不要把

輪詢得比 20 秒快——這是 429 最常見原因。

能整合 Zapier / Make / n8n 嗎？

可以——任何能發帶鑑權 HTTP 的工具都能驅動。n8n 在內容工廠特別流行——原生支援輪詢和佇列。

怎麼防止生成的卡組被公開索引？

API 生成的卡組預設私有於帳號，公開分享是另一個明確動作。

同一份卡組怎麼同時出 9:16 和 16:9？

生成兩次——一次

、一次 。版式是按比例排版的，事後裁切很難看。這意味著點數雙倍消耗——是為了視覺乾淨的故意 trade-off。

要點

內容工廠 = 結構化源資料 + 穩定調度器 + 選對的 API 端點。最常見的工廠故障是用

（Fast PPT）然後試圖加旁白——這條路走不通。用 或 ，再用 加旁白，再用 匯出，自己用 伺服器端拼 MP4。

人工那一側的工作流見 單字卡教學 和 創作者工作流。