# html2pptx.app — Complete Documentation > A hosted HTML-to-PowerPoint service: supported text and simple shapes remain editable, while selected visual elements are rasterized. Last reviewed: 2026-07-25 Runtime behavior and the crawlable website are authoritative. The OpenAPI document is the machine-readable contract for the core REST routes it describes. ## Table of Contents 1. [Service Overview](#service-overview) 2. [Quick Start](#quick-start) 3. [API Reference](#api-reference) 4. [HTML Contract](#html-contract) 5. [Skills Integration](#skills-integration) 6. [MCP Integration](#mcp-integration) 7. [Studio & Web Export](#studio--web-export) 8. [Use Cases](#use-cases) 9. [Plans & Pricing](#plans--pricing) 10. [Security & Limits](#security--limits) 11. [FAQ](#faq) 12. [Troubleshooting](#troubleshooting) --- ## Service Overview html2pptx.app converts slide-oriented HTML/CSS into PowerPoint. Supported text and simple shapes remain editable; SVGs, icons, and some complex structures are rasterized. Flexbox, Grid, gradients, and shadows are supported within the published HTML contract. Review each export because browser and PowerPoint rendering can differ. **Supported HTML/CSS is mapped to editable PowerPoint objects where possible; selected visual elements are exported as images.** ### Architecture html2pptx.app uses a staged pipeline that separates request handling, durable job state, rendering, and delivery: **Client**: Your application, agent, or script sends HTML/CSS via REST API. Any language or platform that can make HTTP requests works. **API Gateway**: Handles authentication (Bearer / X-API-Key), rate limiting per plan tier, request validation, and the initial job creation request. **Durable Queue**: Job metadata is stored in Convex, large request payloads are stored in object storage, and Cloud Tasks can dispatch processing without losing jobs on worker restart. **Private Worker**: The private renderer loads the saved job, maps supported HTML/CSS to PowerPoint objects or images, and updates the durable job state as it progresses. **PPTX Output**: The generated PowerPoint file is uploaded to cloud storage and a time-limited signed URL is returned for download. Retention follows the deployment policy, so check the job status for the current result and save it promptly. ### How html2pptx.app Compares | Feature | html2pptx.app | Others | |---------|--------------|--------| | Conversion method | Supported elements become PPTX objects; selected content is rasterized | Varies: object conversion or slide images | | Text editability | Editable for supported text elements | Varies by conversion method | | CSS support | Published subset including Flexbox, Grid, gradients, shadows, and transforms | Varies by provider | | SVG handling | Rasterized to PNG | Varies by provider | | File size | Depends on embedded and rasterized imagery | Depends on output model and imagery | | Font handling | System-font mapping; public REST does not fetch external web fonts | Varies by provider | ### Three Integration Channels **REST API**: Standard HTTP endpoints for creating HTML-to-PPTX export jobs and polling status. Best for backend integrations, internal tools, and SaaS embedding. Works with any language -- curl, JavaScript, Python, Go, Ruby, and more. Creator-owned template draft creation is not a REST API surface. **Skills**: Register the html2pptx skill for agent tools like Claude Code and Codex. The agent can diagnose, rewrite, export slide-safe HTML, open local editing, and create validated HTML template drafts through the built-in remote MCP workflow. Ideal for AI-powered workflows where the agent manages the full pipeline. **MCP (Model Context Protocol)**: Expose the backend to AI agents via the MCP protocol. Use the remote HTTP endpoint at /mcp for export, docs, catalog, and the supported public creator-owned template draft workflow; use local stdio MCP only for opening local HTML in edit-slide. The documented draft workflow validates and saves HTML through authenticated remote MCP. ### Supported CSS Features | Category | Features | |----------|----------| | Layout | display: flex, display: grid, position: absolute/relative, gap, align-items, justify-content | | Box Model | padding, margin, width, height, box-sizing, overflow: hidden | | Background | background-color, linear-gradient(), radial-gradient(), background-image (URL/base64) | | Border | border, border-radius (including per-corner), border-color, border-width | | Shadow | box-shadow (single and multiple), text-shadow | | Typography | font-family, font-size, font-weight, color, text-align, line-height, letter-spacing | | Transform | transform: rotate(), scale(), translate(), skew() | | Visual | opacity, visibility, z-index, object-fit | ### Supported Features - Inline SVGs are rasterized to PNG and are not editable as vectors in PowerPoint - System-font mapping with explicit output review for substitutions and line wrapping - Flexbox and CSS Grid support within the published subset; review the resulting layout - Gradients, shadows, and border-radius support within the HTML contract; browser parity is not guaranteed - Base64 data URI and absolute-URL image support - Explicit slide canvases with custom width/height/layout support. 1600x900px (13.333in x 7.5in) remains the default example - Multi-slide support (each .slide element becomes one PPTX slide) - Japanese font support (Noto Sans JP, Yu Gothic, Meiryo) - Hosted Studio and hosted web export for manual use in the browser --- ## Quick Start The REST API is asynchronous: create a job, poll its status, then use downloadUrl when it completes. ### Step 1: Sign Up Create an account at html2pptx.app. Free Preview includes one API key and up to 10 exports per month for limited evaluation. Founder Beta expands the quota for continued and commercial use. ### Step 2: Get API Key Navigate to the Dashboard and click "Create API Key". Copy and store it securely -- it will only be shown once. Your key starts with sk_live_ and should be treated as a secret. ### Step 3: Send First Request POST your HTML slide content to /api/export/jobs with your API key in the Authorization header. The API returns a jobId that you can use to track the export. ### Step 4: Download PPTX Poll GET /api/export/jobs/{jobId} until status is "completed". The response normally includes a downloadUrl for the PPTX file; fileBase64 may appear only as a worker fallback when a URL cannot be produced. ### curl Example ```bash curl -X POST https://html2pptx.app/api/export/jobs \ -H "Authorization: Bearer sk_live_xxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: my-unique-request-id-123" \ -d '{ "fileName": "quarterly-review.pptx", "html": "

Hello

Generated via API

", "css": ".slide { font-family: Arial, sans-serif; background: #fff; }", "autoEmbedFonts": false, "metadata": { "channel": "api", "source": "docs-quickstart" } }' # Response (200 OK): # { # "jobId": "5d934729-a0db-4aa9-bc65-e7a3e7e52b32", # "status": "queued", # "createdAt": "2026-04-02T10:30:00Z", # "fileName": "quarterly-review.pptx", # "slideCount": 1 # } # Response headers include: x-request-id: req_abc123... # Poll for completion: curl -s https://html2pptx.app/api/export/jobs/5d934729-a0db-4aa9-bc65-e7a3e7e52b32 \ -H "Authorization: Bearer sk_live_xxxx" # Response (200 OK, when completed): # { # "jobId": "5d934729-a0db-4aa9-bc65-e7a3e7e52b32", # "status": "completed", # "createdAt": "2026-04-02T10:30:00Z", # "completedAt": "2026-04-02T10:30:12Z", # "fileName": "quarterly-review.pptx", # "slideCount": 1, # "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation", # "downloadUrl": "https://storage.example.com/quarterly-review.pptx?token=..." # } ``` ### JavaScript Example ```javascript const response = await fetch("https://html2pptx.app/api/export/jobs", { method: "POST", headers: { "Authorization": "Bearer sk_live_xxxx", "Content-Type": "application/json", "Idempotency-Key": "my-unique-request-id-123", }, body: JSON.stringify({ fileName: "quarterly-review.pptx", html: `

Hello World

Generated via API

`, css: ".slide { font-family: Arial, sans-serif; background: #fff; }", autoEmbedFonts: false, metadata: { channel: "api", source: "docs-js" }, }), }); const { jobId } = await response.json(); const requestId = response.headers.get("x-request-id"); console.log("Job created:", jobId, "Request ID:", requestId); // Poll for completion const poll = async (id) => { const res = await fetch(`https://html2pptx.app/api/export/jobs/${id}`, { headers: { "Authorization": "Bearer sk_live_xxxx" }, }); if (res.status === 429) { const retryAfter = Number(res.headers.get("Retry-After") || 20); await new Promise(r => setTimeout(r, Math.max(1, retryAfter) * 1000)); return poll(id); } if (!res.ok) throw new Error(`Status request failed: ${res.status}`); const data = await res.json(); if (data.status === "completed") return data; if (data.status === "failed") throw new Error(data.message || data.error); await new Promise(r => setTimeout(r, 20000)); return poll(id); }; const completed = await poll(jobId); // Public REST returns a download URL when available. console.log("Download URL:", completed.downloadUrl); // fileBase64 may appear only as a worker fallback when a URL cannot be produced. ``` ### Python Example ```python import requests import time API_KEY = "sk_live_xxxx" BASE_URL = "https://html2pptx.app" # 1. Create export job resp = requests.post( f"{BASE_URL}/api/export/jobs", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", "Idempotency-Key": "my-unique-request-id-123", }, json={ "fileName": "quarterly-review.pptx", "html": '

Hello

', "css": ".slide { font-family: Arial, sans-serif; }", "autoEmbedFonts": False, "metadata": {"channel": "api", "source": "docs-python"}, }, ) job_id = resp.json()["jobId"] request_id = resp.headers.get("x-request-id") print(f"Job created: {job_id} (request-id: {request_id})") # 2. Poll for completion while True: status_resp = requests.get( f"{BASE_URL}/api/export/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"}, ) if status_resp.status_code == 429: time.sleep(max(1, int(status_resp.headers.get("Retry-After", "20")))) continue status_resp.raise_for_status() data = status_resp.json() if data["status"] == "completed": break if data["status"] == "failed": raise RuntimeError(data.get("message") or data.get("error")) time.sleep(20) # 3. Download the PPTX file download_resp = requests.get(data["downloadUrl"]) with open("output.pptx", "wb") as f: f.write(download_resp.content) print("Saved to output.pptx") ``` --- ## API Reference Base URL: https://html2pptx.app Export job creation, status, and plan endpoints use application/json. PPTX import accepts either multipart/form-data with a file or application/json with pptxBase64; see the OpenAPI document for the exact contract. The create endpoint accepts top-level html or a same-key templateId, plus data, css, fileName, and optional size controls; there is no nested payload wrapper. ### Authentication Commercial export endpoints require authentication. Create and revoke API keys from the Dashboard, send a key in one of the following headers, and store it as a secret. | Header | Value | Note | |--------|-------|------| | Authorization | `Bearer sk_live_xxxx` | Recommended -- standard Bearer token format used by most HTTP clients and libraries | | X-API-Key | `sk_live_xxxx` | Alternative header for environments where Authorization is reserved (e.g., API gateways, proxies) | ### Rate Limiting Commercial export responses expose rate and quota headers after a plan is resolved. Available headers vary by plan and response path. REST calls are limited per API key; remote MCP calls are limited per authenticated principal. | Header | Description | |--------|-------------| | `x-request-id` | Request identifier returned by export endpoints for tracing. Preserve it when debugging or contacting support. | | `X-Plan-Id` | The effective plan ID applied to the request. | | `X-RateLimit-Limit` | Maximum requests allowed in the current one-minute window. | | `X-RateLimit-Remaining` | Requests remaining in the current window. | | `Retry-After` | Seconds to wait before retrying after a 429 response. | | `X-Daily-Limit` | Returned on plans with a daily export cap. | | `X-Daily-Remaining` | Remaining jobs in the current UTC day. | | `X-Monthly-Used` | Exports accepted in the current UTC month. | | `X-Fair-Use-State` | Monthly fair-use status such as normal, review, or upgrade_recommended. | ### Job Lifecycle Notes - POST /api/export/jobs returns immediately with a queued job descriptor. It does not block until the PPTX is finished. - Use the public status route at GET /api/export/jobs/{jobId}. Do not rely on any upstream worker URL that may appear in internal payloads. - The completed REST response normally includes downloadUrl. fileBase64 may appear only as a worker fallback when a URL cannot be produced; public REST callers cannot select a response format. - Job ownership is bound to the API key or authenticated MCP principal that created the job. A different key cannot read the same jobId. - Slide count is derived server-side from sanitized .slide roots. Client-provided counts are ignored for enforcement. ### POST /api/v1/import/pptx **Import PPTX to HTML** Converts an existing .pptx into editable HTML slides (the reverse of export). Resolves theme colors (including clrMap/clrMapOvr inversion on dark slides), master text styles, and font families. Synchronous — returns the HTML in a single response. Also available at POST /api/import/pptx. #### Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `file` | file | No | -- | multipart/form-data: the .pptx file (max 25 MB). Use this OR pptxBase64. | | `pptxBase64` | string | No | -- | application/json: base64-encoded .pptx contents (data URLs accepted). Recommended for JSON-RPC / MCP clients. | | `fileName` | string | No | presentation.pptx | Optional original file name used for labeling. | #### Response (200 OK) ```json { "fileName": "deck.pptx", "plan": "api_starter", "slideCount": 13, "slides": [{ "index": 1, "html": "
...
" }], "html": "...", "css": "...", "warnings": [] } ``` #### Error Codes | Code | Description | |------|-------------| | 400 | Missing/invalid file, invalid base64, or invalid OOXML. | | 401 | Missing API key. Set the Authorization: Bearer or X-API-Key header. | | 403 | API key is not mapped to a plan with API access. | | 413 | PPTX exceeds the 25 MB size limit. | ### POST /api/export/jobs **Create Export Job** Creates a new PPTX export job from inline HTML/CSS or a reusable templateId owned by the same API key. The response is a queued job descriptor; use GET /api/export/jobs/{jobId} to retrieve terminal results. #### Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `fileName` | string | No | export.pptx | Output filename for the generated PPTX. Must end with .pptx extension. | | `html` | string | No | -- | Slide-oriented HTML containing one or more .slide elements. Required unless templateId resolves to a reusable template owned by this API key. | | `css` | string | No | "" | Optional CSS applied globally to the submitted HTML. | | `templateId` | string | No | -- | Reusable export template ID beginning with tpl_ and registered to the same API key. May be used instead of html. | | `data` | object | No | {} | Template variables merged into html/css or the reusable template before sanitization. | | `autoEmbedFonts` | boolean | No | false | Compatibility input forwarded to the renderer. Public REST removes @font-face rules and blocks external font downloads, so this does not fetch Google Fonts or custom web fonts. | | `slideCount` | integer | No | -- | Deprecated input retained for compatibility. The public gateway ignores it and recalculates the effective count from sanitized .slide elements. | | `width` | number | No | -- | Optional PPTX slide width in inches. Use with height for custom presentation sizes. | | `height` | number | No | -- | Optional PPTX slide height in inches. Use with width for custom presentation sizes. | | `layout` | string | No | -- | Optional PPTX layout preset or custom layout name. Common presets: LAYOUT_16x9, LAYOUT_16x10, LAYOUT_4x3, LAYOUT_WIDE. | | `aspectRatio` | string | No | -- | Optional ratio using 16:9, 16:10, or 4:3 (the separators :, x, and × are accepted). Unsupported values are ignored. | | `metadata` | object | No | {} | Opaque metadata forwarded to the worker. Useful for request tracing on your side. | | `callbackUrl` | string | No | -- | An HTTPS URL to receive a completion or failure hint. The payload contains jobId/status plus fileName on success or message on failure; it is not the full result. No customer-verifiable webhook signing contract is currently exposed, so treat the callback as unauthenticated and fetch the result from the authenticated status endpoint. Only https:// URLs are accepted. | #### Response (200 OK) ```json { "jobId": "5d934729-a0db-4aa9-bc65-e7a3e7e52b32", "status": "queued", "createdAt": "2026-04-02T10:30:00Z", "fileName": "quarterly-review.pptx", "slideCount": 1 } ``` #### Error Codes | Code | Description | |------|-------------| | 400 | Invalid request body -- missing required fields or malformed JSON. | | 401 | Missing or invalid API key. Ensure the Authorization or X-API-Key header is set with a valid sk_live_ key. | | 403 | API key does not have permission for this operation. Check plan limits or key scope. | | 404 | The supplied reusable templateId was not found for this API key. | | 413 | Request entity too large. The total request body exceeds your plan limit or the worker hard cap. | | 422 | The sanitized HTML resolves to more slides than your plan allows. | | 429 | Rate limit exceeded, daily limit exceeded, monthly fair-use review triggered, or concurrent job limit exceeded. Check Retry-After and usage headers. | | 502 | Bad gateway -- the worker backend is temporarily unavailable. Retry after a short delay. | | 503 | Service unavailable -- the system is under maintenance or experiencing high load. Retry with exponential backoff. | ### GET /api/export/jobs/{jobId} **Check Job Status** Retrieves the current status of an export job. Poll until status is "completed" or "failed". A completed response normally includes downloadUrl; fileBase64 may appear only as a worker fallback. #### Path Parameters | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `jobId` | string | Yes | -- | The job ID returned from the POST /api/export/jobs endpoint. | #### Response (200 OK) ```json { "jobId": "5d934729-a0db-4aa9-bc65-e7a3e7e52b32", "status": "completed", "createdAt": "2026-04-02T10:30:00Z", "completedAt": "2026-04-02T10:30:12Z", "fileName": "quarterly-review.pptx", "slideCount": 3, "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "downloadUrl": "https://storage.example.com/quarterly-review.pptx?token=..." } ``` #### Status Values | Status | Description | |--------|-------------| | `queued` | Job is waiting in the processing queue. | | `processing` | Worker is actively converting HTML to PowerPoint. | | `completed` | Conversion finished successfully. downloadUrl is normally available; fileBase64 may be present as a fallback. | | `failed` | Conversion failed. The message field contains a human-readable description. | #### Error Codes | Code | Description | |------|-------------| | 401 | Missing or invalid API key. | | 404 | Job not found -- either the jobId is invalid or the job belongs to a different API key. | | 429 | Status polling rate limit exceeded. | ### GET /api/export/plans **List Plans** Returns the public plan catalog plus the recommended default plan. No authentication required. #### Response (200 OK) ```json { "recommendedPlanId": "founding_beta", "plans": [ { "id": "free_web", "name": "Free Preview", "includes": { "api": true, "skills": true, "mcp": true }, "limits": { "requestsPerMinute": 3, "dailyRequestLimit": 10, "monthlyRequestLimit": 10, "monthlyReviewThreshold": 0, "monthlyUpgradePromptThreshold": 0, "maxSlidesPerJob": 20, "concurrentJobs": 1, "apiKeys": 1, "maxPayloadBytes": 1048576 } } ], "note": "Free Preview is generous for personal use. Paid tiers unlock commercial operation, team sharing, automation throughput, and support." } ``` ### GET /api/openapi.json **OpenAPI Specification** Returns the OpenAPI 3.x specification for the html2pptx.app API. Useful for generating client SDKs, importing into Postman, or browsing the API schema. #### Response (200 OK) ```json // Returns the full OpenAPI 3.x JSON document ``` ### Error Response Format Commercial export errors use RFC 9457 Problem Details with additional legacy fields for backwards compatibility. Some legacy and creator endpoints return a smaller error object: ```json { "type": "https://html2pptx.app/errors/slides-limit-exceeded", "status": 422, "title": "Slides limit exceeded", "detail": "Plan Starter supports up to 200 slides per job. You submitted 260 slides.", "instance": "/api/export/jobs", "error": "slides_limit_exceeded", "message": "Plan Starter supports up to 200 slides per job.", "slideCount": 260 } ``` --- ## HTML Contract The HTML you send must follow these rules for reliable conversion. - Each slide must have the class .slide -- this is the boundary marker for slide separation - Each .slide must have explicit dimensions. 1600px x 900px (16:9 ratio at 13.333in x 7.5in) is the default example, and API/MCP callers can also set width, height, or layout for portrait/custom output - Supported CSS: flexbox, grid, linear-gradient, radial-gradient, box-shadow, text-shadow, border-radius, transform (rotate, scale, translate, skew), opacity - Fonts: use fonts installed in the render and target PowerPoint environments. Public REST removes @font-face rules and blocks external font downloads; inspect substitutions and line wrapping - Images: both base64 data URIs and absolute URLs are supported. Relative paths will fail -- always use absolute URLs - SVGs: inline SVG elements are supported and are converted to high-quality PNG images - Avoid: script tags, iframes, script-dependent canvas content, external video URLs, anchor tags, form elements, SVG external references, CSS animations, @keyframes, and runtime-dependent state - Nesting: deeply nested elements (> 10 levels) may impact output quality. Keep your HTML structure flat where possible - Text wrapping: text boxes default to no-wrap to prevent unexpected line breaks in PPTX. If you need text to wrap within a container (e.g. long paragraphs), add white-space: normal to that element --- ## Skills Integration Skills are packaged capabilities that extend AI coding agents with domain-specific knowledge and workflows. The html2pptx.app skill teaches your agent how to author slide-safe HTML, validate it against the PPTX conversion contract, optionally open the local visual editor through local stdio MCP, export through remote MCP, and create validated HTML template drafts through remote MCP. The dashboard can share reviewed drafts as unlisted pages; new public-gallery publishing is currently disabled. The resulting PPTX remains an export candidate: validate the markup and visually review the file before distribution. ### Workflow 1. Agent receives a user request (e.g., "Create a deck from these meeting notes") 2. Agent reads the skill definition to understand the html2pptx.app HTML contract 3. Agent generates slide-safe HTML with .slide class elements and explicit dimensions. 1600x900 is the default example 4. Agent validates the markup against the conversion contract 5. If visual review is needed, the agent opens the local edit-slide editor through the CLI or local stdio MCP, then re-reads the edited HTML from disk 6. Agent connects to remote MCP and calls html2pptx_create_export_job 7. Agent polls with html2pptx_wait_for_export_job until completed 8. If the user wants to create an HTML template draft, the agent uses the html2pptx skill and remote MCP: infer title/tags from the HTML, run AI security preflight, validate, fix errors, save a draft, then return draftUrl for dashboard review 9. Agent returns the completed job summary to the user ### Setup #### Step 1: Install MCP + Skill Pick the command for the agent you actually use: Claude Code, Codex, Cursor, VS Code (GitHub Copilot), or Antigravity. For Grok Build, use the Grok-specific installer. For other supported agents or multiple targets, drop the `-a` flag and use the interactive selector. Avoid `--yes` unless you intentionally want to install into every detected agent directory. ```bash # Choose the command for your agent # Claude Code npx skills add https://html2pptx.app -a claude-code # Grok Build npx --yes --package html2pptx-local-mcp@latest html2pptx-install-skills grok # Codex npx skills add https://html2pptx.app -a codex # Cursor npx skills add https://html2pptx.app -a cursor # VS Code (GitHub Copilot) npx skills add https://html2pptx.app -a github-copilot # Antigravity npx skills add https://html2pptx.app -a antigravity # Preview published skills without installing npx skills add https://html2pptx.app --list # More agents / multiple targets: use the interactive selector npx skills add https://html2pptx.app # Claude Code / Codex / Grok Build users: run the matching one line for MCP. npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok ``` #### Step 2: Configure API key Create an API key in the html2pptx.app dashboard and set it as an environment variable. ```bash # Set API key as environment variable export HTML2PPTX_API_KEY="sk_live_xxxx" # Or add to your .env file echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env ``` #### Step 3: Try it out Launch your editor and give it a natural language instruction to create slides. The skill handles everything automatically. ```bash # 例: Claude Code でスライド作成 → PPTX出力 > 「この会議メモから5枚のプレゼンを作って、PPTXで出力して」 # エージェントが自動で実行するフロー: # 1. SKILL.md を読み込み、html2pptx.app のHTML契約を理解 # 2. 会議メモを解析し、スライド構成を設計 # 3. .slide クラス + 明示サイズ付きのスライドセーフHTMLを生成（1600x900 はデフォルト例） # 4. diagnose でマークアップを検証（safe / needs-rewrite / out-of-scope） # 5. html2pptx.app API にエクスポートジョブを送信 # 6. 完了をポーリングし、completed payload をユーザーに返却 # APIキーの設定（環境変数） export HTML2PPTX_API_KEY="sk_live_xxxx" ``` ### Available Skills **html-to-pptx-slide-authoring**: スライド用HTML/CSSの作成・診断・修正。HTMLがPPTXに正しく変換されるかを事前チェックし、問題があれば自動で書き換え。 Capabilities: - HTML診断（safe / needs-rewrite / out-of-scope） - マークアップ自動書き換え - スライドHTML新規生成 - 入力バリデーション **pptx-studio-export-automation**: APIジョブの作成・ステータス管理・エラーハンドリング。REST API / MCP の使い分け判断も含む。 Capabilities: - エクスポートジョブ作成 - ポーリング＆完了待機 - エラー分析＆リトライ - プラン制限の事前チェック **edit-slide**: ローカルHTMLスライドをlocalhost上のvisual editorで開き、localhost bridge 経由で同じファイルに保存。 Capabilities: - html2pptx edit - PowerPoint風UIで視覚編集 - ローカルHTMLへの自動保存 - 変更検知と競合防止 ### Skill Capabilities **Diagnose HTML**: Classify markup as safe, needs-rewrite, or out-of-scope before attempting export. Catches issues like missing .slide elements, unsupported CSS, or dynamic content. **Rewrite Markup**: Transform web-shaped HTML (responsive layouts, percentage-based sizing, scroll containers) into fixed-size .slide structures suitable for PPTX conversion. **Generate Slides**: Create new slide-safe HTML from scratch given a text prompt, topic outline, or data payload. Applies best practices for visual hierarchy and readability. **Validate Output**: Run the generated HTML through a pre-flight check against the html2pptx.app HTML contract before making the API call, preventing wasted export quota on invalid input. **Create Template Drafts**: For creator-owned HTML drafts, the supported public workflow is AI security preflight, remote MCP validation, and authenticated draft creation. CLI, local MCP, and generic REST are not supported draft-creation contracts; legacy or hidden web surfaces are outside this public workflow. Reviewed drafts can be shared as unlisted pages; new public-gallery publishing is disabled. --- ## MCP Integration MCP (Model Context Protocol) is an open protocol that exposes backend capabilities to AI agents through a standardized tool interface. html2pptx.app supports two MCP surfaces: the remote HTTP MCP endpoint at /mcp for export, import, usage, docs, templates, catalog, and creator-owned HTML template drafts; and the local stdio MCP server, which exposes only html2pptx_open_local_slide_editor and html2pptx_stop_local_slide_editor for local edit-slide sessions through a localhost bridge. Use remote MCP for export jobs, PPTX import, job polling, or HTML template drafts. Use local stdio MCP only when the agent must open, preview, edit, or stop editing a local HTML file on the user machine. ### Installation & Setup Claude Code, Codex, and Grok Build users can run one command to register both remote export tools and local edit-slide. Remote MCP follows the hosted service; local MCP uses html2pptx-local-mcp@latest so future starts pick up the newest published package. #### Claude Code (Recommended) **Claude Code users: run this one line** This registers remote export as `html2pptx`, then writes local edit-slide as `html2pptx-local` directly into Claude Code user config. ``` npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude ``` **Manual remote setup** If you only need hosted export tools, add the remote MCP server directly. ``` claude mcp add --scope user --transport http html2pptx https://html2pptx.app/mcp ``` **Compatible local edit-slide setup** If Claude Code stdio registration is unreliable, use the installer because it writes the local server entry directly. ``` npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude ``` > Tip: The installer registers the remote MCP with user scope and writes the local stdio MCP directly to Claude Code user config for better compatibility. #### Grok Build **Install MCP for Grok Build** Run the Grok installer. It registers remote export as `html2pptx` and local edit-slide as `html2pptx-local` through `grok mcp add`. ``` npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp grok ``` **Install Skills for Grok Build** Install the published html2pptx skills into Grok Build’s native skills directory. This does not change MCP configuration. ``` npx --yes --package html2pptx-local-mcp@latest html2pptx-install-skills grok ``` **Manual remote setup** If you prefer to register the remote MCP yourself (or the installer is unavailable), run this directly. `--type http` forces the streamable-http transport so Grok does not auto-pick SSE. ``` grok mcp add html2pptx --url https://html2pptx.app/mcp --type http ``` > Tip: Use `grok inspect` to confirm which project skills and MCP servers Grok discovered. OAuth via WorkOS AuthKit completes in the browser on first use. If your account has not previously been seen on html2pptx.app, sign in to https://html2pptx.app once with the same Google / WorkOS identity so a user record is provisioned before launching Grok. #### Codex **Run one command (recommended)** This registers remote export as `html2pptx`, then adds local edit-slide as `html2pptx-local` using the published package. ``` npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex ``` **Manual remote setup** If you only need hosted export tools, add the remote MCP server directly. ``` codex mcp add html2pptx --url https://html2pptx.app/mcp ``` **Optional local stdio MCP for edit-slide** Use this only when Codex needs to launch local edit-slide for a `.html` file. It runs from the published package, so no repository checkout is required. ``` codex mcp add html2pptx-local -- npx --yes --package html2pptx-local-mcp@latest html2pptx-mcp ``` **Manual remote setup via codex.json** Alternatively, create or edit codex.json in your project root for the hosted remote server. ``` { "mcpServers": { "html2pptx": { "type": "url", "url": "https://html2pptx.app/mcp" } } } ``` > Tip: The installer runs the two Codex MCP add commands in order and continues if either server is already registered. #### Cursor **Add to .cursor/mcp.json** Create .cursor/mcp.json in your project root and add the following. ``` { "mcpServers": { "html2pptx": { "url": "https://html2pptx.app/mcp" } } } ``` #### VS Code **Run the CLI command (recommended)** Run the following command in your terminal. ``` code --add-mcp '{"name":"html2pptx","type":"http","url":"https://html2pptx.app/mcp"}' ``` **Manual setup via .vscode/mcp.json** Alternatively, create .vscode/mcp.json in your project root. ``` { "servers": { "html2pptx": { "type": "http", "url": "https://html2pptx.app/mcp" } } } ``` #### Antigravity **Add to ~/.antigravity/mcp.json** Create or edit ~/.antigravity/mcp.json and add the following. Restart Antigravity after saving so the IDE picks up the new MCP server. ``` { "mcpServers": { "html2pptx": { "url": "https://html2pptx.app/mcp" } } } ``` > Tip: Antigravity (Google) uses the standard MCP mcpServers shape — same JSON as Cursor. ### Available MCP Tools | Tool | Description | |------|-------------| | `html2pptx_list_export_plans` | List the current commercial plan catalog and recommended plan. | | `html2pptx_create_export_job` | Create an export job from HTML/CSS content. Supports optional width, height, layout, waitForCompletion, pollIntervalMs (1-60 seconds), timeoutMs (up to 300 seconds), and responseFormat ("url" \| "base64" \| "both"). Inline MCP delivery is limited to 2 MiB; larger files return the signed URL with a warning. | | `html2pptx_import_pptx` | Remote MCP only. Reverse of export: convert an existing .pptx into editable HTML slides by passing pptxBase64. The local stdio MCP does not expose this tool or accept filePath. Resolves theme colors, master text styles, and fonts. | | `html2pptx_get_export_job` | Get the current status of an export job by jobId. | | `html2pptx_wait_for_export_job` | Polls every 1-60 seconds until the job completes, fails, or reaches the 300-second maximum wait. Transport and rate-limit errors are returned to the caller; the tool does not add automatic retries or backoff. | | `html2pptx_get_docs` | Fetch html2pptx.app documentation to understand the API contract, HTML requirements, and integration guides. | | `html2pptx_get_usage` | Fetch the current usage and quota status for your plan. Shows daily and monthly export counts, remaining quotas, plan limits, and reset information. | | `html2pptx_list_templates` | List available marketplace templates with metadata and optional category filtering. | | `html2pptx_get_template_html` | Fetch a template source HTML and design prompt so agents can study or remix it. | | `html2pptx_validate_template_html` | Dry-run marketplace HTML validation after AI security preflight. Required before creating an HTML template draft. | | `html2pptx_publish_template` | Upload validated HTML, infer missing title/description/category/tags, and create a creator-owned HTML draft. The tool returns draftUrl; the user can review it and create an unlisted share from the dashboard. New public-gallery publishing is currently disabled. | | `html2pptx_open_local_slide_editor` | Local stdio MCP only. Starts the existing CLI localhost bridge for a local .html/.htm slide file and opens the no-code editor without publishing the HTML. Not available from remote /mcp because remote servers cannot access user files. | | `html2pptx_stop_local_slide_editor` | Local stdio MCP only. Stops a local editor bridge session started by html2pptx_open_local_slide_editor. | ### Example Usage ``` # Example conversation in Claude Desktop with html2pptx.app MCP: User: "Create a presentation about our Q1 2026 results." Claude (via MCP): 1. Calls html2pptx_list_export_plans to inspect available plans 2. Generates slide HTML from the conversation context 3. Calls html2pptx_create_export_job with the HTML payload 4. Calls html2pptx_wait_for_export_job to poll until completion 5. Returns the resulting PPTX payload or follow-up instructions # Behind the scenes, the MCP tools handle: # - Authentication with your configured API key # - Proper HTML contract formatting (.slide class, explicit slide dimensions) # - Status polling with exponential backoff # - Error handling and retry logic ``` --- ## Studio & Web Export html2pptx.app also includes a browser-facing Studio and a hosted same-origin web export route. Use these surfaces for manual authoring, visual checks, and lightweight in-browser export flows. **Studio**: The Studio is the manual authoring environment. It is useful when you want to paste HTML/CSS, inspect the visual result, iterate on layout, and export without building your own API client first. **Hosted Web Export**: The hosted web export route is a browser-oriented wrapper around the same backend worker. It is designed for same-origin web app usage, not for backend-to-backend automation or third-party embedding. **When to use each**: Use REST API for product integrations and backend automation, Skills/MCP for agent workflows, Studio for manual authoring, and hosted web export for first-party browser UI flows. ### How these public surfaces fit together - Studio is public and can be used to write or preview slide-oriented HTML manually. - Hosted web export calls /api/web-export/jobs from the browser and is guarded as a same-origin web surface. - REST API remains the canonical automation contract for backend systems and production pipelines. - If you need reproducible server-side exports, prefer the authenticated REST API over hosted web export. - The same core worker and sanitization pipeline sit behind Studio previews, hosted web export, API, Skills, and MCP. - Template draft creation is deliberately narrower: the supported public contract is authenticated remote MCP validation and HTML draft saving. CLI, local MCP, and generic REST are not supported draft-creation contracts; legacy or hidden web surfaces are outside this public workflow. The agent can infer title/tags from the HTML; after review, the dashboard can create an unlisted share. New public-gallery publishing is currently disabled. ### Hosted web export example ```javascript const create = await fetch("/api/web-export/jobs", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ fileName: "studio-export.pptx", html: document.querySelector("#slides-root").innerHTML, css: ".slide { width: 1600px; height: 900px; }", }), }); const queued = await create.json(); console.log("Hosted web export job:", queued.jobId); ``` --- ## Use Cases html2pptx.app is designed for automated, repeatable slide generation. Here are the most common integration patterns: ### Automated Quarterly Reports Generate quarterly performance decks from live data. Pull metrics from your database, format them as slide HTML with charts and KPI cards, and export via the API. Schedule with cron or trigger from your BI pipeline, with validation and output review before distribution. ```javascript const slides = quarterly_data.map((quarter, i) => `

Q${i+1} Results

Revenue

${quarter.revenue}

Growth

${quarter.growth}%

`).join("\n"); const resp = await fetch("/api/export/jobs", { method: "POST", headers: { "Authorization": "Bearer sk_live_xxxx", "Content-Type": "application/json" }, body: JSON.stringify({ fileName: "q-report.pptx", html: slides }), }); ``` ### Sales Proposal Templates Define brand-compliant slide templates in HTML/CSS once, then populate them with dynamic content for each campaign or client pitch. Variables like company name, project details, and pricing are injected at generation time. Marketing teams maintain the templates; teams review exported decks for brand and layout consistency before use. ```javascript // Sales proposal template with dynamic client data function generateProposal(client) { return `

${client.companyName} 御中

ご提案書 - ${client.projectName}

${new Date().toLocaleDateString('ja-JP')} | Confidential

提案概要

${client.features.map(f => `

${f.title}

${f.description}

`).join('')}
`; } ``` ### Agent-Powered Presentations Let AI agents create presentation decks from meeting notes, research summaries, or project briefs. Using Skills or MCP integration, the agent understands the html2pptx.app HTML contract, generates compliant slides, and delivers a download link. Users simply describe what they want in natural language. ### SaaS Export Embedding Add "Export to PowerPoint" functionality to your SaaS product. Render your app's dashboards, analytics views, or reports as slide HTML and call the html2pptx.app API from your backend. Users get native PPTX files with editable text and shapes -- not flat screenshots. ```javascript // Backend route: POST /api/dashboard/export-pptx app.post("/api/dashboard/export-pptx", async (req, res) => { const { dashboardId } = req.body; const dashboard = await getDashboard(dashboardId); // Render each widget as a slide const slides = dashboard.widgets.map(widget => `

${widget.title}

${widget.renderToHTML()}
`).join(""); // Call html2pptx.app API const job = await fetch(process.env.HTML2PPTX_API_URL + "/api/export/jobs", { method: "POST", headers: { "Authorization": `Bearer ${process.env.HTML2PPTX_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ fileName: `${dashboard.name}.pptx`, html: slides, }), }); const { jobId } = await job.json(); res.json({ jobId, statusUrl: `/api/export/jobs/${jobId}` }); }); ``` --- ## Plans & Pricing Choose the plan that fits your usage. The current public catalog is defined in code and enforced in the API gateway: requests per minute, daily guardrails, maximum slides per job, concurrent jobs, API key count, and payload size all vary by plan. | Plan | Exports | Slides/Job | Support | Price | |------|---------|-----------|---------|-------| | Free Preview | 10 per month / 3 rpm | 20 per job | Community | ¥0 | | Founder Beta | 300 per month / 5 rpm | 50 per job | Self-serve | ¥980/mo | | Starter | 3,000 per month / 15 rpm | 100 per job | Email | ¥2,980/mo | | Business | 20,000 per month / 60 rpm | 200 per job | Priority | ¥9,800/mo | | Enterprise / OEM | Custom | 500+ per job | Dedicated | ¥49,800/mo〜 | Upgrade anytime from the Dashboard. Changes take effect immediately with prorated billing. Downgrade at the end of the current billing period. --- ## Security & Limits Public API, Skills, MCP, Studio, and hosted web export are all routed through the same security-sensitive conversion pipeline. The practical controls below are the ones that matter when you integrate or expose the product. ### Authentication and authorization REST API uses API keys. Remote MCP supports commercial API keys or WorkOS-backed authenticated sessions. Job lookup is bound to the same API key or authenticated principal that created the job. ### SVG and untrusted markup Public API and MCP sanitize incoming HTML. Inline SVG is converted to PNG images for reliable output. ### Worker isolation Export jobs run in isolated contexts with enforced request body limits and automatic cleanup of expired jobs. ### Usage controls Per-minute rate limiting, daily guardrails, monthly fair-use review thresholds, maximum slides per job, maximum payload size, and concurrent job limits are all enforced server-side based on the active plan. ### Recommended production practices - Treat API keys as secrets and rotate them from the dashboard when they are exposed. - Use the REST API for backend automation and same-origin hosted web export only for first-party browser flows. - Poll the public job status route with backoff instead of hammering the status endpoint. - Keep slide markup deterministic: explicit slide dimensions, predictable CSS, and no runtime-dependent content. 1600x900 remains the default example. - MCP embeds completed PPTX files only up to 2 MiB. Larger files—including explicit responseFormat: "base64" or "both" requests—return a signed download URL plus a machine-readable warning instead of an oversized response. - Remote /mcp accepts at most 32 JSON-RPC messages and one tools/call message per authenticated HTTP POST. Send additional tool calls separately so the server can enforce the correct per-operation rate limit. - For agent integrations, decide whether the client should use local stdio MCP or remote /mcp before rollout. --- ## FAQ ### How is html2pptx.app different from other HTML-to-PPTX solutions? html2pptx.app maps supported text, simple shapes, tables, and CSS properties to PowerPoint objects instead of rendering every slide as one screenshot. Inline SVGs, icons, and some complex lists are rasterized. Output follows the published HTML contract and should be visually reviewed after export. ### Can I convert any HTML to PPTX? Not reliably. html2pptx.app is optimized for slide-oriented HTML with .slide class elements and explicit dimensions. 1600x900 is the default example, but portrait and other custom sizes are also supported. Arbitrary web pages, interactive apps, scroll-based layouts, and pages with JavaScript-dependent rendering are not supported. The HTML contract section describes the exact requirements. ### What becomes a separate slide? Each element with the .slide class becomes one slide in the output PPTX. If your HTML contains 5 elements with class="slide", the output will have 5 slides. Define clear slide boundaries for predictable results. ### Will exported content remain editable in PowerPoint? Supported text becomes editable PowerPoint text boxes, and supported simple shapes remain adjustable. Inline SVGs, detected icons, and some complex structures are exported as images, so those parts are not editable as text or vectors. ### How long does export take? Export time varies with slide count, layout complexity, and image processing. Poll the job status endpoint with a plan-safe interval, honor Retry-After after a 429 response, and stop when the job reaches completed or failed. ### Which fonts are supported? System fonts such as Arial, Helvetica, and Times New Roman can be used when available in the renderer and target PowerPoint environment. Public REST removes @font-face rules and blocks external font downloads, so autoEmbedFonts does not fetch Google Fonts or arbitrary web-font URLs on this path. Use a suitable font stack and verify substitutions, glyph coverage, and wrapping. ### Is there a free plan? Yes. Free Preview includes one API key and up to 10 exports per month, with limited API, Skills, and MCP usage. Check GET /api/export/plans for the current plan metadata because limits are enforced from code and may evolve. ### Can I use SVGs in my slides? Yes. Inline SVG is supported and converted to a PNG image. Review the generated PPTX in the target PowerPoint environment because rendering and image scaling can vary. ### What is the maximum file size? The HTML payload should stay under 5MB. Generated PPTX files vary by content but typically range from 100KB to 10MB. Jobs with many high-resolution images embedded as base64 will produce larger files. Consider using URL references for large images. ### How secure is the service? html2pptx.app implements multiple security layers: jobs are bound to the creating principal; API keys are hashed at rest; request body limits and concurrent job limits are enforced server-side. Use the REST API for server-side automation and treat hosted web export as a browser surface. ### Does html2pptx.app support Japanese text and CJK characters? Japanese, Chinese, and Korean text is supported. Specify a CJK font stack in CSS (for example, font-family: "Noto Sans JP", sans-serif) and verify glyph coverage and line wrapping in the target PowerPoint environment because installed fonts and metrics can differ. ### How do I handle errors? Check the job status endpoint. If status is "failed", the error or message field contains a human-readable description. Commercial export errors use RFC 9457 Problem Details fields plus legacy error and message fields; some legacy and creator endpoints return a smaller JSON error object. Common issues: missing .slide elements (400), invalid or missing API key (401/403), rate limit exceeded (429), and oversized content (413). ### Can I use CSS Grid for complex slide layouts? The supported CSS Grid subset includes grid-template-columns, grid-template-rows, gap, and grid placement properties. Use explicit slide dimensions and inspect the exported PPTX, because complex browser layouts or unsupported property combinations may render differently. ### Is there a webhook for job completion? Yes. Add callbackUrl (HTTPS only) to POST /api/export/jobs. The notification contains jobId/status plus fileName on success or message on failure, but it is only a delivery hint. No customer-verifiable webhook signing contract is currently exposed, so treat the callback as unauthenticated and fetch the complete result from the authenticated GET /api/export/jobs/{jobId}. Keep status polling as the source of truth, use a plan-safe interval, and honor Retry-After after 429 responses. MCP users can use html2pptx_wait_for_export_job for interval polling; transport and rate-limit errors are returned to the caller. --- ## Troubleshooting | Issue | Solution | |-------|----------| | Job stuck in "queued" status | The private worker may be offline or overloaded. Wait 30 seconds and retry. If persistent, check worker health from the Dashboard or contact support. | | Slides appear blank | Ensure your HTML contains elements with class="slide" and that those elements have visible content. Also verify that CSS is included in the payload and not relying on external stylesheets. | | Fonts look different in PPTX | Public REST does not fetch external web fonts. Use a font stack available in both the renderer and target PowerPoint environment, then inspect substitutions and wrapping. | | 429 Rate limit error | Honor the Retry-After header when present and increase the interval between status requests. Upgrade your plan if the documented request limits are too low. | | Layout differs from browser preview | Use explicit dimensions on .slide elements with inline styles. 1600x900 is the default example, but custom aspect ratios also work when your slide HTML and requested width/height/layout match. Avoid responsive/percentage-based layouts, media queries, and viewport-relative units (vh, vw). | | Images not appearing in PPTX | Use absolute URLs (https://...) or base64 data URIs for images. Relative paths and localhost URLs will fail. Ensure image URLs are publicly accessible from the worker. | | PPTX file size is too large | Large files are usually caused by embedded base64 images or image-heavy content. Use URL references instead, or compress images before embedding. | --- ## Public website pages - [html2pptx.app](https://html2pptx.app): Convert supported HTML and CSS into PowerPoint, with supported text and shapes remaining editable and selected visual elements exported as images. - [Pricing](https://html2pptx.app/pricing): Compare html2pptx.app plans, usage limits, and commercial options. - [PowerPoint to HTML](https://html2pptx.app/pptx-to-html): Convert a PowerPoint file into editable HTML in the browser. - [PowerPoint Templates](https://html2pptx.app/templates): Browse HTML/CSS-generated PowerPoint templates whose supported text and shapes remain editable while selected visual elements are rasterized. - [HTML Template Draft Guide](https://html2pptx.app/templates/publish): Learn how remote MCP validates HTML and creates a creator-owned draft for unlisted sharing; new public-gallery publishing is currently disabled. - [Creator Rewards](https://html2pptx.app/creator-rewards): Read how eligible usage of existing published templates is measured and reviewed for creator rewards. - [Release Notes](https://html2pptx.app/releases): Review html2pptx.app product updates, improvements, and bug fixes. - [Privacy Policy](https://html2pptx.app/privacy): Read the html2pptx.app privacy policy. - [Terms of Service](https://html2pptx.app/terms): Read the html2pptx.app terms of service. - [Commercial Transactions Disclosure](https://html2pptx.app/tokushoho): Read the legally required commercial transactions disclosure. - [Open-source Licenses](https://html2pptx.app/licenses): Review open-source license notices used by html2pptx.app. - Canonical docs: https://html2pptx.app/docs/en - OpenAPI spec: https://html2pptx.app/api/openapi.json - MCP endpoint: https://html2pptx.app/mcp - Short llms.txt: https://html2pptx.app/llms.txt *Generated from html2pptx.app documentation. For the latest version, visit https://html2pptx.app/docs/en*