用 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-CN       # 学习者母语
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。

人工那一侧的工作流见单词卡教程和创作者工作流。