Como gerar 100 baralhos de vocabulário em lote com a API 2Slides (manual da fábrica de conteúdo 2026)

Depois que você valida o fluxo manual — gerar um baralho de vocabulário, narrá-lo, exportar os ativos — o próximo gargalo é volume. Uma escola de idiomas com 12 níveis e 30 temas semanais precisa de 360 baralhos por ano. Um canal faceless do TikTok publicando diariamente precisa de 365 baralhos mais as variantes de proporção. Um time de conteúdo numa empresa de EdTech precisa de centenas de baralhos segmentados por pares L1/L2.

Você não constrói 360 baralhos à mão. Você constrói uma fábrica de conteúdo.

Este guia é o manual prático de 2026 para gerar baralhos de vocabulário em lote (e qualquer outro conteúdo de slides) com a API 2Slides. A decisão arquitetural mais importante — e a que mais comumente sai errada — é escolher o endpoint de geração certo.

Escolha o endpoint certo primeiro (é aqui que a maioria das fábricas quebra)

A 2Slides expõe dois fluxos distintos de geração via API. Apenas um deles produz baralhos que podem ser narrados em seguida.

Para uma fábrica de cards de vocabulário com narração e áudio exportável, use

(ou se você tiver um layout de referência). Não use — esse é o endpoint Fast PPT e você não pode adicionar narração a ele.

Se a sua fábrica só precisa de PPTX silencioso (sem áudio, sem vídeo), o Fast PPT via

é o caminho mais barato. O resto deste manual assume o fluxo com narração.

A arquitetura em um diagrama

[Dados de origem]        [Orquestrador]                  [API 2Slides]                    [Saídas]
    │                          │                               │                              │
 planilha de  ──prompt──▶  Fila de jobs  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 vocabulário  (Cron/script)                                    │                              │
    │                          │                               │                              │
                           Poll  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           a cada 20-30s   status: success                                    │
                                                              │                                ▼
                                                              │             [pages slides PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode, etc.) — apenas async
                                                              │
                                                           Poll  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (grátis; retorna ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Opcional) compor MP4 client-side
                                                   com FFmpeg, ou usar a UI do Workspace
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

Dados de origem → orquestrador → API → ZIP de pages + voices → distribuição. A composição de MP4 é opcional e não é um endpoint público da API em 2026 — é um recurso da UI do Workspace usando FFmpeg.wasm no navegador. O equivalente da API é o ZIP pages-and-voices, que você pode compor com

no servidor se precisar de MP4 na fábrica.

Passo 1 — Defina o schema da fonte primeiro

A jogada de maior alavancagem é definir o schema dos dados de origem antes de qualquer chamada de API. Baralhos construídos a partir de um schema limpo são reproduzíveis; baralhos construídos a partir de prompts ad-hoc não são.

Uma linha de origem de baralho de vocabulário que escala:

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # idioma nativo do aprendiz
target_l2: es          # idioma sendo aprendido
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" }
  # ... mais 27
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # vertical para revisão em short-form
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # veja /tts_sample_voices para o catálogo
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Esse objeto é a unidade de trabalho. Tudo a jusante o consome.

Construa o schema da fonte no que você já tem: uma Google Sheet para times não técnicos, uma tabela Postgres para times de engenharia, um CMS com campos estruturados para times de conteúdo. Evite construí-lo em arquivos Markdown puros — Markdown é bom para escrita humana, mas ruim para automação em lote.

Passo 2 — Autentique

Pegue uma chave de API na página de gerenciamento de API. O formato é:

sk-2slides-{string-hex-de-64-caracteres}

Todas as requisições usam bearer auth:

Authorization: Bearer sk-2slides-...

Os limites de taxa por endpoint estão documentados em 2slides.com/api.md. Para produção em lote:

• create-pdf-slides
  e
  create-like-this
  : projete sua fila em torno dos limites de concorrência deles com backoff exponencial em 429
• jobs/{id}
  (poll): respeite a cadência de polling abaixo — 20–30s, sem agressividade
• download-slides-pages-voices
  : grátis e mais rápido, mas ainda tem rate limit

Passo 3 — Submeta um job de geração Nano Banana

Cards de vocabulário funcionam melhor em modo async (a geração de imagem por slide leva 1–3 minutos para um baralho de 30 cards).

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

A resposta contém o

(um UUID). Faça polling até o término:

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

Cadência de polling: a cada 20–30 segundos. Não faça polling mais rápido — a documentação da API destaca isso explicitamente, e polling agressivo é a causa mais comum de 429s. A maioria dos baralhos termina em 1–3 minutos.

Quando

, o job tem imagens de slide armazenadas no R2 e uma para uma compilação em PDF. As próprias imagens dos slides são o que você depois combinará com áudio.

Passo 4 — Construa templates de prompt que sustentam a escala

A maior diferença entre uma fábrica instável e uma confiável são templates de prompt. Não escreva prompts em runtime por baralho. Defina um template por tipo de baralho e substitua valores.

Template de baralho de vocabulário (

):

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.

O estilo visual é controlado pelo parâmetro

(prompt customizado) ou deixado no default ("infográfico limpo, sem fotografias, tipografia equilibrada"). Mantenha os prompts versionados no git. Quando um prompt muda, registre a versão com cada baralho gerado para correlacionar regressões de qualidade com mudanças de prompt.

Passo 5 — Adicione narração

Uma vez que o job de geração esteja com

, dispare a narração. Narração é apenas async e opera no mesmo :

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

Depois faça polling no mesmo

até a mensagem transitar de "Voice narration generation in progress" para um estado de sucesso.

Dois padrões de voz funcionam bem para cards de vocabulário:

• mode: "single"
  com uma voz — leitura direta de palavra + IPA + frase
• mode: "multi"
  com duas vozes — frases de exemplo divididas entre falantes, ideal para verbos e expressões idiomáticas

O catálogo de vozes é publicado em

. Escolhas comuns incluem , , , . Confirme o suporte com a documentação da API mais recente antes de fixar uma voz específica em produção.

Importante: este único endpoint gera tanto o texto da voz quanto o áudio da voz. Não chame endpoints separados de "texto de voz" e "áudio de voz" — não existe API pública para esses passos independentes. Configure a requisição de narração uma vez e a API faz os dois.

Passo 6 — Exporte pages e voices (grátis)

Uma vez completa a narração, recupere todos os ativos em um único 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"
  }'

A resposta inclui uma

(válida por 1 hora) para um ZIP que contém:

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

Esta exportação é grátis — sem créditos consumidos. Baixe o ZIP e armazene os ativos no seu próprio object store. A URL pré-assinada expira em 1 hora.

Passo 7 — (Opcional) Componha MP4 server-side

A API 2Slides atualmente não expõe um endpoint de composição de MP4 — a geração de MP4 vive na UI do Workspace via FFmpeg.wasm no navegador. Para uma fábrica de conteúdo, componha MP4 server-side com

:

# Para cada página, monte um clipe de (imagem estática) + (áudio de 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

# Concatene todos os clipes por página no MP4 final.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

A cadência de áudio por página é o que o gerador de narração produziu — tipicamente 5–12 segundos por slide para cards de vocabulário. O resultado é o mesmo MP4 que um usuário baixaria da UI do Workspace, mas produzido headless no seu pipeline de fábrica.

Se você quer variantes vertical (9:16) e horizontal (16:9) do mesmo baralho, o caminho mais limpo é gerar o baralho duas vezes com aspect ratios diferentes na fase de geração de slides (

vs ). Cropping com FFmpeg depois do fato muitas vezes produz resultados feios porque os slides foram diagramados para um aspecto específico.

Passo 8 — Construa o orquestrador

Um orquestrador mínimo cuida de cinco loops:

# Pseudocódigo

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

    # 1. Gerar slides 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. Narrar (apenas 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 de pages + voices (grátis)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Baixar e armazenar ativos no seu object store
    download_to_s3(zip_url, deck.id)

    # 5. (Opcional) compor MP4 com ffmpeg, depois distribuir
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Rode isso em uma worker box com uma fila. Para 100 baralhos por dia, um worker é suficiente. Para 1.000+, distribua para um pequeno pool de workers — mas garanta que o pool respeite os limites de taxa de cada endpoint, não apenas a quantidade de workers.

Passo 9 — Padrões de distribuição

A camada de distribuição transforma artefatos em valor de negócio:

• LMS: faça upload do MP4 composto para Canvas / Moodle / Blackboard / Google Classroom via suas respectivas APIs
• TikTok / Reels / Shorts: enfileire MP4 9:16 numa ferramenta de postagem (Buffer, Later, scheduler nativo), um por dia
• Newsletter: incorpore a compilação PDF (da
  downloadUrl
  do job de geração original) como link de download na edição semanal
• Vendas / lead magnet: faça upload do PDF para uma página Stan Store / Gumroad; o teaser do carousel direciona tráfego

Não tente inventar a distribuição. Use as APIs nativas das plataformas e deixe seu orquestrador soltar uma linha no seu agendador.

Matemática de custo (a parte para planejar primeiro)

Para baralhos Nano Banana com narração, os créditos somam mais rápido do que o pricing do Fast PPT que alguns leitores podem ter visto antes. A matemática por baralho de 30 cards (resolução 1K/2K, com narração):

• Planejamento: 10 créditos
• Geração de slides: 30 × 100 = 3.000 créditos
• Narração (texto + áudio): 30 × 210 = 6.300 créditos
• Exportação pages + voices: 0 créditos (grátis)
• Total: ~9.310 créditos por baralho narrado de 30 cards

Sem narração, o mesmo baralho fica em ~3.010 créditos. Em resolução 4K, dobre a porção de geração de slides: 30 × 200 = 6.000 → ~12.310 créditos com narração.

Para uma fábrica de 100 baralhos/mês: 100 × 9.310 = ~931.000 créditos/mês. Compare com a página de pricing para escolher um tier — e reserve orçamento para 4K apenas quando a saída for para um contexto que se beneficia disso (telas grandes, vídeo premium). Para vídeos de revisão no TikTok / Reels, 1K ou 2K é suficiente.

Padrões operacionais que evitam incêndios

Idempotência

Toda submissão de baralho deve ser idempotente em

. Se seu worker cair no meio do batch, reiniciar a fila não pode produzir baralhos duplicados. O padrão mais limpo: armazenar em uma linha de banco; transicionar estados ().

Quality gates

Não distribua automaticamente. Antes de enviar para o TikTok ou Canvas, rode um quality check legível por máquina no artefato:

• Contagem de páginas bate com a contagem solicitada
• ZIP contém o número esperado de arquivos
  pages/page_NN.png
  e
  voices/page_NN.wav
• A duração do áudio por página está entre 3 e 15 segundos (um card de 30 segundos quase sempre significa um script alucinado e longo)
• transcript.txt
  é não-vazio e contém as palavras-alvo

Para os primeiros 50 batches, faça também uma inspeção manual de 1 em cada 10 baralhos. Os primeiros 50 batches são onde problemas sistêmicos de prompt aparecem.

Versionamento

Todo artefato armazena: versão do template de prompt, versão do modelo de imagem (

vs ), voz da narração, timestamp de geração. Quando o modelo melhorar ou um prompt mudar, você pode rerodar apenas os baralhos afetados.

Telemetria de custo

Cada baralho tem um custo de crédito conhecido (veja a matemática acima). Monitore os créditos consumidos por baralho. Quando o uso de créditos por baralho dobra inesperadamente, algo mudou (drift de contagem de páginas, retries, mudou para 4K). Encontre antes que a conta de créditos te pegue de surpresa.

Tratamento de falhas

Um job falho é normal — falha de rede, carga do modelo, raro 5xx. Tente novamente uma vez após backoff. Após duas falhas, empurre o baralho para uma fila

. Não fique em loop infinito.

Build vs buy: quando usar a API

A API é a resposta certa quando:

• Você produz >10 baralhos/semana
• Você tem dados de origem estruturados
• Você precisa de MP4s narrados que vai compor server-side e distribuir
• Você integra com um LMS, scheduler ou CMS
• Você quer reprodutibilidade sob versionamento de prompt

A API é exagero quando:

• Você produz 1 baralho por semana e ajusta visualmente cada vez
• Você é um aprendiz construindo baralhos para estudo pessoal (a UI é mais rápida — e a UI do Workspace também faz a composição do MP4 para você)
• Você é um professor construindo um baralho por aula (use Create Slides from File ou Create Slides Like This e pule a orquestração)

Perguntas frequentes

Onde pego uma chave de API?

2slides.com/api. As chaves vivem na aba de gerenciamento de API.

Por que não posso adicionar narração a um job

/api/v1/slides/generate

?

O endpoint

é Fast PPT — PPTX baseado em template. Sua saída é um arquivo .pptx finalizado, não um job de imagem-de-slide-mais-texto que o gerador de narração consegue ler. O gerador de narração só aceita explicitamente jobs de ou , que produzem jobs de slides nano banana com conteúdo estruturado por página.

Posso exportar MP4 diretamente da API?

Não, não em 2026. A exportação de MP4 é um recurso da UI do Workspace implementado client-side com FFmpeg.wasm. O equivalente da API é

, que retorna um ZIP de imagens de slide, arquivos de áudio e uma transcrição — você compõe o MP4 com se precisar dele em um pipeline de fábrica de conteúdo. Veja Passo 7.

Quais idiomas a API suporta para geração?

Mais de 22 idiomas, incluindo espanhol, francês, alemão, árabe, japonês, coreano, hindi, vietnamita, russo, polonês, italiano, português, indonésio, tailandês, turco e chinês (simplificado/tradicional). Passe via

.

Qual o custo em créditos?

Para baralhos Nano Banana: 10 (planejamento) + 100/slide em 1K/2K (ou 200/slide em 4K) para geração de slides, mais 210/página (10 texto + 200 áudio) para narração. Exportação de pages + voices é grátis. Um baralho narrado de 30 cards em 2K é ~9.310 créditos. Veja a página de pricing e a seção de matemática de custo acima.

Como lido com rate limits 429?

Backoff exponencial. Comece em 1s, dobre até 60s. Após três 429s consecutivos, reduza pela metade a contagem de workers concorrentes. Não faça polling em

mais rápido do que a cada 20 segundos — essa é a causa mais comum de 429.

Posso integrar com Zapier / Make / n8n?

Sim — qualquer ferramenta que faça requisições HTTP autenticadas pode acionar a API 2Slides. n8n em particular é popular para fábricas de conteúdo porque trata os padrões de polling e fila nativamente.

Como evito que baralhos gerados sejam indexados publicamente?

Baralhos gerados via API são privados à sua conta por padrão. O compartilhamento público é uma ação separada e explícita.

Como gero versões vertical (9:16) e horizontal (16:9) do mesmo baralho?

Gere o baralho duas vezes — uma vez com

e uma vez com . Os slides são diagramados por aspect ratio no momento da geração, então cropping post-hoc raramente fica bom. Sim, isso significa dobrar o custo de créditos; é um trade-off deliberado por visuais limpos.

A conclusão

Uma fábrica de conteúdo é dados de origem estruturados + um orquestrador estável + os endpoints de API certos. A API 2Slides é a terceira peça; você é responsável pelas duas primeiras. A falha de fábrica mais comum é usar

(Fast PPT) e depois tentar narrá-lo — esse caminho está fechado. Use ou , narre com , exporte com e componha MP4 server-side com .

Para o lado manual do mesmo fluxo, veja o guia de cards de vocabulário e o guia de fluxo de trabalho do criador. Os padrões de UI lá são os mesmos padrões que você está automatizando com a API; entender o fluxo manual primeiro torna a integração da API muito mais rápida.