Cách tạo hàng loạt 100 bộ slide từ vựng với API 2Slides (Playbook nhà máy nội dung 2026)

Khi đã xác thực quy trình thủ công — tạo một bộ slide từ vựng, thuyết minh, xuất tài sản — nút thắt tiếp theo là khối lượng. Một trường ngôn ngữ với 12 cấp độ và 30 chủ đề hàng tuần cần 360 bộ slide một năm. Một kênh TikTok faceless đăng hàng ngày cần 365 bộ slide cộng các biến thể tỷ lệ khung hình. Một đội ngũ nội dung tại công ty EdTech cần hàng trăm bộ slide phân đoạn theo cặp L1/L2.

Bạn không xây 360 bộ slide bằng tay. Bạn xây nhà máy nội dung.

Hướng dẫn này là playbook thực tế 2026 để tạo hàng loạt bộ slide từ vựng (và bất kỳ nội dung slide nào khác) với API 2Slides. Quyết định kiến trúc quan trọng nhất — và cái thường bị làm sai — là chọn endpoint tạo phù hợp.

Chọn endpoint phù hợp trước (đây là nơi hầu hết nhà máy đổ vỡ)

2Slides phơi bày hai luồng tạo riêng biệt qua API. Chỉ một trong số chúng tạo bộ slide có thể được thuyết minh sau đó.

Cho nhà máy nội dung thẻ từ vựng có thuyết minh và âm thanh xuất được, hãy dùng

(hoặc

create-like-this

nếu bạn có bố cục tham chiếu). Đừng dùng — đó là endpoint Fast PPT và bạn không thể thêm thuyết minh.

Nếu nhà máy của bạn chỉ cần PPTX im lặng (không âm thanh, không video), Fast PPT qua

là con đường rẻ nhất. Phần còn lại của playbook này giả định quy trình có thuyết minh.

Kiến trúc trong một sơ đồ

[Source data]            [Orchestrator]                   [2Slides API]                    [Outputs]
    │                          │                               │                              │
 vocabulary  ──prompt──▶  Job queue  ──POST──▶  /api/v1/slides/create-pdf-slides ──▶   jobId (UUID)
 spreadsheet (Cron/script)                                     │                              │
    │                          │                               │                              │
                           Poll  ──GET──▶  /api/v1/jobs/{jobId} ◀─────────────────────────────┘
                           every 20-30s    status: success                                    │
                                                              │                                ▼
                                                              │             [pages slides PNG · downloadUrl PDF]
                                                              │
                                                              ▶  POST /api/v1/slides/generate-narration
                                                              │  (jobId, voice, mode, etc.) — async only
                                                              │
                                                           Poll  ──GET──▶  /api/v1/jobs/{jobId}
                                                           message: "Voice narration generation in progress" → success
                                                              │
                                                              ▶  POST /api/v1/slides/download-slides-pages-voices
                                                              │  (free; returns ZIP)
                                                              ▼
                                                  pages/*.png + voices/*.{wav,mp3} + transcript.txt
                                                              │
                                                              ▼
                                                   (Optional) compose MP4 client-side
                                                   with FFmpeg, or use the Workspace UI
                                                              │
                                                              ▼
                                                   [LMS / TikTok / newsletter / S3]

Dữ liệu nguồn → orchestrator → API → ZIP của pages + voices → phân phối. Tổng hợp MP4 là tùy chọn và không phải endpoint API công khai từ 2026 — đó là tính năng UI Workspace dùng FFmpeg.wasm trong trình duyệt. Tương đương API là ZIP pages-and-voices, mà bạn có thể tổng hợp với

phía server nếu bạn cần MP4 trong nhà máy.

Bước 1 — Thiết kế schema nguồn trước

Động thái có đòn bẩy cao nhất là xác định schema dữ liệu nguồn trước bất kỳ lệnh gọi API nào. Bộ slide xây từ schema sạch là tái lập được; bộ slide xây từ prompt tùy biến thì không.

Một hàng nguồn bộ slide từ vựng mở rộng được:

deck_id: vocab-b1-travel-2026-w14
source_l1: en          # learner's native language
target_l2: es          # language being learned
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"      # vertical for short-form review
  resolution: "2K"
  page_count: 30
  content_detail: "concise"
narration:
  enabled: true
  voice: "Puck"             # see /tts_sample_voices for the catalog
  mode: "single"
distribution:
  social: [tiktok, reels, shorts]
  newsletter: monday-2026-w14

Đối tượng đó là đơn vị công việc. Mọi thứ phía sau tiêu thụ nó.

Xây schema nguồn trong bất cứ thứ gì bạn đã có: Google Sheet cho nhóm phi kỹ thuật, bảng Postgres cho nhóm kỹ thuật, CMS với trường có cấu trúc cho nhóm nội dung. Tránh xây trong tệp Markdown thuần — Markdown ổn cho viết người nhưng tệ cho tự động hóa hàng loạt.

Bước 2 — Xác thực

Lấy API key từ trang quản lý API. Định dạng là:

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

Tất cả request dùng bearer auth:

Authorization: Bearer sk-2slides-...

Giới hạn tỷ lệ theo endpoint được tài liệu hóa tại 2slides.com/api.md. Cho sản xuất hàng loạt:

• create-pdf-slides
  và
  create-like-this
  : thiết kế hàng đợi quanh giới hạn đồng thời với exponential backoff trên 429
• jobs/{id}
  (poll): tôn trọng nhịp poll bên dưới — 20–30s, không hung hăng
• download-slides-pages-voices
  : miễn phí và nhanh hơn, nhưng vẫn có giới hạn tỷ lệ

Bước 3 — Gửi job tạo Nano Banana

Thẻ từ vựng hoạt động tốt nhất ở chế độ async (tạo hình ảnh từng slide mất 1–3 phút cho bộ 30 thẻ).

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

Phản hồi chứa

(UUID). Poll cho hoàn thành:

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

Nhịp poll: mỗi 20–30 giây. Đừng poll nhanh hơn — tài liệu API nêu rõ điều này, và poll hung hăng là nguyên nhân phổ biến nhất của 429. Hầu hết bộ slide hoàn thành trong 1–3 phút.

Khi

, job có hình ảnh slide lưu trên R2 và cho bản tổng hợp PDF. Bản thân hình ảnh slide là điều bạn sẽ kết hợp với âm thanh sau đó.

Bước 4 — Xây template prompt giữ vững ở quy mô

Khác biệt lớn nhất giữa nhà máy không ổn định và đáng tin cậy là template prompt. Đừng viết prompt khi runtime mỗi bộ slide. Định nghĩa template cho mỗi loại bộ slide và thay thế giá trị.

Template bộ slide từ vựng (

):

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.

Phong cách trực quan được điều khiển bởi tham số

(prompt tùy chỉnh) hoặc để cho mặc định ("clean infographic, no photographs, balanced typography"). Giữ prompt phiên bản hóa trong git. Khi prompt thay đổi, ghi phiên bản với mỗi bộ slide tạo ra để bạn có thể tương quan suy giảm chất lượng với thay đổi prompt.

Bước 5 — Thêm thuyết minh

Khi job tạo là

, khởi động thuyết minh. Thuyết minh chỉ async và hoạt động trên cùng :

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

Sau đó poll cùng

cho đến khi thông báo chuyển từ "Voice narration generation in progress" sang trạng thái thành công.

Hai mẫu giọng hoạt động tốt cho thẻ từ vựng:

• mode: "single"
  với một giọng — đọc thẳng từ + IPA + câu
• mode: "multi"
  với hai giọng — câu ví dụ chia giữa người nói, lý tưởng cho động từ và thành ngữ

Danh mục giọng được công bố tại

. Lựa chọn phổ biến bao gồm , , , . Xác nhận hỗ trợ với tài liệu API mới nhất trước khi cố định giọng cụ thể trong sản xuất.

Quan trọng: endpoint duy nhất này tạo cả văn bản giọng và âm thanh giọng. Đừng gọi các endpoint "voice text" và "voice audio" riêng — không có API công khai cho các bước đó độc lập. Cấu hình request thuyết minh một lần và API làm cả hai.

Bước 6 — Xuất pages và voices (miễn phí)

Khi thuyết minh hoàn thành, lấy tất cả tài sản trong một ZIP duy nhất:

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

Phản hồi bao gồm

(hợp lệ 1 giờ) cho ZIP chứa:

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

Xuất này miễn phí — không tiêu thụ credit. Tải ZIP và lưu tài sản vào kho đối tượng của bạn. URL ký trước hết hạn sau 1 giờ.

Bước 7 — (Tùy chọn) Tổng hợp MP4 phía server

API 2Slides hiện không phơi bày endpoint tổng hợp MP4 — tạo MP4 sống trong UI Workspace qua FFmpeg.wasm trong trình duyệt. Cho nhà máy nội dung, tổng hợp MP4 phía server với

:

# For each page, build a clip of (image still) + (voice audio).
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

# Concatenate all per-page clips into the final MP4.
ffmpeg -f concat -safe 0 -i clip_list.txt -c copy final.mp4

Nhịp âm thanh mỗi trang là bất kỳ điều gì trình tạo thuyết minh sản xuất — thường 5–12 giây mỗi slide cho thẻ từ vựng. Kết quả là cùng MP4 người dùng tải xuống từ UI Workspace, nhưng được sản xuất không đầu trong pipeline nhà máy của bạn.

Nếu bạn muốn biến thể dọc (9:16) và ngang (16:9) của cùng bộ slide, con đường sạch nhất là tạo bộ slide hai lần ở các tỷ lệ khung hình khác nhau ở giai đoạn tạo slide (

so với ). Cắt FFmpeg sau đó thường tạo kết quả xấu vì slide được bố trí cho tỷ lệ khung hình cụ thể.

Bước 8 — Xây orchestrator

Một orchestrator tối thiểu xử lý năm vòng:

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

Chạy điều này trên một worker box với hàng đợi. Cho 100 bộ slide mỗi ngày, một worker là đủ. Cho 1,000+, fan out đến pool worker nhỏ — nhưng đảm bảo pool tôn trọng giới hạn tỷ lệ của mỗi endpoint API, không chỉ số worker.

Bước 9 — Mẫu phân phối

Lớp phân phối biến tài sản thành giá trị kinh doanh:

• LMS: tải MP4 đã tổng hợp lên Canvas / Moodle / Blackboard / Google Classroom qua các API của họ
• TikTok / Reels / Shorts: xếp hàng MP4 9:16 vào công cụ đăng (Buffer, Later, scheduler native), một mỗi ngày
• Newsletter: nhúng bản tổng hợp PDF (từ
  downloadUrl
  của job tạo gốc) dưới dạng liên kết tải xuống trong số hàng tuần
• Bán / lead magnet: tải PDF lên trang Stan Store / Gumroad; teaser carousel dẫn lưu lượng

Đừng cố phát minh phân phối. Dùng API native của nền tảng và để orchestrator của bạn thả một hàng vào scheduler.

Toán chi phí (phần lập kế hoạch trước)

Cho bộ slide Nano Banana có thuyết minh, credit cộng nhanh hơn giá Fast PPT mà một số người đọc có thể đã thấy trước đây. Toán mỗi bộ 30 thẻ (độ phân giải 1K/2K, có thuyết minh):

• Lập kế hoạch: 10 credit
• Tạo slide: 30 × 100 = 3,000 credit
• Thuyết minh (văn bản + âm thanh): 30 × 210 = 6,300 credit
• Xuất pages + voices: 0 credit (miễn phí)
• Tổng: ~9,310 credit mỗi bộ 30 thẻ có thuyết minh

Không có thuyết minh, cùng bộ slide là ~3,010 credit. Ở 4K, gấp đôi phần tạo slide: 30 × 200 = 6,000 → ~12,310 credit với thuyết minh.

Cho nhà máy 100 bộ/tháng: 100 × 9,310 = ~931,000 credit/tháng. So với trang giá để chọn bậc — và lập ngân sách cho 4K chỉ khi đầu ra đi đến ngữ cảnh có lợi từ nó (màn hình lớn, video cao cấp). Cho video ôn TikTok / Reels, 1K hoặc 2K là đủ.

Mẫu vận hành ngăn cháy

Idempotency

Mỗi lần gửi bộ slide nên idempotent trên

. Nếu worker của bạn sập giữa lô, khởi động lại hàng đợi không được tạo bộ slide trùng. Mẫu sạch nhất: lưu trong hàng cơ sở dữ liệu; chuyển trạng thái ().

Cổng chất lượng

Đừng tự động phân phối. Trước khi đẩy lên TikTok hoặc Canvas, chạy kiểm tra chất lượng máy đọc được trên tài sản:

• Số trang khớp số yêu cầu
• ZIP chứa số tệp
  pages/page_NN.png
  và
  voices/page_NN.wav
  mong đợi
• Thời lượng âm thanh mỗi trang nằm giữa 3 và 15 giây (thẻ 30 giây hầu như luôn nghĩa là kịch bản dài bị ảo giác)
• transcript.txt
  không trống và chứa từ mục tiêu

Cho 50 lô đầu tiên, cũng làm kiểm tra điểm thủ công 1 trong 10 bộ slide. 50 lô đầu là nơi vấn đề prompt hệ thống xuất hiện.

Phiên bản hóa

Mỗi tài sản lưu: phiên bản template prompt, phiên bản model hình ảnh (

so với ), giọng thuyết minh, dấu thời gian tạo. Khi model cải thiện hoặc prompt thay đổi, bạn có thể chạy lại chỉ bộ slide bị ảnh hưởng.

Đo lường chi phí

Mỗi bộ slide có chi phí credit đã biết (xem toán trên). Theo dõi credit tiêu thụ mỗi bộ slide. Khi sử dụng credit mỗi bộ slide tăng gấp đôi bất ngờ, có gì đó đã thay đổi (trôi số trang, retry, chuyển sang 4K). Tìm trước khi hóa đơn credit bất ngờ.

Xử lý lỗi

Job thất bại là bình thường — trục trặc mạng, tải model, 5xx hiếm. Retry một lần sau backoff. Sau hai thất bại, đẩy bộ slide vào hàng đợi

. Đừng vòng vô hạn.

Build vs buy: khi nào dùng API

API là câu trả lời đúng khi:

• Bạn sản xuất >10 bộ slide/tuần
• Bạn có dữ liệu nguồn có cấu trúc
• Bạn cần MP4 có thuyết minh sẽ tổng hợp phía server và phân phối
• Bạn tích hợp với LMS, scheduler hoặc CMS
• Bạn muốn tái lập dưới phiên bản hóa prompt

API là quá mức khi:

• Bạn sản xuất 1 bộ slide một tuần và điều chỉnh trực quan mỗi lần
• Bạn là người học xây bộ slide cho học cá nhân (UI nhanh hơn — và UI Workspace cũng làm tổng hợp MP4 cho bạn)
• Bạn là giáo viên xây một bộ slide mỗi bài học (dùng Create Slides from File hoặc Create Slides Like This và bỏ qua orchestration)

Câu hỏi thường gặp

Tôi lấy API key ở đâu?

2slides.com/api. Key sống trong tab quản lý API.

Vì sao tôi không thể thêm thuyết minh vào job

/api/v1/slides/generate

?

Endpoint

là Fast PPT — PPTX dựa trên template. Đầu ra của nó là tệp .pptx hoàn thiện, không phải job hình-ảnh-slide-cộng-văn-bản mà trình tạo thuyết minh có thể đọc. Trình tạo thuyết minh chỉ chấp nhận rõ ràng job từ hoặc , sản xuất job slide nano banana với nội dung từng trang có cấu trúc.

Tôi có thể xuất MP4 trực tiếp từ API không?

Không, không phải từ năm 2026. Xuất MP4 là tính năng UI Workspace triển khai phía client với FFmpeg.wasm. Tương đương API là

trả về ZIP của hình ảnh slide, tệp âm thanh và transcript — bạn tự tổng hợp MP4 với nếu cần trong pipeline nhà máy nội dung. Xem Bước 7.

API hỗ trợ ngôn ngữ nào để tạo?

22+ ngôn ngữ bao gồm tiếng Tây Ban Nha, Pháp, Đức, Ả Rập, Nhật, Hàn, Hindi, Việt, Nga, Ba Lan, Ý, Bồ Đào Nha, Indonesia, Thái, Thổ Nhĩ Kỳ, và tiếng Trung (Giản thể/Phồn thể). Truyền qua

.

Chi phí credit là bao nhiêu?

Cho bộ slide Nano Banana: 10 (lập kế hoạch) + 100/slide ở 1K/2K (hoặc 200/slide ở 4K) cho tạo slide, cộng 210/trang (10 văn bản + 200 âm thanh) cho thuyết minh. Xuất pages + voices miễn phí. Bộ 30 thẻ có thuyết minh ở 2K là ~9,310 credit. Xem trang giá và phần toán chi phí trên.

Tôi xử lý giới hạn tỷ lệ 429 như thế nào?

Exponential backoff. Bắt đầu ở 1s, gấp đôi đến 60s. Sau ba 429 liên tiếp, giảm số worker đồng thời một nửa. Đừng poll

nhanh hơn mỗi 20 giây — đó là nguyên nhân phổ biến nhất của 429.

Tôi có thể tích hợp với Zapier / Make / n8n không?

Có — bất kỳ công cụ nào có thể gửi request HTTP đã xác thực có thể điều khiển API 2Slides. n8n đặc biệt phổ biến cho nhà máy nội dung vì nó xử lý mẫu poll và hàng đợi native.

Tôi ngăn bộ slide tạo ra khỏi bị đánh chỉ mục công khai như thế nào?

Bộ slide tạo qua API mặc định riêng tư với tài khoản của bạn. Chia sẻ công khai là hành động riêng biệt rõ ràng.

Tôi tạo phiên bản dọc (9:16) và ngang (16:9) của cùng bộ slide như thế nào?

Tạo bộ slide hai lần — một lần với

và một lần với . Slide được bố trí cho mỗi tỷ lệ khung hình ở thời điểm tạo, nên cắt sau hiếm khi đẹp. Đúng, điều này nghĩa là gấp đôi chi phí credit; đó là đánh đổi có chủ đích cho hình ảnh sạch.

Kết luận

Một nhà máy nội dung là dữ liệu nguồn có cấu trúc + orchestrator ổn định + endpoint API đúng. API 2Slides là phần thứ ba; bạn chịu trách nhiệm cho hai phần đầu. Thất bại nhà máy phổ biến nhất là dùng

(Fast PPT) và sau đó cố thuyết minh — con đường đó đóng. Dùng hoặc thay thế, thuyết minh với , xuất với , và tổng hợp MP4 phía server với .

Cho phía thủ công của cùng quy trình, xem hướng dẫn thẻ từ vựng và hướng dẫn quy trình creator. Mẫu UI ở đó là cùng mẫu bạn đang tự động hóa với API; hiểu luồng thủ công trước làm tích hợp API nhanh hơn nhiều.