Jak wsadowo generować 100 talii słownictwa z 2Slides API (playbook content factory 2026)

Gdy zwalidujesz manualny workflow — wygeneruj jedną talię, narratoruj, eksportuj — następnym wąskim gardłem jest wolumen. Szkoła językowa z 12 poziomami i 30 tematami tygodniowymi potrzebuje 360 talii rocznie. Faceless TikTok publikujący codziennie potrzebuje 365 talii plus warianty proporcji. Zespół contentowy w EdTechu potrzebuje setek talii segmentowanych po parach L1/L2.

360 talii nie buduje się ręcznie. Buduje się content factory.

Ten przewodnik to praktyczny playbook 2026 do wsadowego generowania talii słownictwa (i dowolnego innego contentu slajdowego) z 2Slides API. Najważniejsza decyzja architektoniczna — i ta, którą najczęściej zawalają — to wybór właściwego endpointu generacji.

Najpierw wybierz właściwy endpoint (tu pęka większość fabryk)

2Slides eksponuje przez API dwa różne flow generacji. Tylko jeden produkuje talie, które potem da się narratorować.

Dla content factory fiszek z narracją i eksportowalnym audio używaj

(lub

create-like-this

, jeśli masz układ referencyjny). Nie używaj — to Fast PPT, do tego nie da się dodać narracji.

Jeśli twoja fabryka potrzebuje tylko cichej PPTX (bez audio, bez wideo), Fast PPT przez

to najtańsza ścieżka. Reszta playbooka zakłada workflow z narracją.

Architektura w jednym diagramie

[Dane źródłowe]         [Orkiestrator]                   [2Slides API]                    [Outputy]
    │                          │                               │                              │
 arkusz       ──prompt──▶   Job queue ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 słownictwa  (Cron/skrypt)                                     │                              │
    │                          │                               │                              │
                           Poll  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           co 20-30s    status: success                                       │
                                                              │                                ▼
                                                              │             [pages slides PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode itd.) — tylko async
                                                              │
                                                           Poll  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (bezpłatne; zwraca ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Opcjonalnie) złóż MP4 po stronie klienta
                                                   z FFmpeg lub przez Workspace UI
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

Dane źródłowe → orkiestrator → API → ZIP pages + voices → dystrybucja. Składanie MP4 jest opcjonalne i nie jest publicznym endpointem API w 2026 — to feature Workspace UI używający FFmpeg.wasm w przeglądarce. Ekwiwalent API to ZIP pages-and-voices, który składasz

-iem po stronie serwera, jeśli MP4 jest potrzebne w fabryce.

Krok 1 — Najpierw zaprojektuj schemat źródłowy

Największa dźwignia to zdefiniowanie schematu danych źródłowych przed jakimkolwiek wywołaniem API. Talie z czystego schematu są reprodukowalne; talie z ad-hoc promptów nie.

Skalowalny wiersz źródłowy talii słownictwa:

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # język ojczysty uczącego się
target_l2: es          # nauczany język
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 więcej
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # pion dla powtórki krótkoformatowej
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # katalog głosów /tts_sample_voices
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Ten obiekt to jednostka pracy. Wszystko downstream go konsumuje.

Buduj schemat w tym, czego zespół już używa: Google Sheet dla nietechnicznych, Postgres dla inżynierii, CMS ze strukturyzowanymi polami dla contentu. Unikaj plików Markdown — Markdown jest dobry do pisania, słaby do automatyzacji wsadowej.

Krok 2 — Uwierzytelnij się

API key na stronie zarządzania API. Format:

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

Wszystkie requesty z bearer auth:

Authorization: Bearer sk-2slides-...

Per-endpoint rate limity udokumentowane na 2slides.com/api.md. Dla produkcji wsadowej:

• create-pdf-slides
  i
  create-like-this
  : zaprojektuj kolejkę wokół ich limitów współbieżności z exponential backoff przy 429
• jobs/{id}
  (poll): respektuj kadencję — 20–30s, nie agresywnie
• download-slides-pages-voices
  : bezpłatny i szybszy, ale nadal rate-limited

Krok 3 — Wyślij job generacji Nano Banana

Fiszki działają najlepiej w trybie async (generacja per-slajd zajmuje 1–3 minuty dla talii 30 kart).

curl -X POST "https://2slides.com/api/v1/slides/create-pdf-slides" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "<twój prompt w formie talii — zob. krok 4>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

Odpowiedź zawiera

(UUID). Polluj do zakończenia:

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

Kadencja pollingu: co 20–30 sekund. Nie szybciej — dokumentacja API jawnie to pisze, a agresywne polling to najczęstsza przyczyna 429. Większość talii kończy się w 1–3 minuty.

Przy

job ma obrazy na R2 i dla kompilacji PDF. Same obrazy później łączysz z audio.

Krok 4 — Szablony promptów, które trzymają się przy skali

Największa różnica między chwiejną a niezawodną fabryką to szablony promptów. Nie pisz promptów w runtime per-talia. Zdefiniuj szablon per-typ talii i podstaw wartości.

Szablon talii słownictwa (

):

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.

Styl wizualny przez parametr

(custom prompt) lub default („czysta infografika, bez zdjęć, zbalansowana typografia"). Trzymaj prompty w git. Przy zmianie loguj wersję z każdą wygenerowaną talią — skorelujesz regresje jakości ze zmianami promptu.

Krok 5 — Dodaj narrację

Gdy job generacji ma

, odpal narrację. Narracja jest tylko async i działa na tym samym :

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

Polluj

aż message przejdzie z „Voice narration generation in progress" do success.

Dwa wzorce głosu dla fiszek:

• mode: "single"
  z jednym głosem — proste czytanie słowo + IPA + zdanie
• mode: "multi"
  z dwoma głosami — przykłady rozdzielone między mówców, idealne dla czasowników i idiomów

Katalog głosów na

. Częsty wybór: , , , . Przed pinowaniem konkretnego głosu w produkcji zweryfikuj wsparcie w aktualnej dokumentacji API.

Ważne: ten jeden endpoint generuje i tekst głosu, i audio. Nie wołaj osobnych „voice text" / „voice audio" endpointów — publiczne API nie oferuje ich osobno. Skonfiguruj request narracji raz, API robi oba.

Krok 6 — Eksport stron i głosów (bezpłatnie)

Po zakończeniu narracji pobierz wszystkie zasoby w jednym 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"
  }'

Odpowiedź zawiera

(ważne 1 godzinę) dla ZIP-a:

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

Ten eksport jest bezpłatny — bez kredytów. Pobierz ZIP i zachowaj zasoby we własnym object store. Presigned URL wygasa po godzinie.

Krok 7 — (Opcjonalnie) Złóż MP4 po stronie serwera

2Slides API obecnie nie eksponuje endpointu składania MP4 — generacja MP4 żyje w Workspace UI przez FFmpeg.wasm w przeglądarce. Dla content factory składaj MP4 po stronie serwera

-iem:

# Per strona, klip z (obraz statyczny) + (audio głosu).
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

# Konkatenuj klipy do końcowego MP4.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

Tempo audio per-strona to to, co wygenerował generator narracji — typowo 5–12 sekund per slajd dla fiszek. Wynik to ten sam MP4, który użytkownik pobrałby z Workspace UI, tylko produkowany headlessowo.

Dla pionowej (9:16) i poziomej (16:9) wersji tej samej talii najczystsza ścieżka to wygenerować talię dwa razy z różnymi

( vs ). Późniejsze przycinanie FFmpegiem często wygląda brzydko, bo slajdy zostały rozplanowane pod konkretną proporcję.

Krok 8 — Zbuduj orkiestrator

Minimalny orkiestrator obsługuje pięć pętli:

# Pseudokod

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

    # 1. Generuj slajdy przez Nano Banana
    job = post("/api/v1/slides/create-pdf-slides", body=build_payload(deck))
    deck_artifact = poll_until_complete(job.data.jobId)

    # 2. Narratoruj (tylko 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. Eksportuj ZIP pages + voices (bezpłatnie)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Pobierz i zachowaj zasoby we własnym object store
    download_to_s3(zip_url, deck.id)

    # 5. (Opcjonalnie) złóż MP4 ffmpeg-iem, potem rozdystrybuuj
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Uruchom na workerze z kolejką. Dla 100 talii dziennie wystarczy jeden worker. Dla 1,000+ rozpędź mały pool — ale pool musi respektować rate limity per-endpoint, nie tylko liczbę workerów.

Krok 9 — Wzorce dystrybucji

Warstwa dystrybucji zamienia artefakty w wartość biznesową:

• LMS: prześlij złożony MP4 do Canvas / Moodle / Blackboard / Google Classroom przez ich API
• TikTok / Reels / Shorts: zakolejkuj 9:16 MP4 w narzędziu publikacyjnym (Buffer, Later, natywny scheduler), jedno na dzień
• Newsletter: osadź kompilację PDF (z
  downloadUrl
  jobu generacji) jako link do pobrania w wydaniu
• Sales / lead magnet: prześlij PDF na Stan Store / Gumroad; teaser karuzelowy napędza ruch

Nie wymyślaj dystrybucji. Używaj API platform i niech orkiestrator wrzuci wiersz do schedulera.

Matematyka kosztów (planuj jako pierwsze)

Dla talii Nano Banana z narracją kredyty rosną szybciej niż w Fast PPT, którego ktoś mógł wcześniej widzieć. Matematyka per talia 30 kart (1K/2K, z narracją):

• Planowanie: 10 kredytów
• Generacja slajdów: 30 × 100 = 3,000 kredytów
• Narracja (tekst + audio): 30 × 210 = 6,300 kredytów
• Eksport pages + voices: 0 (bezpłatny)
• Łącznie: ~9,310 kredytów per narratorowana talia 30 kart

Bez narracji ta sama talia ~3,010 kredytów. Przy 4K część generacji się podwaja: 30 × 200 = 6,000 → ~12,310 z narracją.

Dla fabryki 100 talii/miesiąc: 100 × 9,310 = ~931,000 kredytów/miesiąc. Porównaj ze stroną cennika — i budżetuj 4K tylko tam, gdzie ma znaczenie (duże ekrany, premium wideo). Dla powtórek TikTok/Reels 1K lub 2K wystarcza.

Operacyjne wzorce zapobiegające pożarom

Idempotencja

Każde zgłoszenie talii powinno być idempotentne na

. Jeśli worker padnie w środku batcha, restart kolejki nie może produkować duplikatów. Czysty wzorzec: trzymaj w wierszu DB; przejścia stanów ().

Bramki jakości

Nie auto-dystrybuuj. Przed pchnięciem na TikToka czy Canvas zrób maszynowy check jakości artefaktu:

• Liczba stron zgadza się z żądaniem
• ZIP zawiera oczekiwaną liczbę
  pages/page_NN.png
  i
  voices/page_NN.wav
• Czas trwania audio per-strona między 3 a 15 sekund (30-sekundowa karta to prawie zawsze halucynowany długi skrypt)
• transcript.txt
  nie jest pusty i zawiera słowa docelowe

Dla pierwszych 50 batchy także manualna próbka 1 na 10 talii. Tam wychodzą systemowe problemy promptowe.

Wersjonowanie

Każdy artefakt zapisuje: wersję szablonu promptu, wersję modelu obrazu (

vs ), głos narracji, timestamp generacji. Przy ulepszeniu modelu lub zmianie promptu reodpalasz tylko dotknięte talie.

Telemetria kosztów

Każda talia ma znany koszt kredytowy (zob. wyżej). Śledź kredyty per-talia. Gdy zużycie nieoczekiwanie się podwaja, coś się zmieniło (drift liczby stron, retries, przełączenie na 4K). Znajdź przed rachunkiem.

Obsługa błędów

Niepowodzenie joba jest normalne — chwilowe sieciowe, obciążenie modelu, rzadki 5xx. Retry raz po backoff. Po dwóch błędach push do kolejki

. Nie pętli w nieskończoność.

Build vs buy: kiedy w ogóle używać API?

API jest właściwą odpowiedzią, gdy:

• Produkujesz >10 talii/tydzień
• Masz strukturyzowane dane źródłowe
• Potrzebujesz narratorowanych MP4 składanych po stronie serwera i dystrybuowanych
• Integrujesz z LMS, schedulerem lub CMS
• Chcesz reprodukowalności pod wersjonowaniem promptów

API jest przesadą, gdy:

• Produkujesz 1 talię tygodniowo i tunujesz wizualnie
• Jesteś uczącym się budującym talie do nauki własnej (UI jest szybsze — i Workspace UI robi też składanie MP4)
• Jesteś nauczycielem budującym talię na lekcję (użyj Create Slides from File lub Create Slides Like This i pomiń orkiestrację)

Najczęściej zadawane pytania

Skąd biorę API key?

2slides.com/api. Klucze w zakładce zarządzania API.

Dlaczego nie mogę dodać narracji do

/api/v1/slides/generate

?

Endpoint

to Fast PPT — PPTX z szablonu. Output to gotowy plik .pptx, nie job slide-image-plus-text, który generator narracji może czytać. Generator narracji jawnie akceptuje tylko zadania z lub , które produkują strukturalny content per-strona.

Czy mogę eksportować MP4 bezpośrednio z API?

Nie, nie w 2026. Eksport MP4 to feature Workspace UI implementowany po stronie klienta z FFmpeg.wasm. Ekwiwalentem API jest

, zwracający ZIP z obrazami slajdów, plikami audio i transkryptem — MP4 składasz sam -iem, jeśli potrzebujesz w pipeline'ie. Zob. krok 7.

Jakie języki API obsługuje przy generacji?

22+, w tym hiszpański, francuski, niemiecki, arabski, japoński, koreański, hindi, wietnamski, rosyjski, polski, włoski, portugalski, indonezyjski, tajski, turecki i chiński (uproszczony/tradycyjny). Przekaż przez

.

Jaki jest koszt kredytów?

Dla talii Nano Banana: 10 (planowanie) + 100/slajd przy 1K/2K (lub 200/slajd przy 4K) za generację, plus 210/strona (10 tekst + 200 audio) za narrację. Eksport pages + voices bezpłatny. Narratorowana talia 30 kart w 2K to ~9,310 kredytów. Zob. stronę cennika i sekcję matematyki kosztów wyżej.

Jak obsłużyć 429 rate limity?

Exponential backoff. Start 1s, podwajaj do 60s. Po trzech kolejnych 429 zmniejsz o połowę liczbę współbieżnych workerów. Nie polluj

częściej niż co 20 sekund — to najczęstsza przyczyna 429.

Czy mogę zintegrować z Zapierem / Make / n8n?

Tak — każde narzędzie z autoryzowanym HTTP może napędzić 2Slides API. n8n szczególnie popularne dla content factory, bo natywnie obsługuje polling i kolejki.

Jak zapobiec publicznemu indeksowaniu wygenerowanych talii?

Talie generowane przez API są domyślnie prywatne dla konta. Publiczne udostępnianie to osobna jawna akcja.

Jak wygenerować pionową (9:16) i poziomą (16:9) wersję tej samej talii?

Wygeneruj talię dwa razy — raz z

, raz z . Slajdy są rozplanowane per proporcja w czasie generacji, post-hoc cropping rzadko wygląda dobrze. Tak, podwaja koszt kredytów; to świadomy tradeoff za czyste wizuale.

Wniosek

Content factory to strukturyzowane dane źródłowe + stabilny orkiestrator + właściwe endpointy API. 2Slides API to trzeci kawałek; pierwsze dwa są twoje. Najczęstsza porażka fabryki to użycie

(Fast PPT) i próba narracji — ta ścieżka jest zamknięta. Używaj lub , narratoruj , eksportuj , składaj MP4 po stronie serwera -iem.

Stronę manualną tego workflow zob. przewodnik po fiszkach i przewodnik twórcy. Wzorce UI tam to te same, które automatyzujesz w API; zrozumienie ścieżki manualnej znacznie przyspiesza integrację.