Comment générer 100 jeux de vocabulaire en lot avec l'API 2Slides (manuel d'usine à contenus 2026)

Une fois que vous avez validé le workflow manuel — générer un jeu de vocabulaire, le narrer, exporter les ressources — le goulot d'étranglement suivant est le volume. Une école de langues avec 12 niveaux et 30 thèmes hebdomadaires a besoin de 360 jeux par an. Une chaîne TikTok faceless qui publie quotidiennement a besoin de 365 jeux plus les variantes de format. Une équipe contenu d'une entreprise EdTech a besoin de centaines de jeux segmentés par paires L1/L2.

Vous ne construisez pas 360 jeux à la main. Vous construisez une usine à contenus.

Ce guide est le manuel pratique 2026 pour générer en lot des jeux de vocabulaire (et n'importe quel autre contenu de slides) avec l'API 2Slides. La décision d'architecture la plus importante — et celle la plus souvent ratée — est choisir le bon endpoint de génération.

Choisissez d'abord le bon endpoint (c'est là que la plupart des usines cassent)

2Slides expose deux flux de génération distincts via l'API. Un seul d'entre eux produit des jeux qui pourront ensuite être narrés.

Pour une usine de cartes de vocabulaire avec narration et audio exportable, utilisez

(ou si vous avez une mise en page de référence). N'utilisez pas — c'est l'endpoint Fast PPT et vous ne pouvez pas y ajouter de narration.

Si votre usine n'a besoin que de PPTX silencieux (sans audio, sans vidéo), Fast PPT via

est le chemin le moins cher. Le reste de ce manuel suppose le workflow narré.

L'architecture en un schéma

[Données source]         [Orchestrateur]                [API 2Slides]                    [Sorties]
    │                          │                               │                              │
 tableur de  ──prompt──▶  File de jobs  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 vocabulaire (Cron/script)                                    │                              │
    │                          │                               │                              │
                           Poll  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           toutes les 20-30s status: success                                  │
                                                              │                                ▼
                                                              │             [pages slides PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode, etc.) — async uniquement
                                                              │
                                                           Poll  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (gratuit ; renvoie un ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Optionnel) composer le MP4 côté client
                                                   avec FFmpeg, ou via l'UI Workspace
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

Données source → orchestrateur → API → ZIP de pages + voices → distribution. La composition MP4 est optionnelle et n'est pas un endpoint API public en 2026 — c'est une fonctionnalité de l'UI Workspace utilisant FFmpeg.wasm dans le navigateur. L'équivalent API est le ZIP pages-and-voices, que vous pouvez composer avec

côté serveur si vous avez besoin de MP4 dans l'usine.

Étape 1 — Concevez d'abord le schéma source

Le levier le plus puissant consiste à définir le schéma des données source avant tout appel API. Les jeux construits à partir d'un schéma propre sont reproductibles ; ceux construits à partir de prompts ad hoc ne le sont pas.

Une ligne source de jeu de vocabulaire qui passe à l'échelle :

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # langue maternelle de l'apprenant
target_l2: es          # langue apprise
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 autres
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # vertical pour la révision en short-form
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # voir /tts_sample_voices pour le catalogue
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Cet objet est l'unité de travail. Tout ce qui suit le consomme.

Construisez le schéma source dans ce que vous avez déjà : une Google Sheet pour les équipes non techniques, une table Postgres pour les équipes ingénierie, un CMS avec champs structurés pour les équipes contenu. Évitez de le construire en Markdown brut — Markdown convient à l'écriture humaine mais est mauvais pour l'automatisation en lot.

Étape 2 — Authentifiez-vous

Récupérez une clé API sur la page de gestion API. Le format est :

sk-2slides-{chaîne-hex-de-64-caractères}

Toutes les requêtes utilisent l'auth bearer :

Authorization: Bearer sk-2slides-...

Les limites de débit par endpoint sont documentées sur 2slides.com/api.md. Pour la production en lot :

• create-pdf-slides
  et
  create-like-this
  : concevez votre file en fonction de leurs limites de concurrence avec backoff exponentiel sur 429
• jobs/{id}
  (poll) : respectez la cadence de polling ci-dessous — 20–30s, sans agressivité
• download-slides-pages-voices
  : gratuit et plus rapide, mais toujours soumis à rate limit

Étape 3 — Soumettez un job de génération Nano Banana

Les cartes de vocabulaire fonctionnent mieux en mode async (la génération d'image par slide prend 1–3 minutes pour un jeu de 30 cartes).

curl -X POST "https://2slides.com/api/v1/slides/create-pdf-slides" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "<votre prompt en forme de jeu — voir Étape 4>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

La réponse contient le

(un UUID). Faites un polling jusqu'à la fin :

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

Cadence de polling : toutes les 20–30 secondes. Ne polleez pas plus vite — la documentation API le précise explicitement, et le polling agressif est la cause la plus fréquente de 429. La plupart des jeux se terminent en 1–3 minutes.

Quand

, le job a des images de slide stockées sur R2 et une pour la compilation PDF. Les images de slides elles-mêmes sont ce que vous combinerez ensuite avec l'audio.

Étape 4 — Construisez des templates de prompts qui tiennent à grande échelle

La plus grande différence entre une usine instable et une usine fiable, ce sont les templates de prompt. N'écrivez pas de prompts à l'exécution par jeu. Définissez un template par type de jeu et substituez les valeurs.

Template de jeu de vocabulaire (

) :

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.

Le style visuel est contrôlé par le paramètre

(prompt personnalisé) ou laissé en défaut ("infographie épurée, pas de photos, typographie équilibrée"). Gardez les prompts versionnés dans git. Quand un prompt change, journalisez la version avec chaque jeu généré pour pouvoir corréler les régressions de qualité aux changements de prompt.

Étape 5 — Ajoutez la narration

Une fois que le job de génération est

, lancez la narration. La narration est uniquement async et opère sur le même :

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

Puis pollez le même

jusqu'à ce que le message passe de "Voice narration generation in progress" à un état de succès.

Deux patterns de voix fonctionnent bien pour les cartes de vocabulaire :

• mode: "single"
  avec une seule voix — lecture directe du mot + IPA + phrase
• mode: "multi"
  avec deux voix — phrases d'exemple réparties entre locuteurs, idéal pour les verbes et les expressions idiomatiques

Le catalogue de voix est publié sur

. Les choix courants incluent , , , . Confirmez la prise en charge avec la dernière documentation API avant de figer une voix spécifique en production.

Important : ce seul endpoint génère à la fois le texte de la voix et l'audio de la voix. N'appelez pas d'endpoints séparés "texte voix" et "audio voix" — il n'existe pas d'API publique pour ces étapes indépendamment. Configurez la requête de narration une fois et l'API fait les deux.

Étape 6 — Exportez pages et voices (gratuit)

Une fois la narration terminée, récupérez tous les actifs dans un seul 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 réponse inclut une

(valide 1 heure) pour un ZIP qui contient :

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

Cet export est gratuit — aucun crédit consommé. Téléchargez le ZIP et stockez les actifs dans votre propre object store. L'URL pré-signée expire après 1 heure.

Étape 7 — (Optionnel) Composez le MP4 côté serveur

L'API 2Slides n'expose pas actuellement d'endpoint de composition MP4 — la génération MP4 vit dans l'UI Workspace via FFmpeg.wasm dans le navigateur. Pour une usine à contenus, composez le MP4 côté serveur avec

:

# Pour chaque page, construisez un clip de (image fixe) + (audio voix).
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

# Concaténez tous les clips par page dans le MP4 final.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

La cadence audio par page est celle produite par le générateur de narration — typiquement 5–12 secondes par slide pour les cartes de vocabulaire. Le résultat est le même MP4 qu'un utilisateur téléchargerait depuis l'UI Workspace, mais produit en headless dans votre pipeline d'usine.

Si vous voulez des variantes verticale (9:16) et horizontale (16:9) du même jeu, le chemin le plus propre est de générer le jeu deux fois avec des aspect ratios différents au stade de génération des slides (

vs ). Le crop FFmpeg a posteriori produit souvent des résultats moches car les slides ont été mis en page pour un aspect précis.

Étape 8 — Construisez l'orchestrateur

Un orchestrateur minimal gère cinq boucles :

# Pseudo-code

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

    # 1. Générer les slides via l'endpoint Nano Banana
    job = post("/api/v1/slides/create-pdf-slides", body=build_payload(deck))
    deck_artifact = poll_until_complete(job.data.jobId)

    # 2. Narrer (uniquement 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. Exporter le ZIP pages + voices (gratuit)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Télécharger et stocker les actifs dans votre object store
    download_to_s3(zip_url, deck.id)

    # 5. (Optionnel) composer le MP4 avec ffmpeg, puis distribuer
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Faites tourner cela sur une machine de worker avec une file. Pour 100 jeux par jour, un seul worker suffit. Pour 1 000+, distribuez vers un petit pool de workers — mais assurez-vous que le pool respecte les rate limits de chaque endpoint, pas seulement le nombre de workers.

Étape 9 — Patterns de distribution

La couche de distribution transforme les artefacts en valeur métier :

• LMS : uploadez le MP4 composé vers Canvas / Moodle / Blackboard / Google Classroom via leurs API respectives
• TikTok / Reels / Shorts : enfilez les MP4 9:16 dans un outil de publication (Buffer, Later, scheduler natif), un par jour
• Newsletter : intégrez la compilation PDF (depuis la
  downloadUrl
  du job de génération initial) comme lien de téléchargement dans la livraison hebdomadaire
• Vente / lead magnet : uploadez le PDF sur une page Stan Store / Gumroad ; le teaser carousel pousse le trafic

N'essayez pas d'inventer la distribution. Utilisez les API natives des plateformes et laissez votre orchestrateur déposer une ligne dans votre planificateur.

Le calcul du coût (la partie à planifier en premier)

Pour les jeux Nano Banana avec narration, les crédits s'accumulent plus vite que le pricing Fast PPT que certains lecteurs ont peut-être vu auparavant. Le calcul par jeu de 30 cartes (résolution 1K/2K, avec narration) :

• Planification : 10 crédits
• Génération de slides : 30 × 100 = 3 000 crédits
• Narration (texte + audio) : 30 × 210 = 6 300 crédits
• Export pages + voices : 0 crédit (gratuit)
• Total : ~9 310 crédits par jeu narré de 30 cartes

Sans narration, le même jeu coûte ~3 010 crédits. En résolution 4K, doublez la portion de génération de slides : 30 × 200 = 6 000 → ~12 310 crédits avec narration.

Pour une usine de 100 jeux/mois : 100 × 9 310 = ~931 000 crédits/mois. Comparez avec la page de tarification pour choisir un palier — et budgétez le 4K uniquement quand la sortie va dans un contexte qui en bénéficie (grands écrans, vidéo premium). Pour des vidéos de révision TikTok / Reels, 1K ou 2K suffit largement.

Patterns opérationnels qui évitent les incendies

Idempotence

Toute soumission de jeu doit être idempotente sur

. Si votre worker crashe en plein lot, redémarrer la file ne doit pas produire de jeux dupliqués. Le pattern le plus propre : stocker dans une ligne de base ; faire transitionner les états ().

Quality gates

Ne distribuez pas automatiquement. Avant de pousser vers TikTok ou Canvas, lancez un contrôle qualité lisible par machine sur l'artefact :

• Le nombre de pages correspond au nombre demandé
• Le ZIP contient le nombre attendu de fichiers
  pages/page_NN.png
  et
  voices/page_NN.wav
• La durée audio par page est entre 3 et 15 secondes (une carte de 30 secondes signifie presque toujours un script halluciné trop long)
• transcript.txt
  est non vide et contient les mots cibles

Pour les 50 premiers lots, faites en plus une vérification manuelle ponctuelle d'un jeu sur 10. Les 50 premiers lots sont là où les problèmes systémiques de prompt apparaissent.

Versioning

Chaque artefact stocke : version du template de prompt, version du modèle d'image (

vs ), voix de narration, timestamp de génération. Quand le modèle s'améliore ou qu'un prompt change, vous pouvez relancer uniquement les jeux concernés.

Télémétrie de coût

Chaque jeu a un coût en crédits connu (voir le calcul ci-dessus). Suivez les crédits consommés par jeu. Quand l'usage de crédits par jeu double inopinément, quelque chose a changé (drift du nombre de pages, retries, passage en 4K). Trouvez-le avant que la facture en crédits ne vous prenne de court.

Gestion des échecs

Un job en échec est normal — coupure réseau, charge du modèle, 5xx rare. Réessayez une fois après backoff. Après deux échecs, poussez le jeu dans une file

. Ne bouclez pas indéfiniment.

Build vs buy : quand utiliser l'API

L'API est la bonne réponse quand :

• Vous produisez >10 jeux/semaine
• Vous avez des données source structurées
• Vous avez besoin de MP4 narrés que vous composerez côté serveur et distribuerez
• Vous intégrez avec un LMS, un planificateur ou un CMS
• Vous voulez de la reproductibilité sous versioning de prompt

L'API est exagérée quand :

• Vous produisez 1 jeu par semaine et l'ajustez visuellement à chaque fois
• Vous êtes un apprenant qui construit des jeux pour son étude personnelle (l'UI est plus rapide — et l'UI Workspace fait aussi la composition MP4 pour vous)
• Vous êtes un enseignant qui construit un jeu par leçon (utilisez Create Slides from File ou Create Slides Like This et passez l'orchestration)

Foire aux questions

Où récupérer une clé API ?

2slides.com/api. Les clés vivent dans l'onglet de gestion API.

Pourquoi ne puis-je pas ajouter de narration à un job

/api/v1/slides/generate

?

L'endpoint

est Fast PPT — PPTX piloté par template. Sa sortie est un fichier .pptx finalisé, pas un job d'image-de-slide-plus-texte que le générateur de narration peut lire. Le générateur de narration n'accepte explicitement que les jobs issus de ou , qui produisent des jobs nano banana avec un contenu structuré par page.

Puis-je exporter le MP4 directement depuis l'API ?

Non, pas en 2026. L'export MP4 est une fonctionnalité de l'UI Workspace implémentée côté client avec FFmpeg.wasm. L'équivalent API est

, qui renvoie un ZIP contenant les images de slides, les fichiers audio et une transcription — vous composez vous-même le MP4 avec si vous en avez besoin dans un pipeline d'usine à contenus. Voir Étape 7.

Quelles langues l'API prend-elle en charge pour la génération ?

Plus de 22 langues, dont l'espagnol, le français, l'allemand, l'arabe, le japonais, le coréen, l'hindi, le vietnamien, le russe, le polonais, l'italien, le portugais, l'indonésien, le thaï, le turc et le chinois (simplifié/traditionnel). Passez via

.

Quel est le coût en crédits ?

Pour les jeux Nano Banana : 10 (planification) + 100/slide en 1K/2K (ou 200/slide en 4K) pour la génération de slides, plus 210/page (10 texte + 200 audio) pour la narration. L'export pages + voices est gratuit. Un jeu narré de 30 cartes en 2K coûte ~9 310 crédits. Voir la page de tarification et la section calcul de coût ci-dessus.

Comment gérer les rate limits 429 ?

Backoff exponentiel. Démarrez à 1s, doublez jusqu'à 60s. Après trois 429 consécutifs, divisez par deux le nombre de workers concurrents. Ne pollez pas

plus vite que toutes les 20 secondes — c'est la cause la plus fréquente de 429.

Puis-je intégrer avec Zapier / Make / n8n ?

Oui — tout outil capable de faire des requêtes HTTP authentifiées peut piloter l'API 2Slides. n8n est en particulier populaire pour les usines à contenus car il gère nativement les patterns de polling et de file.

Comment empêcher l'indexation publique des jeux générés ?

Les jeux générés via l'API sont privés à votre compte par défaut. Le partage public est une action séparée et explicite.

Comment générer les versions verticale (9:16) et horizontale (16:9) du même jeu ?

Générez le jeu deux fois — une fois avec

et une fois avec . Les slides sont mis en page selon l'aspect ratio au moment de la génération, donc le crop a posteriori a rarement bonne allure. Oui, cela double le coût en crédits ; c'est un trade-off délibéré pour des visuels propres.

À retenir

Une usine à contenus, c'est des données source structurées + un orchestrateur stable + les bons endpoints API. L'API 2Slides est le troisième élément ; vous êtes responsable des deux premiers. L'échec d'usine le plus courant est d'utiliser

(Fast PPT) puis d'essayer de le narrer — ce chemin est fermé. Utilisez ou , narrez avec , exportez avec et composez le MP4 côté serveur avec .

Pour le pendant manuel du même workflow, voir le guide des cartes de vocabulaire et le guide du workflow créateur. Les patterns d'UI là-bas sont les mêmes que ceux que vous automatisez avec l'API ; comprendre d'abord le flux manuel rend l'intégration API beaucoup plus rapide.