2Slides API で 100 個の単語カードデッキを一括生成：2026 コンテンツファクトリー実践ガイド

Q: なぜ /api/v1/slides/generate のジョブにナレーションを追加できない？

generate は Fast PPT──テンプレート駆動 PPTX。出力は完成した .pptx ファイル、ナレーションジェネレータが読める「スライド画像 + テキスト」型ジョブではありません。ナレーションジェネレータは明示的に create-pdf-slides または create-like-this のジョブのみ受け付けます。

Q: 生成 API は何言語サポート？

22+ 言語。responseLanguage で指定。

Q: 429 の処理？

指数バックオフ。1 秒開始、60 秒上限まで倍化。連続 3 回 429 で同時ワーカー数を半減。/api/v1/jobs/{id} を 20 秒より速くポーリングしない。

Q: 同じデッキの 9:16 と 16:9 両方を生成するには？

2 回生成──aspectRatio: "9:16" と "16:9"。レイアウトは比率ごとに最適化されており、事後クロップは見栄えが悪い。クレジット倍消費はビジュアルクオリティのための意図的トレードオフ。

手動ワークフローを検証した次のボトルネックはボリュームです。12 レベル × 週 30 テーマの語学学校は年 360 デッキ。毎日投稿の faceless TikTok は年 365 デッキ + アスペクト比バリアント。EdTech のコンテンツチームは L1/L2 ペアで何百ものデッキ。

360 デッキは手で作るものではありません。コンテンツファクトリーを構築するものです。

このガイドは 2Slides API でプログラム的に単語デッキを一括生成する 2026 実践プレイブック。最も重要なアーキテクチャ判断──そして最もよく間違われるもの──は正しい生成エンドポイントを選ぶことです。

まず正しいエンドポイントを選ぶ（ここでファクトリーが壊れる）

2Slides API は API 経由で 2 つの異なる生成フローを公開しています。そのうち片方だけが、後でナレーションを追加できるデッキを生成します。

エンドポイント	出力	ナレーション可能？	クレジット
`POST /api/v1/slides/generate`	Fast PPT ──テンプレート駆動 PPTX。テンプレートライブラリの `themeId` が必要	❌ 不可。ナレーションエンドポイントが明示的に拒否	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 の Fast PPT が最安。残りはナレーション付きワークフローを前提とします。

アーキテクチャ図

[ソース]                  [オーケストレーター]                 [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 側で MP4 が必要ならファクトリーで ffmpeg をサーバーで実行します。

Step 1 — ソーススキーマを先に設計

deck_id: vocab-b1-travel-2026-w14
source_l1: ja          # 学習者母語
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"
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Step 2 — 認証

API 管理ページでキー取得。Bearer 認証：

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 分で完了。

Step 4 — 規模で耐えるプロンプトテンプレート

{{source_l1}} 母語の {{cefr_level}} レベル {{target_l2}} 学習者用の語彙デッキを生成。
テーマ：{{theme}}。

カード数：{{word_count}}。

各カードの出力：
- 対象語（{{target_l2}}）
- 品詞
- IPA
- {{source_l1}} 訳
- 自然な {{theme}} 文脈の例文 2 つ、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" から成功状態に遷移するまで待つ。

2 つの音声パターン：

mode: "single"（単一音声）──直接単語、IPA、例文を読む
mode: "multi"（双人対話）──例文を 2 つの音声で分担、動詞や慣用句に最適

音声カタログは /tts_sample_voices/、よく使うのは Puck、Aoede、Charon、Kore。本番固定前に最新 API ドキュメントを確認。

重要：このエンドポイントはナレーションテキストと音声を一度で生成。「voice text」と「voice audio」を別々のエンドポイントで呼ばない──そういう独立した公開 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

# 全ページクリップを結合
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

各ページ音声時間はナレーションジェネレータが生成したもの──通常単語カードで 5–12 秒/スライド。Workspace UI からダウンロードする MP4 と同じ結果が、ファクトリーで自動的に得られます。

同じデッキの縦型（9:16）と横型（16:9）両方が必要なら、最もきれいな方法はスライド生成段階で 2 回生成すること（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 ワーカーで十分。1,000+：小ワーカープールに、ただしプール総並行が各エンドポイントレート制限を超えないように。

Step 9 — 配信パターン

LMS：合成 MP4 を Canvas / Moodle / Blackboard / Google Classroom に各 API でアップロード
TikTok / Reels / Shorts：9:16 MP4 を投稿ツール（Buffer、Later、ネイティブ）にキュー、1 日 1 本
Newsletter：PDF コンパイル（元の生成ジョブの downloadUrl）を週次メールに埋め込み
セールス / リードマグネット：PDF を Stan Store / Gumroad に、カルーセルティーザーで誘導

コスト計算（最初に計画すべき部分）

ナレーション付き 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 で各送信を冪等に。状態を (deck_id, status) で DB 行に格納し遷移（pending → generating → narrating → exporting → composed → distributed）。

品質ゲート

自動配信しない。機械可読品質チェック：

要求数とページ数一致
ZIP に正しい数の pages/page_NN.png と voices/page_NN.wav
各ページ音声が 3–15 秒
transcript.txt 非空、目標語を含む

最初 50 バッチは手動で 1/10 を点検。

バージョニング

各成果物に：プロンプトテンプレートバージョン、画像モデル（gemini-3-pro-image-preview vs gemini-3.1-flash-image-preview）、ナレーション音声、生成タイムスタンプ。

コスト遠隔測定

各デッキは既知のクレジットコスト。突然 2 倍 → 何かが変わった。

失敗処理

バックオフ 1 回再試行。2 回失敗で needs_human キュー。無限ループしない。

API を使うべきか

API が正解：

週 >10 デッキ
構造化ソースデータ
サーバー側で合成・配信したいナレーション付き MP4
LMS / スケジューラ / CMS 統合
プロンプトバージョン下の再現性

API が過剰：

週 1 デッキで毎回視覚調整（UI が速い──Workspace UI は MP4 合成までやってくれる）
個人学習用
レッスンごとに 1 デッキの教師

よくある質問

API キーはどこで取る？

2slides.com/api、API 管理タブ。

なぜ `/api/v1/slides/generate` のジョブにナレーションを追加できない？

generate は Fast PPT──テンプレート駆動 PPTX。出力は完成した .pptx ファイル、ナレーションジェネレータが読める「スライド画像 + テキスト」型ジョブではありません。ナレーションジェネレータは明示的に create-pdf-slides または create-like-this のジョブのみ受け付けます。

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 秒開始、60 秒上限まで倍化。連続 3 回 429 で同時ワーカー数を半減。/api/v1/jobs/{id} を 20 秒より速くポーリングしない。

Zapier / Make / n8n と統合可能？

可能──認証付き HTTP リクエストを送れるツールならどれでも。n8n はコンテンツファクトリーで特に人気。

生成デッキを公開インデックスから防ぐには？

API 生成デッキはデフォルトでアカウント私有、公開共有は別の明示アクション。

同じデッキの 9:16 と 16:9 両方を生成するには？

2 回生成──aspectRatio: "9:16" と "16:9"。レイアウトは比率ごとに最適化されており、事後クロップは見栄えが悪い。クレジット倍消費はビジュアルクオリティのための意図的トレードオフ。

結論

コンテンツファクトリーは構造化ソースデータ + 安定オーケストレーター + 正しい API エンドポイント。最頻の失敗は /api/v1/slides/generate（Fast PPT）を使ってナレーションしようとすること──このパスは閉じています。create-pdf-slides または create-like-this を使い、generate-narration でナレーション、download-slides-pages-voices でエクスポート、ffmpeg でサーバー側 MP4 合成。

手動側のワークフローは単語カードガイドとクリエイターワークフローを参照。