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

Q: 為什麼 /api/v1/slides/generate 的任務不能加旁白？

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

Q: API 支援多少種生成語言？

22+ 種。透過 responseLanguage 傳。

Q: 怎麼處理 429？

指數退避——1 秒起步、2 倍遞增到 60 秒。連續 3 次 429 把並行 worker 數砍半。不要把 /api/v1/jobs/{id} 輪詢得比 20 秒快——這是 429 最常見原因。

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

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

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

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

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

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

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

端點	產出	能加旁白？	點數
`POST /api/v1/slides/generate`	Fast PPT ——模板驅動 PPTX，需要從模板庫拿 `themeId`	❌ 不能。旁白端點會明確拒絕這種 job	10 / 頁
`POST /api/v1/slides/create-pdf-slides`	Nano Banana ——基於提示詞的影像生成投影片，和 Workspace 同一引擎	✅ 可以	10（規劃）+ 100 / 頁（1K/2K）或 200 / 頁（4K）
`POST /api/v1/slides/create-like-this`	Nano Banana ——參考一張影像生成	✅ 可以	同上

做帶旁白和可匯出音訊的單字卡內容工廠——用 create-pdf-slides（如果要照著某個版式做就用 create-like-this）。不要用 /api/v1/slides/generate——那是 Fast PPT，加不了旁白。

如果工廠只要無聲 PPTX（沒音訊、沒影片），用 /api/v1/slides/generate 最便宜。本手冊餘下部分假設是帶旁白工作流。

一圖看架構

[源資料]                  [調度器]                       [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。create-pdf-slides/create-like-this：圍繞並行上限和 429 指數退避來設計佇列。jobs/{id} 輪詢：尊重下面的輪詢節奏——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"
  }'

回傳 jobId（UUID）。輪詢：

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

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

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

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 個字。

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

Step 5 — 加旁白

生成任務 status: "success" 之後啟動旁白。旁白只支援非同步，作用在同一個 jobId：

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
  }'

繼續輪詢同一個 /api/v1/jobs/{jobId}，直到 message 從 "Voice narration generation in progress" 變到成功狀態。

兩種聲音模式都有用：

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

聲音目錄在 /tts_sample_voices/，常用的有 Puck、Aoede、Charon、Kore。生產環境固定聲音之前最好對照最新 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"
  }'

回應裡的 downloadUrl（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 伺服器端拼：

# 每頁：影像 + 配音音訊 拼成一段
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 生成階段就用不同的 aspectRatio（"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 完全夠。

防止現場起火的維運模式

冪等

每次提交對 deck_id 冪等。worker 中途崩了重啟絕對不能產生重複卡組。最乾淨：在資料庫存 (deck_id, status) 列，遷移狀態（pending → generating → narrating → exporting → composed → distributed）。

品質門

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

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

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

版本化

每個產物存：提示詞模板版本、影像模型版本（gemini-3-pro-image-preview vs gemini-3.1-flash-image-preview）、配音聲音、生成時間戳。

成本遙測

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

失敗處理

退避 1 次重試。兩次失敗後推到 needs_human 佇列。別死迴圈。

該不該用 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` 的任務不能加旁白？

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

能直接從 API 匯出 MP4 嗎？

不能（截至 2026）。MP4 匯出是 Workspace UI 的功能，瀏覽器端用 FFmpeg.wasm 實作。API 等價物是 download-slides-pages-voices 回傳的 ZIP（投影片影像 + 音訊 + 字幕）——內容工廠裡需要 MP4 的話自己用 ffmpeg 拼。見 Step 7。

API 支援多少種生成語言？

22+ 種。透過 responseLanguage 傳。

點數怎麼算？

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

怎麼處理 429？

指數退避——1 秒起步、2 倍遞增到 60 秒。連續 3 次 429 把並行 worker 數砍半。不要把 /api/v1/jobs/{id} 輪詢得比 20 秒快——這是 429 最常見原因。

能整合 Zapier / Make / n8n 嗎？

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

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

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

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

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

要點

內容工廠 = 結構化源資料 + 穩定調度器 + 選對的 API 端點。最常見的工廠故障是用 /api/v1/slides/generate（Fast PPT）然後試圖加旁白——這條路走不通。用 create-pdf-slides 或 create-like-this，再用 generate-narration 加旁白，再用 download-slides-pages-voices 匯出，自己用 ffmpeg 伺服器端拼 MP4。

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