100 Vokabel-Decks per Batch über die 2Slides-API erzeugen (Content-Factory-Playbook 2026)

Q: Warum kann ich keine Vertonung an einen /api/v1/slides/generate-Job hängen?

Das generate-Endpoint ist Fast PPT — vorlagenbasierte PPTX. Output ist eine fertige .pptx-Datei, kein Slide-Bild-plus-Text-Job, den der Vertonungsgenerator lesen kann. Der Vertonungsgenerator akzeptiert ausschließlich Jobs aus create-pdf-slides oder create-like-this, die strukturierten Per-Page-Inhalt liefern.

Q: Wie erzeuge ich vertikale (9:16) und horizontale (16:9) Versionen desselben Decks?

Deck zweimal generieren — einmal mit aspectRatio: "9:16", einmal mit aspectRatio: "16:9". Folien werden pro Seitenverhältnis layoutet, daher sieht nachträgliches Cropping selten gut aus. Ja, doppelte Credit-Kosten — bewusster Tradeoff für saubere Visuals.

Sobald Sie den manuellen Workflow validiert haben — ein Vokabeldeck erzeugen, vertonen, Assets exportieren — ist der nächste Engpass das Volumen. Eine Sprachschule mit 12 Niveaus und 30 Wochenthemen braucht 360 Decks im Jahr. Ein täglich postender Faceless-TikTok-Kanal braucht 365 Decks plus Format-Varianten. Ein Content-Team eines EdTech-Unternehmens braucht hunderte Decks segmentiert nach L1/L2-Paaren.

360 Decks baut man nicht von Hand. Man baut eine Content Factory.

Dieser Leitfaden ist das praktische 2026-Playbook für die Batch-Erzeugung von Vokabel-Decks (und beliebigem Folien-Content) mit der 2Slides API. Die wichtigste architektonische Entscheidung — und am häufigsten falsch getroffen — ist die Wahl des richtigen Generierungs-Endpoints.

Das richtige Endpoint zuerst wählen (hier brechen die meisten Factories)

2Slides exponiert über die API zwei Generierungs-Flows. Nur einer erzeugt Decks, die anschließend vertont werden können.

Endpoint	Ergebnis	Vertonung möglich?	Credits
`POST /api/v1/slides/generate`	Fast PPT — vorlagenbasierte PPTX. Erfordert eine `themeId` aus der Vorlagenbibliothek.	nein. Das Vertonungs-Endpoint lehnt Jobs von hier explizit ab.	10 / Seite
`POST /api/v1/slides/create-pdf-slides`	Nano Banana — bildgenerierte Folien aus Textprompt. Gleiche Engine wie Workspace.	ja	10 (Planung) + 100 / Folie (1K/2K) oder 200 / Folie (4K)
`POST /api/v1/slides/create-like-this`	Nano Banana — bildgenerierte Folien zu Referenzbild.	ja	wie oben

Für eine Vokabelkarten-Content-Factory mit Vertonung und exportierbarem Audio nutzen Sie create-pdf-slides (oder create-like-this, wenn Sie ein Referenzlayout haben). Nutzen Sie nicht /api/v1/slides/generate — das ist Fast PPT, dort lässt sich keine Vertonung anfügen.

Wenn Ihre Factory nur stille PPTX (kein Audio, kein Video) braucht, ist Fast PPT via /api/v1/slides/generate der günstigste Weg. Der Rest dieses Playbooks setzt den vertonten Workflow voraus.

Die Architektur in einem Diagramm

[Quelldaten]            [Orchestrator]                   [2Slides API]                    [Outputs]
    │                          │                               │                              │
 Vokabel-     ──Prompt──▶  Job-Queue ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 Tabelle      (Cron/Skript)                                    │                              │
    │                          │                               │                              │
                           Poll  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           alle 20-30s    status: success                                     │
                                                              │                                ▼
                                                              │             [pages slides PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode, etc.) — nur async
                                                              │
                                                           Poll  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (kostenlos; liefert ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Optional) MP4 client-seitig komponieren
                                                   mit FFmpeg, oder über Workspace-UI
                                                              │
                                                              ▼
                                                   [LMS / TikTok / Newsletter / S3]

Quelldaten → Orchestrator → API → ZIP aus Pages und Voices → Distribution. MP4-Komposition ist optional und kein öffentliches API-Endpoint Stand 2026 — sie ist ein Workspace-UI-Feature mit FFmpeg.wasm im Browser. API-seitig erhalten Sie das Pages-und-Voices-ZIP, das Sie mit ffmpeg serverseitig komponieren, wenn Sie MP4 in der Factory brauchen.

Schritt 1 — Quellschema zuerst entwerfen

Der größte Hebel ist die Definition des Quelldatenschemas vor jedem API-Aufruf. Decks aus sauberem Schema sind reproduzierbar; Decks aus Ad-hoc-Prompts nicht.

Eine skalierbare Vokabel-Deck-Quellzeile:

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # Muttersprache des Lerners
target_l2: es          # Zielsprache
cefr_level: B1
theme: travel
words:
  - { word: "boarding pass", ipa: "/ˈbɔːrdɪŋ pæs/", pos: noun, l1: "tarjeta de embarque" }
  - { word: "layover",       ipa: "/ˈleɪoʊvər/",     pos: noun, l1: "escala" }
  - { word: "to delay",      ipa: "/dɪˈleɪ/",         pos: verb, l1: "retrasar" }
  # ... 27 weitere
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # vertikal für Kurzform-Wiederholung
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # Voice-Katalog unter /tts_sample_voices
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Dieses Objekt ist die Arbeitseinheit. Alles Downstream konsumiert es.

Bauen Sie das Quellschema in dem, was Ihr Team bereits nutzt: Google Sheet für nicht-technische Teams, Postgres-Tabelle für Engineering, CMS mit strukturierten Feldern für Content-Teams. Vermeiden Sie reine Markdown-Dateien — gut für Menschen-Schreiben, schlecht für Batch.

Schritt 2 — Authentifizieren

API-Key auf der API-Verwaltungsseite holen. Format:

sk-2slides-{64-character-hex-string}

Alle Anfragen mit Bearer-Auth:

Authorization: Bearer sk-2slides-...

Endpoint-spezifische Rate Limits unter 2slides.com/api.md. Für Batchproduktion:

create-pdf-slides und create-like-this: Queue um die Concurrency-Limits herum bauen, exponentielles Backoff bei 429
jobs/{id} (Polling): Polling-Frequenz unten respektieren — 20–30 s, nicht aggressiv
download-slides-pages-voices: kostenlos und schneller, aber rate-limited

Schritt 3 — Nano-Banana-Generierungsjob abschicken

Vokabelkarten laufen am besten async (die Bildgenerierung pro Folie dauert 1–3 Minuten für 30 Karten).

curl -X POST "https://2slides.com/api/v1/slides/create-pdf-slides" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "<Ihr deckförmiger Prompt — siehe Schritt 4>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

Die Antwort enthält die jobId (UUID). Pollen bis zur Fertigstellung:

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

Polling-Frequenz: alle 20–30 Sekunden. Nicht schneller — die API-Doku weist explizit darauf hin, aggressives Polling ist die häufigste Ursache für 429. Die meisten Decks sind in 1–3 Minuten fertig.

Bei status: "success" liegen Folienbilder auf R2 und es gibt eine downloadUrl für eine PDF-Kompilation. Die Folienbilder selbst kombinieren Sie später mit Audio.

Schritt 4 — Skalierfeste Prompt-Templates bauen

Der größte Unterschied zwischen einer wackligen und einer stabilen Factory sind Prompt-Templates. Schreiben Sie keine Prompts pro Deck zur Laufzeit. Definieren Sie ein Template pro Deck-Typ und füllen Werte ein.

Vokabel-Deck-Template (userInput):

Generate a {{cefr_level}}-level vocabulary deck for {{source_l1}}-speaking learners
of {{target_l2}}. Theme: {{theme}}.

Number of cards: {{word_count}}.

For each card, output exactly:
- Target word (in {{target_l2}})
- Part of speech
- IPA transcription
- Translation in {{source_l1}}
- Two example sentences in natural {{theme}} context, B1 syntax, 8–14 words each

Words to include:
{{word_list_yaml}}

End with a 3-card recap of the most useful 3 words from the deck.

Visueller Stil über designStyle (eigener Prompt) oder Default („sauberes Infografik-Design, keine Fotos, ausgewogene Typografie"). Prompts in git versionieren. Bei Änderung die Version mit jedem Deck loggen — so korrelieren Sie Qualitätseinbrüche mit Prompt-Änderungen.

Schritt 5 — Vertonung anhängen

Sobald der Generierungsjob status: "success" ist, Vertonung anstoßen. Vertonung ist nur async und arbeitet auf derselben 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
  }'

Dann erneut /api/v1/jobs/{jobId} pollen, bis die Message von „Voice narration generation in progress" auf einen Erfolgsstatus wechselt.

Zwei Voice-Patterns für Vokabelkarten:

mode: "single" mit einer Stimme — geradlinig: Wort + IPA + Satz
mode: "multi" mit zwei Stimmen — Beispielsätze auf Sprecher aufgeteilt, ideal für Verben und Idiome

Voice-Katalog unter /tts_sample_voices/. Häufige Wahl: Puck, Aoede, Charon, Kore. Vor dem Pinning auf eine Voice in Produktion mit der aktuellen API-Doku gegenchecken.

Wichtig: Dieses eine Endpoint erzeugt sowohl Voice-Text als auch Voice-Audio. Keine separaten „Voice-Text"- und „Voice-Audio"-Endpoints aufrufen — die gibt es öffentlich nicht. Vertonung einmal konfigurieren, die API erledigt beides.

Schritt 6 — Pages und Voices exportieren (kostenlos)

Sobald die Vertonung fertig ist, alle Assets in einem ZIP holen:

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

Die Antwort enthält eine downloadUrl (1 Stunde gültig) für ein ZIP mit:

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

Dieser Export ist kostenlos — keine Credits. ZIP herunterladen und Assets in Ihren Object Store legen. Die Presigned-URL läuft nach 1 Stunde ab.

Schritt 7 — (Optional) MP4 serverseitig komponieren

Die 2Slides API bietet derzeit kein MP4-Komposition-Endpoint — MP4-Erzeugung lebt im Workspace-UI über FFmpeg.wasm im Browser. In einer Content Factory komponieren Sie MP4 serverseitig mit ffmpeg:

# Pro Seite einen Clip aus (Bildstandbild) + (Voice-Audio).
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

# Alle Per-Page-Clips zur finalen MP4 zusammenführen.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

Audio-Kadenz pro Seite ist das, was der Vertonungsgenerator produziert hat — meist 5–12 Sekunden pro Folie für Vokabelkarten. Ergebnis ist dieselbe MP4, die ein Nutzer aus dem Workspace-UI herunterladen würde, nur headless in Ihrer Pipeline.

Wer dasselbe Deck vertikal (9:16) und horizontal (16:9) braucht: am saubersten das Deck zweimal mit unterschiedlichem aspectRatio ("9:16" vs "16:9") generieren. Nachträgliches FFmpeg-Cropping liefert oft hässliche Ergebnisse, weil die Folien für ein bestimmtes Verhältnis layoutet wurden.

Schritt 8 — Den Orchestrator bauen

Ein minimaler Orchestrator behandelt fünf Schleifen:

# Pseudocode

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

    # 1. Folien via Nano-Banana-Endpoint generieren
    job = post("/api/v1/slides/create-pdf-slides", body=build_payload(deck))
    deck_artifact = poll_until_complete(job.data.jobId)

    # 2. Vertonen (nur async)
    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 exportieren (kostenlos)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Assets herunterladen und im eigenen Object Store ablegen
    download_to_s3(zip_url, deck.id)

    # 5. (Optional) MP4 mit ffmpeg komponieren, dann verteilen
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Auf einem Worker mit Queue laufen lassen. Für 100 Decks pro Tag genügt ein Worker. Für 1,000+ einen kleinen Worker-Pool — der aber die Endpoint-Rate-Limits respektieren muss, nicht nur die Worker-Zahl.

Schritt 9 — Distributionsmuster

Die Distribution wandelt Artefakte in Geschäftswert um:

LMS: komponierte MP4 via API in Canvas / Moodle / Blackboard / Google Classroom hochladen
TikTok / Reels / Shorts: 9:16-MP4 in ein Posting-Tool (Buffer, Later, nativer Scheduler) einreihen, eines pro Tag
Newsletter: PDF-Kompilation (aus der downloadUrl des Originaljobs) als Download im Wochen-Issue verlinken
Sales / Lead-Magnet: PDF auf Stan Store / Gumroad hochladen; Carousel-Teaser treibt Traffic

Distribution nicht selbst neu erfinden. Plattform-eigene APIs nutzen und Orchestrator eine Zeile im Scheduler ablegen lassen.

Kostenrechnung (zuerst planen)

Für Nano-Banana-Decks mit Vertonung summieren sich Credits schneller als beim Fast-PPT-Pricing, das man vielleicht kennt. Mathematik pro 30-Karten-Deck (1K/2K, mit Vertonung):

Planung: 10 Credits
Folienerzeugung: 30 × 100 = 3,000 Credits
Vertonung (Text + Audio): 30 × 210 = 6,300 Credits
Pages-+-Voices-Export: 0 Credits (kostenlos)
Gesamt: ~9,310 Credits pro vertontem 30-Karten-Deck

Ohne Vertonung ~3,010 Credits. Bei 4K den Folienanteil verdoppeln: 30 × 200 = 6,000 → ~12,310 Credits mit Vertonung.

Für eine 100-Decks/Monat-Factory: 100 × 9,310 = ~931,000 Credits/Monat. Mit der Preisseite abgleichen — und 4K nur dort budgetieren, wo es zählt (große Bildschirme, Premium-Video). Für TikTok/Reels-Reviews reicht 1K oder 2K.

Operative Muster, die Brände verhindern

Idempotenz

Jede Deck-Übermittlung idempotent auf deck_id. Crasht der Worker mitten im Batch, darf der Restart keine Duplikate erzeugen. Sauber: (deck_id, status) in einer DB-Zeile, Statuswechsel (pending → generating → narrating → exporting → composed → distributed).

Quality Gates

Nicht automatisch verteilen. Vor TikTok oder Canvas einen maschinenlesbaren Qualitätscheck auf das Artefakt:

Seitenzahl entspricht Anforderung
ZIP enthält erwartete Anzahl pages/page_NN.png und voices/page_NN.wav
Audiodauer pro Seite zwischen 3 und 15 Sekunden (eine 30-Sekunden-Karte heißt fast immer halluziniertes Skript)
transcript.txt ist nicht leer und enthält die Zielwörter

Für die ersten 50 Batches zusätzlich manuelle Stichprobe 1 von 10 Decks. Dort tauchen systemische Promptprobleme auf.

Versionierung

Jedes Artefakt speichert: Prompt-Template-Version, Bildmodell-Version (gemini-3-pro-image-preview vs gemini-3.1-flash-image-preview), Vertonungs-Voice, Generierungs-Zeitstempel. Bei Modellverbesserung oder Promptwechsel betroffene Decks gezielt neu rechnen.

Kosten-Telemetrie

Jedes Deck hat einen bekannten Credit-Preis (siehe oben). Credits pro Deck tracken. Verdoppelt sich der Verbrauch unerwartet, hat sich etwas geändert (Seitendrift, Retries, 4K-Wechsel). Vor der Rechnung finden.

Fehlerbehandlung

Ein fehlgeschlagener Job ist normal — Netzaussetzer, Modelllast, seltener 5xx. Nach Backoff einmal retryen. Nach zwei Fehlern in eine needs_human-Queue. Nicht endlos schleifen.

Build vs. Buy: Wann überhaupt die API?

Die API ist die richtige Antwort, wenn:

Sie >10 Decks/Woche produzieren
Strukturierte Quelldaten haben
Vertonte MP4s brauchen, die Sie serverseitig komponieren und verteilen
Mit LMS, Scheduler oder CMS integrieren
Reproduzierbarkeit unter Prompt-Versionierung wollen

Die API ist Overkill, wenn:

Sie 1 Deck pro Woche produzieren und visuell tunen
Sie Lerner:in sind und Decks für sich selbst bauen (UI ist schneller — und das Workspace-UI macht die MP4-Komposition für Sie)
Sie Lehrkraft sind und ein Deck pro Stunde bauen (Create Slides from File oder Create Slides Like This und Orchestrierung sparen)

Häufig gestellte Fragen

Woher bekomme ich einen API-Key?

2slides.com/api. Keys liegen im API-Verwaltungs-Tab.

Warum kann ich keine Vertonung an einen `/api/v1/slides/generate`-Job hängen?

Das generate-Endpoint ist Fast PPT — vorlagenbasierte PPTX. Output ist eine fertige .pptx-Datei, kein Slide-Bild-plus-Text-Job, den der Vertonungsgenerator lesen kann. Der Vertonungsgenerator akzeptiert ausschließlich Jobs aus create-pdf-slides oder create-like-this, die strukturierten Per-Page-Inhalt liefern.

Kann ich MP4 direkt aus der API exportieren?

Nein, Stand 2026 nicht. MP4-Export ist ein Workspace-UI-Feature mit FFmpeg.wasm. API-Äquivalent ist download-slides-pages-voices — ein ZIP mit Folienbildern, Audios und Transcript. Sie komponieren MP4 selbst mit ffmpeg. Siehe Schritt 7.

Welche Sprachen unterstützt die API für die Generierung?

22+ Sprachen, darunter Spanisch, Französisch, Deutsch, Arabisch, Japanisch, Koreanisch, Hindi, Vietnamesisch, Russisch, Polnisch, Italienisch, Portugiesisch, Indonesisch, Thai, Türkisch und Chinesisch (vereinfacht/traditionell). Per responseLanguage.

Was kosten die Credits?

Für Nano-Banana-Decks: 10 (Planung) + 100/Folie bei 1K/2K (oder 200/Folie bei 4K) für die Folienerzeugung, plus 210/Seite (10 Text + 200 Audio) für Vertonung. Pages-+-Voices-Export kostenlos. Ein vertontes 30-Karten-Deck in 2K liegt bei ~9,310 Credits. Siehe Preisseite und Kostenrechnung oben.

Wie behandle ich 429 Rate Limits?

Exponentielles Backoff. Start bei 1 s, Verdopplung bis 60 s. Nach drei aufeinanderfolgenden 429 Worker-Concurrency halbieren. /api/v1/jobs/{id} nicht schneller als alle 20 Sekunden pollen — das ist die häufigste 429-Ursache.

Kann ich mit Zapier / Make / n8n integrieren?

Ja — jedes Tool, das authentifizierte HTTP-Requests stellen kann, treibt die 2Slides API. n8n ist für Content-Factories besonders beliebt, weil es Polling und Queues nativ behandelt.

Wie verhindere ich, dass generierte Decks öffentlich indexiert werden?

Per API erzeugte Decks sind standardmäßig privat zum Account. Öffentliches Teilen ist eine separate explizite Aktion.

Wie erzeuge ich vertikale (9:16) und horizontale (16:9) Versionen desselben Decks?

Deck zweimal generieren — einmal mit aspectRatio: "9:16", einmal mit aspectRatio: "16:9". Folien werden pro Seitenverhältnis layoutet, daher sieht nachträgliches Cropping selten gut aus. Ja, doppelte Credit-Kosten — bewusster Tradeoff für saubere Visuals.

Das Fazit

Eine Content Factory ist strukturiertes Quellschema + stabiler Orchestrator + die richtigen API-Endpoints. Die 2Slides API ist das dritte Stück; Sie verantworten die ersten zwei. Häufigster Factory-Fehler: /api/v1/slides/generate (Fast PPT) nutzen und versuchen zu vertonen — der Pfad ist geschlossen. Stattdessen create-pdf-slides oder create-like-this, vertonen mit generate-narration, exportieren mit download-slides-pages-voices, MP4 serverseitig mit ffmpeg komponieren.

Für die manuelle Seite desselben Workflows siehe Vokabelkarten-Leitfaden und Creator-Workflow-Leitfaden. Die UI-Patterns dort sind dieselben Patterns, die Sie automatisieren; den manuellen Flow zu verstehen, beschleunigt die API-Integration deutlich.