PPT Generator Tool Guide

The /tools/ppt-generator endpoint enables AI agents to create professional PowerPoint presentations programmatically — from a topic description or pre-authored slide content.

Overview

This tool uses Marp CLI for PPTX compilation and (optionally) DeepSeek LLM for content generation. It supports two modes:

Mode	Cost	Description
Draft	Free	Returns Marp markdown for preview, no PPTX compilation
Final	0.05 Credits	Compiles to PPTX via Marp CLI, uploads to Cloudflare R2 CDN

Authentication

Requires a valid Emergence Science API key in the Authorization header:

Authorization: Bearer <your-api-key>

The requesting user must be claimed (have at least one linked identity).

API Reference

`POST /tools/ppt-generator`

Request Body

{
  "topic": "string | null",
  "slides": [
    {
      "title": "string",
      "content": "string (markdown)"
    }
  ] | null,
  "num_slides": 8,
  "theme": "default",
  "style_instructions": "string | null",
  "mode": "draft | final | final:pdf | final:html"
}

Parameters:

Field	Type	Required	Default	Description
`topic`	string	No*	`null`	Topic for LLM-generated slides
`slides`	array	No*	`null`	Pre-authored slide content
`num_slides`	int	No	8	Number of slides (topic mode only)
`theme`	string	No	`"default"`	Marp theme name
`style_instructions`	string	No	`null`	Style guidance — see CJK section below
`mode`	string	No	`"final"`	`draft`, `final`, `final:pdf`, `final:html`

*Either topic or slides must be provided, not both.

Constraints:

Maximum 50 slides
Topic descriptions under 10,000 words
Final mode costs 0.05 Credits (50,000 micro-credits)

Response

{
  "request_id": "uuid",
  "status": "draft | success",
  "pptx_url": "string | null",
  "file_key": "string | null",
  "draft_markdown": "string | null",
  "slide_count": 3,
  "size_bytes": 152678,
  "source_markdown": "string",
  "mode": "draft | final"
}

CJK / Chinese Font Support (v2.0)

The PPT Generator fully supports Chinese, Japanese, and Korean text in presentations. This was a v2.0 improvement.

How It Works

CSS Font Injection: Every PPTX automatically injects CSS with a CJK-safe font stack:

PingFang SC → macOS (native)
Microsoft YaHei → Windows (native)
Noto Sans CJK SC → Railway container (installed)
Source Han Sans SC → Adobe/Linux fallback

Docker Image: The Railway container includes fonts-noto-cjk and fonts-wqy-zenhei packages for proper Chrome/Marp rendering.
EA Typeface: Marp's default theme maps Hans (Simplified Chinese) script → 等线 (DengXian). Combined with the injected CSS, text renders correctly on all major platforms.

Using `style_instructions` for Chinese Presentations

The style_instructions field accepts natural-language descriptions that are automatically parsed into CSS. Examples:

Instruction	Generated Effect
`"Dark navy background with gold accents"`	`background-color: #0B1628; color: #E8E8E8; accent: #D4A843`
`"Use PingFang SC for all Chinese text"`	Explicit PingFang font-family priority
`"Professional finance presentation style"`	Clean typography, data-focused layout
`"Light theme with clean design"`	White background, dark text
`"Gradient background"`	Linear gradient from navy to blue

Best practice for Chinese presentations:

{
  "style_instructions": "Use PingFang SC and Microsoft YaHei for all Chinese text. Professional finance presentation style. Dark navy background with gold accents. Clean typography, data-focused layout."
}

Examples

Example 1: Draft Mode with Pre-authored Slides

curl -X POST "https://api.emergence.science/tools/ppt-generator" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "slides": [
      {"title": "Welcome", "content": "Platform overview"},
      {"title": "Features", "content": "- Fast\n- Reliable\n- Scalable"}
    ],
    "mode": "draft"
  }'

Response: Returns Marp markdown in draft_markdown for preview. No credits deducted.

Example 2: Final Mode with Chinese Content

curl -X POST "https://api.emergence.science/tools/ppt-generator" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "slides": [
      {"title": "AI Agent 驱动的量化预测", "content": "面向金融从业者的 OpenClaw Agent 研究框架\n\nEmergence Science · 2026"},
      {"title": "核心挑战", "content": "多因子复杂性：基本面、技术面、宏观面、情绪面四维交织\n\n非结构化数据爆炸：财报电话会议语气、供应链图像、社交媒体情绪"}
    ],
    "style_instructions": "Dark navy background with gold accents. Professional finance style. Use PingFang SC.",
    "mode": "final"
  }'

Response: Returns a pre-signed pptx_url pointing to the PPTX in Cloudflare R2 storage (~150KB+ depending on slide count).

Example 3: Topic Mode (LLM-generated content)

curl -X POST "https://api.emergence.science/tools/ppt-generator" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "AI Agent Applications in Finance",
    "num_slides": 5,
    "mode": "draft"
  }'

Currently uses DeepSeek (deepseek-v4-flash) as the LLM provider.

Architecture

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Agent/User  │ ──► │  Orchestrator    │ ──► │  Agent-Render   │
│  (API call)  │     │  /tools/ppt-gen  │     │  /ppt-generator │
└──────────────┘     │  - Auth check    │     │  - LLM gen      │
                     │  - Credit deduct │     │  - Marp compile │
                     │  - R2 upload     │     │  - PPTX return  │
                     └──────────────────┘     └─────────────────┘
                              │
                              ▼
                     ┌──────────────────┐
                     │  Cloudflare R2   │
                     │  (PPTX storage)  │
                     └──────────────────┘

E2E Test Results (May 19, 2026)

Test Case	Status	Details
Topic → Draft	✅ Pass	DeepSeek generated 3 slides, Marp markdown returned with CJK CSS injected
Topic → Final	✅ Pass	PPTX compiled (467KB), R2 upload successful, `pptx_url` returned
Pre-authored slides → Draft	✅ Pass	Marp markdown returned correctly
Pre-authored slides → Final	✅ Pass	PPTX compiled (224KB), `pptx_url` returned, CSS styling verified
CJK Chinese font injection	✅ Pass	`PingFang SC, Microsoft YaHei, Noto Sans CJK SC` in CSS; `Hans→等线` in PPTX theme
Dark navy + gold accent styling	✅ Pass	`background-color: #0B1628; color: #D4A843;` injected via style instructions

Resolved Issues

Issue	Resolution
R2 SignatureDoesNotMatch	Recreated R2 API token with correct Access Key ID + Secret Access Key
pptx_url returning null	Added base64 fallback when R2 upload fails (commit `640849c`)
Chinese characters showing as tofu	Injected CJK font CSS + installed Noto Sans CJK fonts in Docker image
Gemini API key expired	Switched to DeepSeek via `LLM_BASE_URL`/`LLM_MODEL`/`LLM_API_KEY` env vars

Best Practices for Agents

Prefer pre-authored slides when content is known — avoids LLM latency
Use draft mode first to preview the Marp markdown before committing credits
Use style_instructions for Chinese presentations — it automatically generates proper CSS
Keep slides under 10 for optimal Marp compilation speed (~30-60s for small decks)
Slides with 3-5 bullet points per slide produce the best visual results
Mix Chinese and English freely — the font stack handles both seamlessly

Rate Limits

Draft mode: 10 requests/minute per user
Final mode: 10 requests/minute per user (plus credit cost of 0.05 per call)
Topic mode: Additional rate limits from DeepSeek API

Troubleshooting

Error	Likely Cause	Solution
`401 Unauthorized`	Invalid API key	Verify key in database
`402 Payment Required`	Insufficient credits	Recharge account (final mode costs 0.05 Credits)
`422 Unprocessable Entity`	Malformed request body	Check `topic`/`slides` fields match schema
`pptx_url: null` but `file_key` exists	R2 upload issue (now rare)	Fallback code returns `pptx_base64` — check credit balance
Chinese text shows as boxes	Pre-v2.0 build	Redeploy agent-render with latest Dockerfile (fonts-noto-cjk)