Cómo generar 100 presentaciones de vocabulario en lote con la API de 2Slides (Playbook 2026)

Q: ¿Por qué no puedo añadir narración a un job de /api/v1/slides/generate?

generate es Fast PPT — PPTX por plantilla. Su salida es un .pptx finalizado, no un job de slide-imagen-más-texto que el narrador pueda leer. El narrador solo acepta jobs de create-pdf-slides o create-like-this.

Q: ¿Qué idiomas soporta?

22+ idiomas vía responseLanguage.

Q: ¿Versiones 9:16 y 16:9 de la misma presentación?

Genera dos veces — aspectRatio: "9:16" y "16:9". Las slides están maquetadas por aspecto, croppear post-hoc se ve feo. Sí, dobla coste créditos — trade-off intencional por visuales limpios.

Una vez validado el flujo manual — generar una presentación, narrarla, exportar los assets — el siguiente cuello de botella es el volumen. Una escuela de idiomas con 12 niveles y 30 temas semanales necesita 360 presentaciones al año. Un canal TikTok faceless diario necesita 365 más variantes de aspecto. Un equipo de contenido EdTech necesita cientos segmentadas por L1/L2.

No construyes 360 presentaciones a mano. Construyes una fábrica de contenido.

Esta guía es el playbook práctico 2026 para generar presentaciones de vocabulario en lote con la API de 2Slides. La decisión arquitectónica más importante — y la que más se hace mal — es elegir el endpoint de generación correcto.

Elige el endpoint correcto primero (aquí se rompe la mayoría de fábricas)

La API expone dos flujos de generación distintos. Solo uno produce presentaciones a las que se les puede añadir narración después.

Endpoint	Salida	¿Narración posible?	Créditos
`POST /api/v1/slides/generate`	Fast PPT — PPTX por plantilla. Requiere `themeId` de la biblioteca.	❌ No. El endpoint de narración rechaza explícitamente jobs creados aquí.	10 / página
`POST /api/v1/slides/create-pdf-slides`	Nano Banana — slides con imágenes generadas desde prompt. Mismo motor que Workspace.	✅ Sí	10 (planificación) + 100 / slide (1K/2K) o 200 / slide (4K)
`POST /api/v1/slides/create-like-this`	Nano Banana — coincidiendo con un imagen de referencia	✅ Sí	Igual

Para una fábrica de tarjetas de vocabulario con narración y audio exportable, usa create-pdf-slides (o create-like-this si tienes un layout de referencia). No uses /api/v1/slides/generate — ese es el endpoint Fast PPT y no se le puede añadir narración.

Si tu fábrica solo necesita PPTX silencioso (sin audio, sin video), /api/v1/slides/generate con Fast PPT es la ruta más barata. El resto del playbook asume el flujo narrado.

Arquitectura

[Datos fuente]            [Orquestador]                   [API 2Slides]                   [Salidas]
    │                          │                              │                              │
hoja vocab ──prompt──▶  Cola jobs  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
                       (Cron / script)                       │                                │
    │                          │                              │                                │
                          Polling  ──GET──▶  /api/v1/jobs/{jobId} ◀────────────────────────────┘
                          cada 20-30s    status: success                                       │
                                                              │                                 ▼
                                                              │             [pages PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode etc.) — solo async
                                                              │
                                                          Polling  ──GET──▶  /api/v1/jobs/{jobId}
                                                          message: "Voice narration ... in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (gratis; devuelve ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Opcional) componer MP4 con ffmpeg
                                                   o usar el Workspace UI
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

Datos → orquestador → API → ZIP de pages + voices → distribución. La composición MP4 es opcional y no es un endpoint público de la API en 2026 — es una funcionalidad del Workspace UI usando FFmpeg.wasm en el navegador. El equivalente API es el ZIP pages-and-voices, que puedes componer con ffmpeg server-side si necesitas MP4 en la pipeline de la fábrica.

Paso 1 — Diseña el schema fuente primero

deck_id: vocab-b1-travel-2026-w14
source_l1: es          # idioma nativo
target_l2: en          # idioma a aprender
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 más
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Paso 2 — Autenticación

Página de gestión API. Bearer auth:

Authorization: Bearer sk-2slides-...

Rate limits por endpoint en 2slides.com/api.md. Para create-pdf-slides/create-like-this: diseña la cola alrededor de límites de concurrencia con backoff exponencial en 429. Para jobs/{id}: respeta cadencia de 20–30s.

Paso 3 — Enviar job de generación Nano Banana

Modo async (la generación de imagen por slide tarda 1–3 min para deck de 30):

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

Devuelve jobId (UUID). Polling:

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

Cadencia: cada 20–30 segundos. No más rápido — la documentación lo dice explícitamente, polling agresivo es la causa más común de 429. La mayoría completan en 1–3 minutos.

Cuando status: "success", las imágenes de slides están en R2 y hay downloadUrl para una compilación PDF. Las imágenes de slide son lo que después combinarás con audio.

Paso 4 — Plantillas de prompt que aguantan a escala

Genera presentación vocabulario nivel {{cefr_level}} para aprendices {{source_l1}}
de {{target_l2}}. Tema: {{theme}}.

Número tarjetas: {{word_count}}.

Cada tarjeta:
- Palabra objetivo ({{target_l2}})
- Categoría gramatical
- Transcripción IPA
- Traducción {{source_l1}}
- Dos frases ejemplo en contexto natural {{theme}}, sintaxis B1, 8–14 palabras

Palabras a incluir:
{{word_list_yaml}}

Termina con recap 3 tarjetas de las 3 más útiles.

Estilo visual con designStyle (prompt custom) o por defecto. Versiona prompts en git.

Paso 5 — Añadir narración

Una vez status: "success", lanza narración. Solo async, opera sobre el mismo 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
  }'

Polling al mismo /api/v1/jobs/{jobId} hasta que el message transicione de "Voice narration generation in progress" a éxito.

Dos patrones de voz:

mode: "single" — una voz lee palabra + IPA + frases
mode: "multi" — frases divididas entre dos voces, ideal para verbos y modismos

Catálogo de voces en /tts_sample_voices/, comunes: Puck, Aoede, Charon, Kore. Confirma con la última API doc antes de fijar voz en producción.

Importante: este único endpoint genera tanto el texto como el audio. No llames endpoints separados de "voice text" y "voice audio" — no existe esa API pública. Una sola petición, la API hace ambos pasos.

Paso 6 — Exportar pages y voices (gratis)

Tras narración, recupera todos los assets en un solo 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"
  }'

downloadUrl (válida 1 hora) apunta a un ZIP con:

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

Esta exportación es gratis — sin créditos consumidos. Descarga y guarda en tu object store. La URL prefirmada expira en 1 hora.

Paso 7 — (Opcional) Componer MP4 server-side

La API de 2Slides no expone endpoint de composición MP4 — la generación MP4 vive en el Workspace UI vía FFmpeg.wasm. En la fábrica, componer con ffmpeg:

# Por cada página: clip de (imagen still) + (audio voz)
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

# Concatenar clips en MP4 final
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

Duración por página = lo que generó el narrador — típicamente 5–12s/slide para vocabulario. Resultado idéntico al MP4 que descarga un usuario desde el Workspace UI, pero producido headless en la fábrica.

Si quieres variantes vertical (9:16) y horizontal (16:9) de la misma presentación, lo más limpio es generar la presentación dos veces con distintos aspectRatio en la fase de generación. Cropear con ffmpeg post-hoc se ve mal porque las slides están maquetadas para una proporción específica.

Paso 8 — Construir el orquestador

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

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

    # 2. Narración (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. Exportar ZIP pages + voices (gratis)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Descargar a tu object store
    download_to_s3(zip_url, deck.id)

    # 5. (Opcional) componer MP4 con ffmpeg, distribuir
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Un worker para 100 decks/día. 1,000+: pool pequeño respetando rate limits por endpoint.

Paso 9 — Patrones de distribución

LMS: subir MP4 compuesto a Canvas / Moodle / Blackboard / Google Classroom
TikTok / Reels / Shorts: cola de 9:16 MP4 a Buffer / Later / scheduler nativo
Newsletter: PDF compilado (del downloadUrl original) como descarga
Lead magnet: PDF a Stan Store / Gumroad

Matemáticas de coste (a planificar primero)

Las presentaciones Nano Banana narradas suman créditos más rápido que el precio Fast PPT. Por presentación de 30 tarjetas (1K/2K, narración):

Planificación: 10 créditos
Generación slides: 30 × 100 = 3,000 créditos
Narración (texto + audio): 30 × 210 = 6,300 créditos
Exportación pages + voices: 0 (gratis)
Total: ~9,310 créditos por presentación narrada de 30 tarjetas

Sin narración la misma presentación es ~3,010 créditos. A 4K resolución: 30 × 200 = 6,000 → ~12,310 créditos con narración.

Fábrica de 100 decks/mes: 100 × 9,310 = ~931,000 créditos/mes. Compara con precios. 4K solo cuando el output va a contexto que se beneficia (pantallas grandes, video premium). Para revisión TikTok / Reels, 1K o 2K basta.

Patrones operativos

Idempotencia

Cada submit idempotente en deck_id. Estados (deck_id, status) en DB: pending → generating → narrating → exporting → composed → distributed.

Quality gates

Antes de TikTok / Canvas: verificar conteo de páginas, que el ZIP tiene pages/page_NN.png y voices/page_NN.wav esperados, audio entre 3–15s/página, transcript.txt no vacío. Primeros 50 lotes: verificar manualmente 1/10.

Versionado

Cada artefacto guarda: versión prompt, versión modelo (gemini-3-pro-image-preview vs gemini-3.1-flash-image-preview), voz narración, timestamp.

Telemetría de coste

Coste conocido por presentación. Si dobla, algo cambió.

Manejo de fallas

Backoff y 1 reintento. Tras 2 fallas, push a needs_human. Sin bucle infinito.

Build vs buy

API correcto cuando: >10 presentaciones/semana, datos estructurados, MP4 narrado server-side, integras LMS/scheduler/CMS, reproducibilidad bajo versionado prompt.

API overkill cuando: 1/semana ajustando visualmente (UI más rápida — Workspace UI también compone MP4), aprendiz personal, profesor 1/lección.

Preguntas frecuentes

¿Dónde obtengo API key?

2slides.com/api, tab gestión API.

¿Por qué no puedo añadir narración a un job de `/api/v1/slides/generate`?

generate es Fast PPT — PPTX por plantilla. Su salida es un .pptx finalizado, no un job de slide-imagen-más-texto que el narrador pueda leer. El narrador solo acepta jobs de create-pdf-slides o create-like-this.

¿Puedo exportar MP4 directamente desde la API?

No, no en 2026. Export MP4 es feature del Workspace UI implementada client-side con FFmpeg.wasm. El equivalente API es download-slides-pages-voices que devuelve ZIP de imágenes, audio y transcript — compones MP4 con ffmpeg si lo necesitas en la fábrica. Ver Paso 7.

¿Qué idiomas soporta?

22+ idiomas vía responseLanguage.

¿Coste en créditos?

Nano Banana: 10 (planificación) + 100/slide a 1K/2K (o 200/slide a 4K) + narración 210/página (10 texto + 200 audio). Export pages+voices gratis. Deck de 30 narrado a 2K ~9,310 créditos. Precios.

¿429 rate limits?

Backoff exponencial. 1s start, doblar a 60s. Tras 3 consecutivos, reduce concurrencia a la mitad. No polling más rápido que 20s.

¿Integración con Zapier / Make / n8n?

Sí — cualquier herramienta con HTTP autenticado. n8n popular para fábricas.

¿Cómo prevengo indexación pública?

API genera decks privados por defecto. Compartir es acción explícita.

¿Versiones 9:16 y 16:9 de la misma presentación?

Genera dos veces — aspectRatio: "9:16" y "16:9". Las slides están maquetadas por aspecto, croppear post-hoc se ve feo. Sí, dobla coste créditos — trade-off intencional por visuales limpios.

Conclusión

Fábrica de contenido = datos fuente estructurados + orquestador estable + endpoints API correctos. La falla más común es usar /api/v1/slides/generate (Fast PPT) e intentar narrar — esa ruta está cerrada. Usa create-pdf-slides o create-like-this, narra con generate-narration, exporta con download-slides-pages-voices, compón MP4 server-side con ffmpeg.

Lado manual: guía vocabulario y flujo creador.