2Slides API로 100개 단어 덱 일괄 생성하기 (2026 콘텐츠 팩토리 플레이북)

수동 워크플로우 — 단어 덱 하나 생성, 내레이션 추가, 자산 내보내기 — 를 검증한 후의 다음 병목은 볼륨입니다. 12개 레벨과 30개 주간 테마를 갖춘 어학원은 연 360개 덱이 필요합니다. 매일 게시하는 페이스리스 TikTok 채널은 연 365개 덱과 비율 변형이 필요합니다. EdTech 회사의 콘텐츠 팀은 L1/L2 쌍별로 분할된 수백 개 덱이 필요합니다.

360개 덱은 수작업으로 만들지 않습니다. 콘텐츠 팩토리를 만듭니다.

이 가이드는 2Slides API로 단어 덱(과 모든 슬라이드 콘텐츠)을 일괄 생성하기 위한 2026년 실전 플레이북입니다. 가장 중요한 아키텍처 결정 — 그리고 가장 자주 잘못 내려지는 결정 — 은 올바른 생성 엔드포인트를 선택하는 것입니다.

먼저 올바른 엔드포인트 선택 (대부분의 팩토리가 여기서 망가집니다)

2Slides는 API를 통해 두 가지 별개의 생성 흐름을 노출합니다. 그중 하나만 이후에 내레이션을 추가할 수 있는 덱을 생성합니다.

내레이션과 내보낼 수 있는 오디오가 있는 단어 카드 콘텐츠 팩토리에는

(또는 참조 레이아웃이 있다면

create-like-this

)를 사용하세요. 는 사용하지 마세요 — Fast PPT 엔드포인트이며 내레이션을 추가할 수 없습니다.

팩토리가 무음 PPTX(오디오 없음, 영상 없음)만 필요하다면

를 통한 Fast PPT가 가장 저렴한 경로입니다. 이 플레이북의 나머지는 내레이션 워크플로우를 가정합니다.

한 다이어그램으로 보는 아키텍처

[원본 데이터]            [오케스트레이터]                 [2Slides API]                    [출력]
    │                          │                               │                              │
 단어             ──프롬프트──▶  작업 큐  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 스프레드시트 (Cron/스크립트)                                  │                              │
    │                          │                               │                              │
                           폴링  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           20-30초마다    status: success                                    │
                                                              │                                ▼
                                                              │             [pages 슬라이드 PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode 등) — async only
                                                              │
                                                           폴링  ──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 → pages + voices ZIP → 배포. MP4 합성은 선택이며 2026년 현재 공개 API 엔드포인트가 아닙니다 — 브라우저에서 FFmpeg.wasm을 사용하는 Workspace UI 기능입니다. API 등가물은 pages-and-voices ZIP이며, 팩토리에서 MP4가 필요하다면 서버 측에서

로 합성할 수 있습니다.

Step 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 more
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 파일에 만들지 마세요 — Markdown은 사람의 글쓰기에는 좋지만 일괄 자동화에는 나쁩니다.

Step 2 — 인증

API 관리 페이지에서 API 키를 받으세요. 형식:

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

모든 요청은 베어러 인증을 사용합니다.

Authorization: Bearer sk-2slides-...

엔드포인트별 속도 제한은 2slides.com/api.md에 문서화되어 있습니다. 일괄 생산을 위해:

• create-pdf-slides
  와
  create-like-this
  : 동시성 한도 주변에 큐를 설계하고 429에 지수 백오프 적용
• jobs/{id}
  (폴링): 아래 폴링 케이던스를 존중 — 20~30초, 공격적이지 않게
• download-slides-pages-voices
  : 무료이며 더 빠르지만 여전히 속도 제한이 있음

Step 3 — Nano Banana 생성 작업 제출

단어 카드는 비동기 모드에서 가장 잘 작동합니다(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": "<your deck-shaped prompt — see Step 4>",
    "responseLanguage": "en",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "page": 30,
    "contentDetail": "concise",
    "mode": "async"
  }'

응답에는

(UUID)가 포함됩니다. 완료를 폴링하세요.

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

폴링 케이던스: 20~30초마다. 더 빠르게 폴링하지 마세요 — API 문서가 명시적으로 언급하며, 공격적 폴링이 429의 가장 흔한 원인입니다. 대부분의 덱은 1~3분 안에 완료됩니다.

일 때, 작업의 슬라이드 이미지가 R2에 저장되고 PDF 컴파일에 대한 이 있습니다. 슬라이드 이미지가 나중에 오디오와 결합할 것입니다.

Step 4 — 규모에서도 견디는 프롬프트 템플릿 만들기

흔들리는 팩토리와 신뢰할 수 있는 팩토리의 가장 큰 차이는 프롬프트 템플릿입니다. 덱마다 런타임에 프롬프트를 작성하지 마세요. 덱 유형별로 템플릿을 정의하고 값을 대체하세요.

단어 덱 템플릿 (

):

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.

시각 스타일은

매개변수(사용자 정의 프롬프트)로 제어하거나 기본값("clean infographic, no photographs, balanced typography")으로 둡니다. 프롬프트를 git에 버전 관리하세요. 프롬프트가 변경될 때 생성된 각 덱과 함께 버전을 로깅해 품질 회귀를 프롬프트 변경과 상관시킬 수 있게 하세요.

Step 5 — 내레이션 추가

생성 작업이

가 되면 내레이션을 시작합니다. 내레이션은 비동기 전용이며 같은 에 작용합니다.

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

그런 다음 같은

를 메시지가 "Voice narration generation in progress"에서 성공 상태로 전환될 때까지 폴링하세요.

단어 카드에 잘 작동하는 두 가지 음성 패턴:

• 음성 하나로
  mode: "single"
  — 단순한 단어 + IPA + 문장 낭독
• 두 음성으로
  mode: "multi"
  — 화자 사이에 분할된 예문, 동사와 관용 표현에 이상적

음성 카탈로그는

에 게시되어 있습니다. 일반적인 선택은 , , , 입니다. 프로덕션에서 특정 음성을 고정하기 전에 최신 API 문서로 지원을 확인하세요.

중요: 이 단일 엔드포인트가 음성 텍스트와 음성 오디오를 모두 생성합니다. "음성 텍스트"와 "음성 오디오"의 별도 엔드포인트를 호출하지 마세요 — 그 단계들에 대한 독립적인 공개 API가 없습니다. 내레이션 요청을 한 번 구성하면 API가 둘 다 처리합니다.

Step 6 — pages와 voices 내보내기 (무료)

내레이션이 완료되면 모든 자산을 단일 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"
  }'

응답에는 다음을 포함하는 ZIP에 대한

(1시간 유효)이 포함됩니다.

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

이 내보내기는 무료입니다 — 크레딧 소비 없음. ZIP을 다운로드하고 자체 객체 저장소에 자산을 저장하세요. 사전 서명된 URL은 1시간 후 만료됩니다.

Step 7 — (선택) 서버 측 MP4 합성

2Slides API는 현재 MP4 합성 엔드포인트를 노출하지 않습니다 — MP4 생성은 브라우저의 FFmpeg.wasm을 통해 Workspace UI에 있습니다. 콘텐츠 팩토리의 경우

로 서버 측에서 MP4를 합성하세요.

# 각 페이지에 대해 (이미지 정지) + (음성 오디오) 클립 생성.
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초. 결과는 사용자가 Workspace UI에서 다운로드할 수 있는 MP4와 같지만 팩토리 파이프라인에서 헤드리스로 생성됩니다.

같은 덱의 세로(9:16)와 가로(16:9) 변형을 원한다면 가장 깔끔한 경로는 슬라이드 생성 단계에서 다른 종횡비로 두 번 덱을 생성하는 것입니다(

vs ). 사후 FFmpeg 자르기는 슬라이드가 특정 종횡비를 위해 배치되었기 때문에 종종 보기 흉한 결과를 낳습니다.

Step 8 — 오케스트레이터 만들기

최소 오케스트레이터는 다섯 가지 루프를 처리합니다.

# Pseudocode

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

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

    # 2. Narrate (async only)
    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. Export pages + voices ZIP (free)
    zip_url = post("/api/v1/slides/download-slides-pages-voices",
                   body={"jobId": deck_artifact.id})

    # 4. Download and store assets in your object store
    download_to_s3(zip_url, deck.id)

    # 5. (Optional) compose MP4 with ffmpeg, then distribute
    if deck.distribution.social:
        compose_mp4(deck.id)
        distribute(deck)

큐가 있는 워커 박스에서 실행하세요. 하루 100개 덱이면 한 워커로 충분합니다. 1,000개 이상이면 작은 워커 풀로 팬아웃하되 — 풀이 워커 수가 아닌 각 API 엔드포인트의 속도 제한을 존중하도록 하세요.

Step 9 — 배포 패턴

배포 레이어가 산출물을 비즈니스 가치로 바꿉니다.

• LMS: 합성된 MP4를 각 API를 통해 Canvas / Moodle / Blackboard / Google Classroom에 업로드
• TikTok / Reels / Shorts: 9:16 MP4를 게시 도구(Buffer, Later, 네이티브 스케줄러)에 큐, 일일 한 개
• 뉴스레터: 원본 생성 작업의
  downloadUrl
  에서 PDF 컴파일을 주간 호의 다운로드 링크로 임베드
• 세일즈 / 리드 마그넷: PDF를 Stan Store / Gumroad 페이지에 업로드; 캐러셀 티저가 트래픽을 유도

배포를 발명하려고 하지 마세요. 플랫폼 네이티브 API를 사용하고 오케스트레이터가 스케줄러에 행을 떨어뜨리도록 하세요.

비용 계산 (먼저 계획해야 할 부분)

내레이션이 있는 Nano Banana 덱의 경우, 일부 독자가 이전에 본 Fast PPT 가격보다 크레딧이 더 빠르게 누적됩니다. 30카드 덱당 계산(1K/2K 해상도, 내레이션 포함):

• 기획: 10 크레딧
• 슬라이드 생성: 30 × 100 = 3,000 크레딧
• 내레이션 (텍스트 + 오디오): 30 × 210 = 6,300 크레딧
• pages + voices 내보내기: 0 크레딧 (무료)
• 합계: 내레이션 포함 30카드 덱당 약 9,310 크레딧

내레이션 없이는 같은 덱이 약 3,010 크레딧입니다. 4K 해상도에서는 슬라이드 생성 부분이 두 배가 됩니다: 30 × 200 = 6,000 → 내레이션 포함 약 12,310 크레딧.

월 100덱 팩토리: 100 × 9,310 = 약 931,000 크레딧/월. 가격 페이지와 비교해 등급을 선택하세요 — 그리고 4K는 결과물이 그것에 이익을 보는 맥락(대형 화면, 프리미엄 영상)으로 갈 때만 예산을 잡으세요. TikTok / Reels 복습 영상에는 1K나 2K가 충분합니다.

화재를 막는 운영 패턴

멱등성

모든 덱 제출은

에 대해 멱등이어야 합니다. 워커가 일괄 작업 도중 충돌하더라도 큐 재시작이 중복 덱을 생성해서는 안 됩니다. 가장 깔끔한 패턴: 데이터베이스 행에 를 저장하고 상태를 전환합니다().

품질 게이트

자동 배포하지 마세요. TikTok이나 Canvas에 푸시하기 전에 산출물에 대해 기계 판독 가능 품질 검사를 실행하세요.

• 페이지 수가 요청한 수와 일치
• ZIP에 예상한 수의
  pages/page_NN.png
  와
  voices/page_NN.wav
  파일 포함
• 페이지당 오디오 길이가 3~15초 사이 (30초짜리 카드는 거의 항상 환각된 긴 스크립트를 의미)
• transcript.txt
  가 비어 있지 않고 목표 단어를 포함

처음 50개 배치는 또한 10개 중 1개의 수동 점검도 하세요. 처음 50개 배치가 시스템적 프롬프트 문제가 표면화되는 곳입니다.

버전 관리

모든 산출물은 다음을 저장합니다: 프롬프트 템플릿 버전, 이미지 모델 버전(

vs ), 내레이션 음성, 생성 타임스탬프. 모델이 개선되거나 프롬프트가 변경되면 영향받은 덱만 다시 실행할 수 있습니다.

비용 텔레메트리

각 덱은 알려진 크레딧 비용이 있습니다(위 계산 참고). 덱당 소비된 크레딧을 추적하세요. 덱당 크레딧 사용량이 예기치 않게 두 배가 되면 무언가 변경되었습니다(페이지 수 드리프트, 재시도, 4K로 전환). 크레딧 청구서가 당신을 놀라게 하기 전에 찾으세요.

실패 처리

실패한 작업은 정상입니다 — 네트워크 깜박임, 모델 부하, 드문 5xx. 백오프 후 한 번 재시도. 두 번 실패한 후 덱을

큐에 푸시하세요. 무한 루프를 돌지 마세요.

빌드 vs 구매: 언제 API를 사용할 것인가

API가 옳은 답은 다음과 같을 때입니다.

• 주당 10개 이상 덱을 생성
• 구조화된 원본 데이터가 있음
• 서버 측에서 합성하고 배포할 내레이션 MP4가 필요
• LMS, 스케줄러, CMS와 통합
• 프롬프트 버전 관리에서 재현성을 원함

API가 과한 경우:

• 주당 1개 덱을 생성하고 매번 시각적으로 조정 (UI가 더 빠르며 — Workspace UI도 MP4 합성을 처리)
• 개인 학습용 덱을 만드는 학습자
• 수업당 1개 덱을 만드는 교사 (Create Slides from File이나 Create Slides Like This 사용)

자주 묻는 질문

API 키는 어디서 받나요?

2slides.com/api. 키는 API 관리 탭에 있습니다.

/api/v1/slides/generate

작업에 내레이션을 추가할 수 없는 이유는?

엔드포인트는 Fast PPT — 템플릿 기반 PPTX입니다. 출력은 완성된 .pptx 파일이지 내레이션 생성기가 읽을 수 있는 슬라이드 이미지 + 텍스트 작업이 아닙니다. 내레이션 생성기는 나 에서 만든 작업만 명시적으로 받아들이며, 이는 페이지별 구조화된 콘텐츠가 있는 nano banana 슬라이드 작업을 생성합니다.

API에서 직접 MP4를 내보낼 수 있나요?

아니요, 2026년 현재. MP4 내보내기는 클라이언트 측에서 FFmpeg.wasm으로 구현되는 Workspace UI 기능입니다. API 등가물은 슬라이드 이미지·오디오 파일·전사를 반환하는 ZIP인

입니다 — 콘텐츠 팩토리 파이프라인에서 필요하면 로 직접 MP4를 합성하세요. Step 7 참고.

API가 생성에 어떤 언어를 지원하나요?

스페인어, 프랑스어, 독일어, 아랍어, 일본어, 한국어, 힌디어, 베트남어, 러시아어, 폴란드어, 이탈리아어, 포르투갈어, 인도네시아어, 태국어, 터키어, 중국어(간체/번체)를 포함한 22개 이상의 언어.

로 전달.

크레딧 비용은?

Nano Banana 덱: 슬라이드 생성에 10 (기획) + 100/슬라이드 (1K/2K) 또는 200/슬라이드 (4K), 내레이션에 210/페이지 (10 텍스트 + 200 오디오). pages + voices 내보내기는 무료. 2K에서 30카드 내레이션 덱은 약 9,310 크레딧. 가격 페이지와 위 비용 계산 섹션 참고.

429 속도 제한은 어떻게 처리하나요?

지수 백오프. 1초에서 시작해 60초까지 두 배. 연속 3번의 429 후 동시 워커 수를 절반으로 줄이세요.

를 20초보다 빠르게 폴링하지 마세요 — 이것이 429의 가장 흔한 원인입니다.

Zapier / Make / n8n과 통합할 수 있나요?

네 — 인증된 HTTP 요청을 만들 수 있는 어떤 도구든 2Slides API를 구동할 수 있습니다. 특히 n8n은 폴링과 큐 패턴을 네이티브로 처리하기 때문에 콘텐츠 팩토리에서 인기 있습니다.

생성된 덱이 공개적으로 색인되지 않게 하려면?

API를 통해 생성된 덱은 기본적으로 계정에 비공개입니다. 공개 공유는 별개의 명시적 동작입니다.

같은 덱의 세로(9:16)와 가로(16:9) 버전을 어떻게 생성하나요?

덱을 두 번 생성 — 한 번은

, 다른 한 번은 . 슬라이드는 생성 시 종횡비별로 배치되므로 사후 자르기는 좀처럼 보기 좋지 않습니다. 네, 이는 크레딧 비용이 두 배가 됨을 의미합니다 — 깨끗한 시각 자료를 위한 의도적인 트레이드오프입니다.

결론

콘텐츠 팩토리는 구조화된 원본 데이터 + 안정된 오케스트레이터 + 올바른 API 엔드포인트입니다. 2Slides API는 세 번째 조각이고, 처음 두 가지는 당신의 책임입니다. 가장 흔한 팩토리 실패는

(Fast PPT)를 사용한 다음 내레이션을 추가하려는 것입니다 — 그 경로는 닫혀 있습니다. 대신 나 를 사용하고, 으로 내레이션을 추가하고, 로 내보내고, 서버 측에서 로 MP4를 합성하세요.

같은 워크플로우의 수동 측면은 단어 카드 가이드와 크리에이터 워크플로우 가이드를 참고하세요. 거기 있는 UI 패턴은 API로 자동화하는 것과 같은 패턴입니다. 수동 흐름을 먼저 이해하면 API 통합이 훨씬 빠릅니다.