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 create-pdf-slides (ou create-like-this si vous avez une mise en page de référence). N'utilisez pas /api/v1/slides/generate — 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 /api/v1/slides/generate 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 → 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 ffmpeg 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 :

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 :

Toutes les requêtes utilisent l'auth bearer :

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

La réponse contient le jobId (un UUID). Faites un polling jusqu'à la fin :

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 status: "success", le job a des images de slide stockées sur R2 et une downloadUrl 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 (userInput) :

Le style visuel est contrôlé par le paramètre designStyle (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 status: "success", lancez la narration. La narration est uniquement async et opère sur le même jobId :

Puis pollez le même /api/v1/jobs/{jobId} 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 /tts_sample_voices/. Les choix courants incluent Puck, Aoede, Charon, Kore. 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 :

La réponse inclut une downloadUrl (valide 1 heure) pour un ZIP qui contient :

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 ffmpeg :

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 (aspectRatio: "9:16" vs "16:9"). 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 :

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 deck_id. 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 (deck_id, status) dans une ligne de base ; faire transitionner les états (pending → generating → narrating → exporting → composed → distributed).

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 (gemini-3-pro-image-preview vs gemini-3.1-flash-image-preview), 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 needs_human. 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 generate 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 create-pdf-slides ou create-like-this, 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 download-slides-pages-voices, qui renvoie un ZIP contenant les images de slides, les fichiers audio et une transcription — vous composez vous-même le MP4 avec ffmpeg 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 responseLanguage.

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 /api/v1/jobs/{id} 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 aspectRatio: "9:16" et une fois avec aspectRatio: "16:9". 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 /api/v1/slides/generate (Fast PPT) puis d'essayer de le narrer — ce chemin est fermé. Utilisez create-pdf-slides ou create-like-this, narrez avec generate-narration, exportez avec download-slides-pages-voices et composez le MP4 côté serveur avec ffmpeg.

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.