PPTX.gallery
getting-startedapipowerpoint

Overview

The pptx.dev API lets you generate .pptx files programmatically with a single HTTP request. This guide walks you through making your first API call and building a complete presentation.

Prerequisites

  • A pptx.dev API key (get one free)
  • Any HTTP client (curl, fetch, Python requests, etc.)

Step 1: Authenticate

This generation endpoint requires a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Step 2: Pick Your Building Blocks

Every presentation is composed of building blocks from the pptx.gallery:

Block What it controls
Layout Slide structure and content zones
Color scheme Brand colors across all slides
Font scheme Heading and body typefaces
Narrative Story arc (intro → insight → call-to-action)
Theme Combined color + font preset

Browse the gallery to find the slugs you need before writing your request body.

Step 3: Make Your First API Call

curl --fail-with-body --show-error --output presentation.pptx \
  -X POST https://api.pptx.dev/v1/generate \
  -H "Authorization: Bearer $PPTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Q1 Business Review",
  "slides": [
    {
      "layout": "cover",
      "title": "Q1 Business Review",
      "subtitle": "January – March 2026"
    },
    {
      "layout": "text",
      "title": "Key Highlights",
      "blocks": [
        {
          "text": "Revenue up 24% YoY"
        },
        {
          "text": "NPS score: 72"
        }
      ]
    }
  ],
  "narrative": "problem-solution",
  "design": {
    "colorScheme": "corporate-blue",
    "fontScheme": "aptos"
  },
  "catalogs": {
    "default": {
      "source": "https://www.pptx.gallery",
      "narratives": {
        "problem-solution": {
          "name": "Problem → Solution",
          "summary": "Classic business arc: name the pain, raise the stakes, present your fix, show how it works, prove it, ask. The default for sales decks, internal proposals, and most general business presentations.",
          "audienceFit": [
            "customers",
            "stakeholders",
            "executives",
            "internal-teams"
          ],
          "duration": {
            "min": 5,
            "max": 30
          },
          "tags": [
            "business",
            "sales",
            "general",
            "proposal"
          ],
          "beats": [
            {
              "id": "hook",
              "name": "Hook",
              "description": "Open with a striking question, statistic, customer quote, or moment that earns the audience'\''s attention. The goal is to make them want to hear what comes next, not to convey information.",
              "layout": "cover"
            },
            {
              "id": "problem",
              "name": "The Problem",
              "description": "Name the pain in concrete terms. Make it visceral and specific — describe who hurts, how, and what they'\''re trying to do today that isn'\''t working. Avoid abstractions; use real examples or scenarios the audience recognizes."
            },
            {
              "id": "stakes",
              "name": "Why It Matters",
              "description": "Quantify the cost of inaction or the upside of action. Use numbers, trends, customer impact, competitive pressure — whatever makes the audience feel the size of the problem and care about solving it now rather than later."
            },
            {
              "id": "solution",
              "name": "The Solution",
              "description": "Reveal your approach and what it produces for the customer. Lead with the outcome, not the architecture. Keep it concrete: what does the audience get, and what changes for them?"
            },
            {
              "id": "mechanism",
              "name": "How It Works",
              "description": "Show the moving parts that make the solution credible. Walk through the key mechanism, workflow, or technical insight that explains why this approach succeeds where others have failed. Enough detail to earn trust; not so much that you lose the room."
            },
            {
              "id": "evidence",
              "name": "Proof",
              "description": "Demonstrate the solution works. Use customer logos, before/after metrics, demos, case studies, third-party validation — whatever de-risks the claim. One strong piece of proof beats three weak ones."
            },
            {
              "id": "ask",
              "name": "The Ask",
              "description": "State a clear, specific call to action. What do you want the audience to do, decide, or commit to next? Make the smallest credible ask that moves things forward, and make it unambiguous.",
              "layout": "cover"
            }
          ]
        }
      },
      "colorSchemes": {
        "corporate-blue": {
          "name": "Corporate Blue",
          "summary": "Legacy corporate blue palette for conservative business contexts.",
          "description": "A classic corporate blue scheme with strong contrast and familiar PowerPoint-era business cues.",
          "accent1": "#015DFE",
          "accent2": "#0100A6",
          "accent3": "#02ACFF",
          "accent4": "#94A1B2",
          "accent5": "#E3ECF3",
          "accent6": "#5A82FC",
          "dark1": "#000000",
          "dark2": "#011842",
          "light1": "#FFFFFF",
          "light2": "#F3F7FF",
          "hyperlink": "#0563C1",
          "followedHyperlink": "#954F72",
          "tags": [
            "corporate",
            "stable",
            "trustworthy",
            "conservative",
            "professional"
          ]
        }
      },
      "fontSchemes": {
        "aptos": {
          "name": "Aptos",
          "major": "Aptos Display",
          "minor": "Aptos",
          "type": "sans-serif",
          "app": "powerpoint",
          "languageFamily": "latin",
          "languages": [],
          "textSample": "Modern clean design",
          "description": "Aptos is a sans serif OPF font scheme for Latin presentations, using Aptos Display for headings with Aptos for body text."
        }
      },
      "layouts": {
        "cover": {
          "name": "Cover",
          "summary": "The opening slide: title, subtitle and an optional picture.",
          "tags": [
            "Openers and closers"
          ],
          "design": {
            "titleAlignment": "center",
            "contentAlignment": "center"
          },
          "direction": "row",
          "regions": [
            {
              "name": "title"
            },
            {
              "name": "media",
              "accepts": [
                "image",
                "video"
              ],
              "role": "media",
              "flow": "none",
              "bleed": true
            }
          ],
          "description": "Open a presentation with its subject and a short introduction. Add a picture when it helps establish the context.",
          "preview": {
            "vectorSrc": "https://www.pptx.gallery/layout-previews/cover.svg"
          }
        },
        "text": {
          "name": "Text",
          "summary": "Prose. Several blocks sit side by side when short and stack when long.",
          "tags": [
            "Text"
          ],
          "direction": "column",
          "regions": [
            {
              "name": "title"
            },
            {
              "name": "body",
              "accepts": [
                "text",
                "list",
                "quote",
                "code",
                "group"
              ],
              "role": "primary",
              "flow": "auto"
            }
          ],
          "description": "Explain one idea in continuous prose. Use paragraphs or flowing blocks for detail that needs to be read in sequence.",
          "preview": {
            "vectorSrc": "https://www.pptx.gallery/layout-previews/text.svg"
          }
        }
      }
    }
  }
}'

The request body is the complete OPF document, not a wrapper with a topic or slide count. References come from embedded records or the host's registered Gallery catalog; the API does not fetch catalog URLs from the document.

Step 4: Read the Response

A successful response has the PowerPoint MIME type and contains the file bytes. The command above saves those bytes directly as presentation.pptx; there is no second download-URL request. Inspect the exit status before opening the file: with --fail-with-body, a non-2xx response contains the API's JSON error instead of a presentation.

Authentication and hosted generation are separate from local OPF editing. A valid key is required; an insufficient hosted wallet returns 402, and an invalid document returns 422. Those error responses contain JSON, not a PowerPoint presentation. Keep your original OPF and review the exported file in your target application.

Step 5: Integrate into Your App

Node.js

import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.pptx.dev/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PPTX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My Presentation",
    slides: [{ title: "Hello World", subtitle: "Generated from portable OPF" }],
  }),
});
if (!response.ok) {
  throw new Error(`Generation failed (${response.status}): ${await response.text()}`);
}
await writeFile("presentation.pptx", new Uint8Array(await response.arrayBuffer()));

Python

import os
from pathlib import Path
import requests

response = requests.post(
    "https://api.pptx.dev/v1/generate",
    headers={"Authorization": f"Bearer {os.environ['PPTX_API_KEY']}"},
    json={
        "name": "My Presentation",
        "slides": [{"title": "Hello World", "subtitle": "Generated from portable OPF"}],
    },
    timeout=60,
)
response.raise_for_status()
Path("presentation.pptx").write_bytes(response.content)

Keep the API key on your server. Other articles provide OPF bodies or data builders that you can substitute into this request; preserve its authentication, status handling, and binary response handling.

Next Steps

← Back to How-To Guides