Как пакетно генерировать 100 лексических колод через 2Slides API (плейбук контент-фабрики 2026)

Q: Почему нельзя добавить озвучку к задаче /api/v1/slides/generate?

Эндпоинт generate — это Fast PPT, шаблонный PPTX. Его выход — финализированный .pptx, а не задача с картинками-слайдами и текстом, которую читает генератор озвучки. Генератор озвучки явно принимает только задачи create-pdf-slides или create-like-this, которые порождают Nano Banana-задачи со структурированным контентом постранично.

Q: Как сгенерировать вертикальную (9:16) и горизонтальную (16:9) версии одной колоды?

Сгенерируйте дважды — один раз с aspectRatio: "9:16", другой с "16:9". Слайды верстаются под конкретное соотношение, поэтому пост-фактумная обрезка редко выглядит хорошо. Да, это удваивает стоимость в кредитах — это сознательный компромисс ради чистого визуала.

Когда ручной процесс уже отлажен — сгенерировать одну лексическую колоду, озвучить, экспортировать активы — следующее узкое место это объём. Языковая школа с 12 уровнями и 30 темами в неделю требует 360 колод в год. Faceless TikTok-канал с ежедневной публикацией — 365 колод плюс варианты пропорций. Контент-команда EdTech-компании — сотни колод по парам L1/L2.

360 колод вручную не построить. Нужна контент-фабрика.

Это руководство — практичный плейбук 2026 по пакетной генерации лексических (и любых других) колод через 2Slides API. Самое важное архитектурное решение, которое чаще всего ошибочно — выбор эндпоинта генерации.

Сначала выберите правильный эндпоинт (здесь чаще всего ломаются)

2Slides открывает по API два разных сценария генерации. Только один из них даёт колоды, которые потом можно озвучить.

Эндпоинт	Что выдаёт	Озвучка возможна?	Кредиты
`POST /api/v1/slides/generate`	Fast PPT — шаблонный PPTX. Требует `themeId` из библиотеки шаблонов.	нет. Эндпоинт озвучки явно отвергает такие задачи.	10 / страница
`POST /api/v1/slides/create-pdf-slides`	Nano Banana — слайды с генерируемыми картинками из текстового промпта. Тот же движок, что у Workspace.	да	10 (планирование) + 100 / слайд (1K/2K) или 200 / слайд (4K)
`POST /api/v1/slides/create-like-this`	Nano Banana — слайды с генерируемыми картинками, повторяющие референсное изображение.	да	то же

Для контент-фабрики с озвучкой и экспортируемым аудио используйте create-pdf-slides (или create-like-this, если есть референсный макет). Не используйте /api/v1/slides/generate — это эндпоинт Fast PPT, и озвучить его нельзя.

Если фабрике нужен только тихий PPTX (без аудио и видео), Fast PPT через /api/v1/slides/generate — самый дешёвый путь. Дальше плейбук исходит из озвученного процесса.

Архитектура одной диаграммой

[Источник]               [Оркестратор]                    [2Slides API]                   [Выходы]
    │                         │                                │                              │
 словарная   ──промпт──▶   очередь  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 таблица     (cron/скрипт)                                     │                              │
    │                         │                                │                              │
                           Опрос  ──GET──▶  /api/v1/jobs/{jobId} ◀────────────────────────────┘
                           каждые 20-30s   status: success                                    │
                                                              │                                ▼
                                                              │             [страницы PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode, ...) — только async
                                                              │
                                                           Опрос  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (бесплатно; возвращает ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Опционально) сборка MP4 на стороне клиента
                                                   через FFmpeg или в Workspace UI
                                                              │
                                                              ▼
                                                   [LMS / TikTok / рассылка / S3]

Источник → оркестратор → API → ZIP со страницами и голосами → доставка. Сборка MP4 опциональна и не является публичным API-эндпоинтом по состоянию на 2026 — это функция Workspace UI на FFmpeg.wasm в браузере. API-эквивалент — ZIP со страницами и голосами, который вы собираете в MP4 на сервере через ffmpeg, если фабрике нужно видео.

Шаг 1 — сначала спроектируйте схему источника

Самый высокорычажный шаг — определить структуру исходных данных до любого вызова API. Колоды из чистой схемы воспроизводимы; колоды из ситуативных промптов — нет.

Строка-источник для лексической колоды, которая масштабируется:

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # родной язык учащегося
target_l2: es          # изучаемый язык
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
generation:
  endpoint: create-pdf-slides
  aspect_ratio: "9:16"      # вертикальная для коротких видео
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # каталог в /tts_sample_voices
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Этот объект — единица работы. Всё остальное по конвейеру потребляет его.

Стройте схему там, где у вас уже есть инструменты: Google Sheet для нетехнических команд, Postgres-таблица для инженеров, CMS со структурированными полями для контент-команд. Не стройте в обычных Markdown-файлах — для пакетной автоматизации это плохо.

Шаг 2 — авторизация

Получите API-ключ на странице управления API. Формат:

sk-2slides-{64-character-hex-string}

Все запросы используют bearer-аутентификацию:

Authorization: Bearer sk-2slides-...

Пер-эндпоинтные лимиты документированы на 2slides.com/api.md. Для пакетного производства:

create-pdf-slides и create-like-this: проектируйте очередь под их лимиты конкурентности с экспоненциальным бэкоффом на 429
jobs/{id} (опрос): соблюдайте каденцию — 20–30s, не агрессивно
download-slides-pages-voices: бесплатно и быстрее, но тоже ограничено по rate-limit

Шаг 3 — отправьте задачу генерации Nano Banana

Лексические карточки лучше работают в async-режиме (генерация изображений на 30 карточек занимает 1–3 минуты).

curl -X POST "https://2slides.com/api/v1/slides/create-pdf-slides" \
  -H "Authorization: Bearer sk-2slides-..." \
  -H "Content-Type: application/json" \
  -d '{
    "userInput": "<ваш промпт-колода — см. шаг 4>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

В ответе будет jobId (UUID). Опрашивайте статус:

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

Каденция опроса: раз в 20–30 секунд. Не опрашивайте чаще — документация явно об этом предупреждает, агрессивный опрос — самая частая причина 429. Большинство колод собирается за 1–3 минуты.

Когда status: "success", изображения слайдов лежат на R2, и есть downloadUrl для PDF-сборки. Сами изображения слайдов вы позже скомпонуете с аудио.

Шаг 4 — стройте промпт-шаблоны, выдерживающие масштаб

Главное отличие шаткой фабрики от стабильной — промпт-шаблоны. Не пишите промпт на лету для каждой колоды. Определите шаблон под тип колоды и подставляйте значения.

Шаблон лексической колоды (userInput):

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.

Визуальный стиль управляется параметром designStyle (свой промпт) или оставляется по умолчанию («clean infographic, no photographs, balanced typography»). Храните промпты под версионированием в git. Когда промпт меняется, логируйте версию вместе с каждой сгенерированной колодой — так вы сможете коррелировать регрессии качества с изменениями промпта.

Шаг 5 — добавьте озвучку

Когда статус задачи генерации success, запускайте озвучку. Озвучка только async и работает на том же 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
  }'

Затем опрашивайте тот же /api/v1/jobs/{jobId}, пока message не сменится с «Voice narration generation in progress» на success.

Два паттерна голоса хорошо работают для лексических карточек:

mode: "single" с одним голосом — прямое чтение «слово + IPA + предложение»
mode: "multi" с двумя голосами — примеры разделяются между спикерами, идеально для глаголов и идиом

Каталог голосов опубликован в /tts_sample_voices/. Распространённые варианты — Puck, Aoede, Charon, Kore. Сверяйтесь с актуальной API-документацией, прежде чем фиксировать конкретный голос в продакшене.

Важно: один эндпоинт генерирует и текст голоса, и аудио. Не вызывайте отдельные «voice text» и «voice audio» эндпоинты — публичных API для этих шагов по отдельности нет. Настройте запрос озвучки один раз — API сделает оба шага.

Шаг 6 — экспорт страниц и голосов (бесплатно)

Когда озвучка завершена, заберите все активы одним 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 (валидна 1 час) на ZIP, содержащий:

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

Этот экспорт бесплатный — кредиты не расходуются. Загрузите ZIP и положите активы в собственное хранилище. Presigned-URL живёт 1 час.

Шаг 7 — (Опционально) собрать MP4 на стороне сервера

API 2Slides пока не предоставляет эндпоинт сборки MP4 — генерация MP4 живёт в Workspace UI через FFmpeg.wasm в браузере. Для контент-фабрики собирайте MP4 на сервере через ffmpeg:

# Для каждой страницы соберите клип (статичная картинка) + (голос).
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

# Соедините постраничные клипы в финальный MP4.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

Темп аудио на странице — то, что выдал генератор озвучки: обычно 5–12 секунд на слайд для лексики. Результат — тот же MP4, который пользователь скачал бы из Workspace UI, но собранный «безголово» в вашем конвейере.

Если нужны вертикальный (9:16) и горизонтальный (16:9) варианты одной колоды, чище всего сгенерировать колоду дважды в разных пропорциях на этапе генерации (aspectRatio: "9:16" против "16:9"). Постфактумная обрезка через FFmpeg часто даёт некрасивый результат, потому что слайды свёрстаны под конкретное соотношение сторон.

Шаг 8 — оркестратор

Минимальный оркестратор обрабатывает пять циклов:

# Псевдокод

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

    # 1. Сгенерировать слайды через Nano Banana endpoint
    job = post("/api/v1/slides/create-pdf-slides", body=build_payload(deck))
    deck_artifact = poll_until_complete(job.data.jobId)

    # 2. Озвучить (только 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. Экспорт ZIP со страницами и голосами (бесплатно)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Скачать и сложить активы в собственное хранилище
    download_to_s3(zip_url, deck.id)

    # 5. (Опционально) собрать MP4 через ffmpeg, потом раздать
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

Запускайте на воркер-машине с очередью. Для 100 колод в день одного воркера хватает. Для 1 000+ распараллеливайте на маленький пул — но пул должен соблюдать лимиты per-endpoint, а не просто число воркеров.

Шаг 9 — паттерны доставки

Слой доставки превращает артефакты в бизнес-ценность:

LMS: загружайте собранный MP4 в Canvas / Moodle / Blackboard / Google Classroom через их API
TikTok / Reels / Shorts: ставьте 9:16 MP4 в очередь планировщика (Buffer, Later, нативный планировщик), по одному в день
Рассылка: вшейте PDF-сборку (из downloadUrl исходной задачи генерации) как ссылку на скачивание в недельный выпуск
Лид-магнит / продажи: загрузите PDF в Stan Store / Gumroad; тизер-карусель ведёт трафик

Не изобретайте доставку. Используйте платформенные API и пусть оркестратор кладёт строку в ваш планировщик.

Математика стоимости (то, что планировать первым)

Для Nano Banana-колод с озвучкой кредиты копятся быстрее, чем у Fast PPT, что некоторые читатели могли видеть раньше. Математика на колоду из 30 карточек (1K/2K, с озвучкой):

Планирование: 10 кредитов
Генерация слайдов: 30 × 100 = 3 000 кредитов
Озвучка (текст + аудио): 30 × 210 = 6 300 кредитов
Экспорт страниц и голосов: 0 кредитов (бесплатно)
Итого: ~9 310 кредитов на одну озвученную колоду из 30 карточек

Без озвучки та же колода — ~3 010 кредитов. В 4K стоимость генерации удваивается: 30 × 200 = 6 000 → ~12 310 с озвучкой.

Для фабрики на 100 колод/мес: 100 × 9 310 = ~931 000 кредитов в месяц. Сравнивайте со страницей тарифов, чтобы выбрать тариф — и закладывайте 4K только когда выход уходит в контекст, который этого стоит (большие экраны, премиум-видео). Для TikTok/Reels-обзоров достаточно 1K или 2K.

Эксплуатационные паттерны, предотвращающие пожары

Идемпотентность

Каждая отправка колоды должна быть идемпотентной по deck_id. Если воркер падает посреди батча, перезапуск очереди не должен порождать дубли. Самый чистый паттерн: храните (deck_id, status) в строке БД и переводите состояния (pending → generating → narrating → exporting → composed → distributed).

Контроль качества

Не раздавайте автоматически. Перед публикацией в TikTok или Canvas прогоняйте машинно-читаемую проверку артефакта:

Число страниц совпадает с запрошенным
ZIP содержит ожидаемое число pages/page_NN.png и voices/page_NN.wav
Длительность аудио на странице — между 3 и 15 секундами (30-секундная карточка почти всегда означает «галлюцинированный длинный сценарий»)
transcript.txt непустой и содержит целевые слова

Для первых 50 батчей делайте выборочную ручную проверку 1 из 10. Именно в первых 50 проявляются системные проблемы промпта.

Версионирование

В каждом артефакте храните: версию промпт-шаблона, версию модели картинок (gemini-3-pro-image-preview против gemini-3.1-flash-image-preview), голос озвучки, таймстемп генерации. Когда модель улучшается или меняется промпт, можно перегенерировать только затронутые колоды.

Телеметрия по стоимости

Стоимость каждой колоды известна (см. математику выше). Отслеживайте кредиты на колоду. Когда расход неожиданно удваивается — что-то изменилось (плавающее число страниц, ретраи, переход на 4K). Найдите это раньше, чем счёт за кредиты застанет врасплох.

Обработка отказов

Падение задачи — норма: сетевая ошибка, загрузка модели, редкие 5xx. Один ретрай после бэкоффа. После двух подряд — отправляйте колоду в очередь needs_human. Не зацикливайтесь.

Build vs buy: когда вообще нужен API

API — правильный ответ, когда:

Вы делаете >10 колод в неделю
У вас структурированные исходные данные
Нужны озвученные MP4, которые вы соберёте на сервере и раздадите
Идёт интеграция с LMS, планировщиком или CMS
Нужна воспроизводимость с версионированием промптов

API — перебор, когда:

Вы делаете 1 колоду в неделю и каждый раз тонко настраиваете её визуально
Вы учащийся, который собирает колоды для себя (UI быстрее — и Workspace UI собирает MP4 за вас)
Вы преподаватель, делающий по одной колоде на урок (используйте Create Slides from File или Create Slides Like This и пропустите оркестрацию)

Часто задаваемые вопросы

Где взять API-ключ?

2slides.com/api. Ключи живут на вкладке управления API.

Почему нельзя добавить озвучку к задаче `/api/v1/slides/generate`?

Эндпоинт generate — это Fast PPT, шаблонный PPTX. Его выход — финализированный .pptx, а не задача с картинками-слайдами и текстом, которую читает генератор озвучки. Генератор озвучки явно принимает только задачи create-pdf-slides или create-like-this, которые порождают Nano Banana-задачи со структурированным контентом постранично.

Можно ли экспортировать MP4 прямо из API?

Нет, по состоянию на 2026. Экспорт MP4 — функция Workspace UI на FFmpeg.wasm. API-эквивалент — download-slides-pages-voices, возвращающий ZIP с изображениями, аудио и транскриптом. MP4 собирайте сами через ffmpeg, если он нужен в фабрике. См. шаг 7.

Какие языки поддерживает API для генерации?

22+, включая испанский, французский, немецкий, арабский, японский, корейский, хинди, вьетнамский, русский, польский, итальянский, португальский, индонезийский, тайский, турецкий и китайский (упрощённый/традиционный). Передавайте через responseLanguage.

Сколько стоит в кредитах?

Для Nano Banana-колод: 10 (планирование) + 100/слайд при 1K/2K (или 200/слайд при 4K) для генерации, плюс 210/страница (10 текст + 200 аудио) на озвучку. Экспорт страниц и голосов бесплатный. Озвученная колода из 30 карточек в 2K — ~9 310 кредитов. См. страницу тарифов и блок «математика стоимости» выше.

Как обрабатывать 429?

Экспоненциальный бэкофф. Старт 1с, удвоение до 60с. После трёх подряд 429 уменьшайте число одновременных воркеров вдвое. Не опрашивайте /api/v1/jobs/{id} чаще, чем раз в 20 секунд — это самая частая причина 429.

Можно ли интегрироваться с Zapier / Make / n8n?

Да — любой инструмент, умеющий делать аутентифицированные HTTP-запросы, заведёт 2Slides API. n8n особенно популярен в контент-фабриках, потому что нативно умеет опросы и очереди.

Как защитить сгенерированные колоды от публичной индексации?

Колоды, созданные через API, по умолчанию приватны для вашего аккаунта. Публичный шаринг — отдельное явное действие.

Как сгенерировать вертикальную (9:16) и горизонтальную (16:9) версии одной колоды?

Сгенерируйте дважды — один раз с aspectRatio: "9:16", другой с "16:9". Слайды верстаются под конкретное соотношение, поэтому пост-фактумная обрезка редко выглядит хорошо. Да, это удваивает стоимость в кредитах — это сознательный компромисс ради чистого визуала.

Главная мысль

Контент-фабрика — это структурированный источник + стабильный оркестратор + правильные эндпоинты. 2Slides API — третья часть, первые две — на вас. Самый частый провал — использование /api/v1/slides/generate (Fast PPT) и попытка озвучить — этот путь закрыт. Используйте create-pdf-slides или create-like-this, озвучивайте через generate-narration, экспортируйте download-slides-pages-voices и собирайте MP4 на сервере через ffmpeg.

Ручную сторону того же процесса см. в руководстве по карточкам лексики и руководстве для авторов. UI-паттерны там — те же паттерны, что вы автоматизируете API; понимание ручного процесса делает интеграцию по API намного быстрее.

С чего начать

Получите API-ключ на 2slides.com/api
Спроектируйте схему источника (см. шаг 1) и заведите 5–10 пробных колод
Реализуйте оркестратор: генерация → опрос → озвучка → опрос → экспорт ZIP
Прогоните 50 пробных батчей с ручной выборочной проверкой 1 из 10
Подключите доставку в LMS / соцсети / рассылку и поставьте на cron