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

Q: Dlaczego nie mogę dodać narracji do /api/v1/slides/generate?

Endpoint generate 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 create-pdf-slides lub create-like-this, które produkują strukturalny content per-strona.

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

Wygeneruj talię dwa razy — raz z aspectRatio: "9:16", raz z "16:9". 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.

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ć.

Endpoint	Co produkuje	Możliwa narracja?	Kredyty
`POST /api/v1/slides/generate`	Fast PPT — PPTX z szablonu. Wymaga `themeId` z biblioteki szablonów.	nie. Endpoint narracji jawnie odrzuca zadania stąd.	10 / strona
`POST /api/v1/slides/create-pdf-slides`	Nano Banana — slajdy generowane z obrazem z promptu tekstowego. Ta sama silnik co Workspace.	tak	10 (planowanie) + 100 / slajd (1K/2K) lub 200 / slajd (4K)
`POST /api/v1/slides/create-like-this`	Nano Banana — slajdy generowane z obrazem dopasowane do obrazu referencyjnego.	tak	jak wyżej

Dla content factory fiszek z narracją i eksportowalnym audio używaj create-pdf-slides (lub create-like-this, jeśli masz układ referencyjny). Nie używaj /api/v1/slides/generate — 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 /api/v1/slides/generate 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 ffmpeg-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 jobId (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 status: "success" job ma obrazy na R2 i downloadUrl 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 (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.

Styl wizualny przez parametr designStyle (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 status: "success", odpal narrację. Narracja jest tylko async i działa na tym samym 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
  }'

Polluj /api/v1/jobs/{jobId} 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 /tts_sample_voices/. Częsty wybór: Puck, Aoede, Charon, Kore. 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 downloadUrl (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 ffmpeg-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 aspectRatio ("9:16" vs "16:9"). 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 deck_id. Jeśli worker padnie w środku batcha, restart kolejki nie może produkować duplikatów. Czysty wzorzec: trzymaj (deck_id, status) w wierszu DB; przejścia stanów (pending → generating → narrating → exporting → composed → distributed).

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 (gemini-3-pro-image-preview vs gemini-3.1-flash-image-preview), 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 needs_human. 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 generate 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 create-pdf-slides lub create-like-this, 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 download-slides-pages-voices, zwracający ZIP z obrazami slajdów, plikami audio i transkryptem — MP4 składasz sam ffmpeg-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 responseLanguage.

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 /api/v1/jobs/{id} 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 aspectRatio: "9:16", raz z "16:9". 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 /api/v1/slides/generate (Fast PPT) i próba narracji — ta ścieżka jest zamknięta. Używaj create-pdf-slides lub create-like-this, narratoruj generate-narration, eksportuj download-slides-pages-voices, składaj MP4 po stronie serwera ffmpeg-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ę.