Come generare in batch 100 mazzi di vocabolario con l'API 2Slides (manuale della content factory 2026)

Una volta validato il workflow manuale — generare un mazzo di vocabolario, narrarlo, esportare le risorse — il prossimo collo di bottiglia è il volume. Una scuola di lingue con 12 livelli e 30 temi settimanali ha bisogno di 360 mazzi all'anno. Un canale TikTok faceless che pubblica ogni giorno ha bisogno di 365 mazzi più le varianti di proporzione. Un team di contenuti di un'azienda EdTech ha bisogno di centinaia di mazzi segmentati per coppie L1/L2.

Non costruisci 360 mazzi a mano. Costruisci una content factory.

Questa guida è il manuale pratico 2026 per generare in batch mazzi di vocabolario (e qualunque altro contenuto di slide) con l'API 2Slides. La singola decisione architetturale più importante — e quella sbagliata più spesso — è scegliere l'endpoint di generazione giusto.

Scegli prima l'endpoint giusto (qui si rompe la maggior parte delle factory)

2Slides espone due flussi distinti di generazione tramite API. Solo uno di essi produce mazzi che possono essere successivamente narrati.

Per una content factory di schede di vocabolario con narrazione e audio esportabile, usa

(oppure se hai un layout di riferimento). Non usare — è l'endpoint Fast PPT e non puoi aggiungerci la narrazione.

Se la tua factory ha bisogno solo di PPTX silenzioso (niente audio, niente video), Fast PPT via

è il percorso più economico. Il resto di questo manuale assume il workflow con narrazione.

L'architettura in un diagramma

[Dati sorgente]          [Orchestratore]                [API 2Slides]                    [Output]
    │                          │                               │                              │
 foglio di    ──prompt──▶  Coda di job  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 vocaboli     (Cron/script)                                   │                              │
    │                          │                               │                              │
                           Poll  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           ogni 20-30s    status: success                                    │
                                                              │                                ▼
                                                              │             [pages slides PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode, ecc.) — solo async
                                                              │
                                                           Poll  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (gratuito; restituisce ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Opzionale) componi MP4 lato client
                                                   con FFmpeg, oppure usa la UI di Workspace
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

Dati sorgente → orchestratore → API → ZIP di pages + voices → distribuzione. La composizione MP4 è opzionale e non è un endpoint API pubblico nel 2026 — è una funzionalità della UI di Workspace che usa FFmpeg.wasm nel browser. L'equivalente API è lo ZIP pages-and-voices, che puoi comporre con

lato server se ti serve MP4 nella factory.

Step 1 — Progetta prima lo schema sorgente

La mossa con la leva più alta è definire lo schema dei dati sorgente prima di qualsiasi chiamata API. I mazzi costruiti da uno schema pulito sono riproducibili; quelli costruiti da prompt ad hoc no.

Una riga sorgente di mazzo di vocabolario che scala:

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # lingua nativa dello studente
target_l2: es          # lingua che si sta imparando
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" }
  # ... altri 27
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # verticale per il ripasso short-form
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # vedi /tts_sample_voices per il catalogo
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Quell'oggetto è l'unità di lavoro. Tutto ciò che viene dopo lo consuma.

Costruisci lo schema sorgente con quello che hai già: un Google Sheet per team non tecnici, una tabella Postgres per team di engineering, un CMS con campi strutturati per team di contenuti. Evita di costruirlo in semplici file Markdown — Markdown va bene per la scrittura umana ma è scarso per l'automazione in batch.

Step 2 — Autenticati

Procurati una chiave API dalla pagina di gestione API. Il formato è:

sk-2slides-{stringa-hex-di-64-caratteri}

Tutte le richieste usano bearer auth:

Authorization: Bearer sk-2slides-...

I limiti di rate per endpoint sono documentati su 2slides.com/api.md. Per la produzione in batch:

• create-pdf-slides
  e
  create-like-this
  : progetta la coda intorno ai loro limiti di concorrenza con backoff esponenziale sui 429
• jobs/{id}
  (poll): rispetta la cadenza di polling sotto — 20–30s, niente aggressività
• download-slides-pages-voices
  : gratuito e più veloce, ma comunque soggetto a rate limit

Step 3 — Invia un job di generazione Nano Banana

Le schede di vocabolario funzionano meglio in modalità async (la generazione delle immagini per slide richiede 1–3 minuti per un mazzo da 30 schede).

curl -X POST "https://2slides.com/api/v1/slides/create-pdf-slides" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "<il tuo prompt in forma di mazzo — vedi Step 4>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

La risposta contiene il

(un UUID). Fai polling fino al completamento:

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

Cadenza di polling: ogni 20–30 secondi. Non fare polling più veloce — la documentazione API lo evidenzia esplicitamente, e il polling aggressivo è la causa più comune di 429. La maggior parte dei mazzi si completa in 1–3 minuti.

Quando

, il job ha le immagini delle slide salvate su R2 e una per la compilazione PDF. Le immagini delle slide stesse sono ciò che combinerai successivamente con l'audio.

Step 4 — Costruisci template di prompt che reggano alla scala

La differenza più grande tra una factory traballante e una affidabile sono i template di prompt. Non scrivere prompt a runtime per ogni mazzo. Definisci un template per tipo di mazzo e sostituisci i valori.

Template di mazzo di vocabolario (

):

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.

Lo stile visuale è controllato dal parametro

(prompt personalizzato) o lasciato al default ("infografica pulita, niente fotografie, tipografia bilanciata"). Tieni i prompt sotto versionamento in git. Quando un prompt cambia, registra la versione con ogni mazzo generato così puoi correlare le regressioni di qualità ai cambiamenti di prompt.

Step 5 — Aggiungi la narrazione

Quando il job di generazione è in

, lancia la narrazione. La narrazione è solo async e opera sullo stesso :

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

Poi fai polling sullo stesso

finché il messaggio passa da "Voice narration generation in progress" a uno stato di successo.

Due pattern di voce funzionano bene per le schede di vocabolario:

• mode: "single"
  con una sola voce — lettura diretta di parola + IPA + frase
• mode: "multi"
  con due voci — frasi di esempio divise tra parlanti, ideali per verbi e modi di dire

Il catalogo delle voci è pubblicato su

. Scelte comuni includono , , , . Conferma il supporto con la documentazione API più recente prima di fissare una voce specifica in produzione.

Importante: questo singolo endpoint genera sia il testo della voce che l'audio della voce. Non chiamare endpoint separati per "testo voce" e "audio voce" — non esiste un'API pubblica per questi step indipendenti. Configura la richiesta di narrazione una volta sola e l'API fa entrambi.

Step 6 — Esporta pages e voices (gratuito)

Una volta completata la narrazione, recupera tutti gli asset in un unico 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"
  }'

La risposta include una

(valida 1 ora) per uno ZIP che contiene:

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

Questo export è gratuito — nessun credito consumato. Scarica lo ZIP e archivia gli asset nel tuo object store. La URL pre-firmata scade dopo 1 ora.

Step 7 — (Opzionale) Componi MP4 lato server

L'API 2Slides attualmente non espone un endpoint di composizione MP4 — la generazione MP4 vive nella UI di Workspace via FFmpeg.wasm nel browser. Per una content factory, componi MP4 lato server con

:

# Per ogni pagina, costruisci un clip di (immagine fissa) + (audio voce).
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

# Concatena tutti i clip per pagina nell'MP4 finale.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

La cadenza audio per pagina è quella che il generatore di narrazione ha prodotto — tipicamente 5–12 secondi per slide per le schede di vocabolario. Il risultato è lo stesso MP4 che un utente scaricherebbe dalla UI di Workspace, ma prodotto headless nella tua pipeline di factory.

Se vuoi varianti verticale (9:16) e orizzontale (16:9) dello stesso mazzo, il percorso più pulito è generare il mazzo due volte con aspect ratio diversi nello stage di generazione delle slide (

vs ). Il crop con FFmpeg a posteriori produce spesso risultati brutti perché le slide sono state impaginate per un aspect specifico.

Step 8 — Costruisci l'orchestratore

Un orchestratore minimale gestisce cinque loop:

# Pseudo-codice

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

    # 1. Genera le slide via endpoint Nano Banana
    job = post("/api/v1/slides/create-pdf-slides", body=build_payload(deck))
    deck_artifact = poll_until_complete(job.data.jobId)

    # 2. Narra (solo 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. Esporta lo ZIP pages + voices (gratuito)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Scarica e archivia gli asset nel tuo object store
    download_to_s3(zip_url, deck.id)

    # 5. (Opzionale) componi MP4 con ffmpeg, poi distribuisci
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Eseguilo su una worker box con una coda. Per 100 mazzi al giorno, un worker basta. Per 1.000+, distribuisci su un piccolo pool di worker — ma assicurati che il pool rispetti i rate limit di ciascun endpoint, non solo il numero di worker.

Step 9 — Pattern di distribuzione

Il livello di distribuzione trasforma gli artefatti in valore di business:

• LMS: carica l'MP4 composto su Canvas / Moodle / Blackboard / Google Classroom tramite le rispettive API
• TikTok / Reels / Shorts: metti in coda gli MP4 9:16 in uno strumento di pubblicazione (Buffer, Later, scheduler nativo), uno al giorno
• Newsletter: incorpora la compilazione PDF (dalla
  downloadUrl
  del job di generazione originale) come link di download nel numero settimanale
• Vendite / lead magnet: carica il PDF su una pagina Stan Store / Gumroad; il teaser carousel porta traffico

Non provare a inventare la distribuzione. Usa le API native delle piattaforme e lascia che il tuo orchestratore inserisca una riga nel tuo scheduler.

Calcolo dei costi (la parte da pianificare per prima)

Per i mazzi Nano Banana con narrazione, i crediti si accumulano più velocemente del pricing Fast PPT che alcuni lettori potrebbero aver visto in precedenza. Il calcolo per mazzo da 30 schede (risoluzione 1K/2K, con narrazione):

• Planning: 10 crediti
• Generazione slide: 30 × 100 = 3.000 crediti
• Narrazione (testo + audio): 30 × 210 = 6.300 crediti
• Export pages + voices: 0 crediti (gratuito)
• Totale: ~9.310 crediti per mazzo narrato da 30 schede

Senza narrazione, lo stesso mazzo è ~3.010 crediti. A risoluzione 4K, raddoppia la porzione di generazione slide: 30 × 200 = 6.000 → ~12.310 crediti con narrazione.

Per una factory da 100 mazzi/mese: 100 × 9.310 = ~931.000 crediti/mese. Confronta con la pagina di pricing per scegliere un tier — e prevedi budget per il 4K solo quando l'output va in un contesto che ne beneficia (schermi grandi, video premium). Per i video di ripasso TikTok / Reels, 1K o 2K bastano.

Pattern operativi che evitano gli incendi

Idempotenza

Ogni invio di mazzo dovrebbe essere idempotente su

. Se il tuo worker crasha a metà batch, il riavvio della coda non deve produrre mazzi duplicati. Il pattern più pulito: archiviare in una riga di database; far transitare gli stati ().

Quality gate

Non distribuire automaticamente. Prima di inviare a TikTok o Canvas, lancia un controllo qualità leggibile dalla macchina sull'artefatto:

• Il numero di pagine corrisponde a quello richiesto
• Lo ZIP contiene il numero atteso di file
  pages/page_NN.png
  e
  voices/page_NN.wav
• La durata dell'audio per pagina è tra 3 e 15 secondi (una scheda da 30 secondi quasi sempre significa uno script allucinato lungo)
• transcript.txt
  è non vuoto e contiene le parole target

Per i primi 50 batch, fai anche un controllo manuale a campione di 1 mazzo su 10. I primi 50 batch sono dove emergono i problemi sistemici di prompt.

Versionamento

Ogni artefatto memorizza: versione del template di prompt, versione del modello di immagini (

vs ), voce della narrazione, timestamp di generazione. Quando il modello migliora o un prompt cambia, puoi rieseguire solo i mazzi interessati.

Telemetria dei costi

Ogni mazzo ha un costo in crediti noto (vedi calcolo sopra). Traccia i crediti consumati per mazzo. Quando l'uso di crediti per mazzo raddoppia inaspettatamente, qualcosa è cambiato (drift del numero di pagine, retry, passaggio a 4K). Trovalo prima che la bolletta dei crediti ti colga di sorpresa.

Gestione dei fallimenti

Un job fallito è normale — un blip di rete, carico del modello, raro 5xx. Ritenta una volta dopo backoff. Dopo due fallimenti, sposta il mazzo in una coda

. Non andare in loop infinito.

Build vs buy: quando usare l'API

L'API è la risposta giusta quando:

• Produci >10 mazzi/settimana
• Hai dati sorgente strutturati
• Hai bisogno di MP4 narrati che comporrai lato server e distribuirai
• Integri con un LMS, scheduler o CMS
• Vuoi riproducibilità sotto versionamento dei prompt

L'API è eccessiva quando:

• Produci 1 mazzo a settimana e lo personalizzi visivamente ogni volta
• Sei uno studente che costruisce mazzi per studio personale (la UI è più rapida — e la UI di Workspace fa anche la composizione MP4 per te)
• Sei un insegnante che costruisce un mazzo a lezione (usa Create Slides from File o Create Slides Like This e salta l'orchestrazione)

Domande frequenti

Dove ottengo una chiave API?

2slides.com/api. Le chiavi vivono nella tab di gestione API.

Perché non posso aggiungere la narrazione a un job

/api/v1/slides/generate

?

L'endpoint

è Fast PPT — PPTX guidato da template. Il suo output è un file .pptx finalizzato, non un job di immagine-di-slide-più-testo che il generatore di narrazione possa leggere. Il generatore di narrazione accetta esplicitamente solo job da o , che producono job nano banana con contenuto strutturato per pagina.

Posso esportare MP4 direttamente dall'API?

No, non nel 2026. L'export MP4 è una funzionalità della UI di Workspace implementata lato client con FFmpeg.wasm. L'equivalente API è

, che restituisce uno ZIP di immagini di slide, file audio e una trascrizione — componi tu stesso l'MP4 con se ne hai bisogno in una pipeline di content factory. Vedi Step 7.

Quali lingue supporta l'API per la generazione?

Più di 22 lingue, tra cui spagnolo, francese, tedesco, arabo, giapponese, coreano, hindi, vietnamita, russo, polacco, italiano, portoghese, indonesiano, thailandese, turco e cinese (semplificato/tradizionale). Passale via

.

Qual è il costo in crediti?

Per i mazzi Nano Banana: 10 (planning) + 100/slide a 1K/2K (o 200/slide a 4K) per la generazione delle slide, più 210/pagina (10 testo + 200 audio) per la narrazione. Export pages + voices è gratuito. Un mazzo narrato da 30 schede a 2K è ~9.310 crediti. Vedi la pagina di pricing e la sezione di calcolo dei costi sopra.

Come gestisco i rate limit 429?

Backoff esponenziale. Parti da 1s, raddoppia fino a 60s. Dopo tre 429 consecutivi, dimezza il numero di worker concorrenti. Non fare polling su

più veloce di ogni 20 secondi — è la causa più comune di 429.

Posso integrare con Zapier / Make / n8n?

Sì — qualsiasi tool che possa fare richieste HTTP autenticate può guidare l'API 2Slides. n8n in particolare è popolare per le content factory perché gestisce nativamente i pattern di polling e coda.

Come impedisco che i mazzi generati vengano indicizzati pubblicamente?

I mazzi generati via API sono privati al tuo account per default. La condivisione pubblica è un'azione separata ed esplicita.

Come genero le versioni verticale (9:16) e orizzontale (16:9) dello stesso mazzo?

Genera il mazzo due volte — una con

e una con . Le slide vengono impaginate per aspect ratio al momento della generazione, quindi il crop a posteriori raramente viene bene. Sì, questo significa raddoppiare il costo in crediti; è un trade-off deliberato per visivi puliti.

La conclusione

Una content factory è dati sorgente strutturati + un orchestratore stabile + gli endpoint API giusti. L'API 2Slides è il terzo pezzo; tu sei responsabile dei primi due. Il fallimento di factory più comune è usare

(Fast PPT) e poi cercare di narrarlo — quel percorso è chiuso. Usa o , narra con , esporta con e componi MP4 lato server con .

Per il lato manuale dello stesso workflow, vedi la guida alle schede di vocabolario e la guida al workflow del creator. I pattern UI lì sono gli stessi che stai automatizzando con l'API; capire prima il flusso manuale rende l'integrazione API molto più veloce.