Overview

Every PowerPoint layout is built on placeholders — predefined zones where content goes. The pptx.dev API maps your JSON content to these placeholders automatically, so you get properly positioned text, images, and charts without manual layout work.

Placeholder Types

How the API Maps Content to Placeholders

When you send a slide definition, the API:

1. Reads the layout to determine which placeholders exist
2. Uses title, subtitle, and typed body payloads to fill the declared placeholders
3. Applies the color scheme and font scheme to style each placeholder
4. Renders the final slide

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Key Highlights",
  "slides": [
    {
      "layout": "text-2x-left",
      "title": "Key Highlights",
      "blocks": [
        {
          "text": "Revenue Growth\n\nRevenue increased 24% year-over-year."
        },
        {
          "text": "Market Expansion\n\nEntered three new European markets in Q1."
        }
      ]
    }
  ],
  "catalogs": {
    "layouts": {
      "records": [
        {
          "$schema": "https://openpresentation.org/schema/opf-layout/v1",
          "id": "text-2x-left",
          "name": "Text 2x Left",
          "placeholders": [
            {
              "type": "text"
            },
            {
              "type": "text"
            }
          ],
          "composition": {
            "mode": "row"
          }
        }
      ]
    }
  }
}

In this example:

• title fills the slide title.
• The first blocks entry supplies the first text region.
• The second entry supplies the second text region.

Multi-Item Layouts

Repeated content uses a blocks array. Each block supplies its own payload, such as metric, image, chart, or a list in items:

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Q1 Metrics",
  "slides": [
    {
      "layout": "number-3x-title-center",
      "title": "Q1 Metrics",
      "blocks": [
        {
          "metric": {
            "value": "$1.2M",
            "label": "Revenue"
          }
        },
        {
          "metric": {
            "value": "94%",
            "label": "Retention"
          }
        },
        {
          "metric": {
            "value": "72",
            "label": "NPS"
          }
        }
      ],
      "design": {
        "titleAlignment": "center",
        "contentAlignment": "center"
      }
    }
  ],
  "catalogs": {
    "layouts": {
      "records": [
        {
          "$schema": "https://openpresentation.org/schema/opf-layout/v1",
          "id": "number-3x-title-center",
          "name": "Number 3x Title Center",
          "placeholders": [
            {
              "type": "title"
            },
            {
              "type": "metric"
            },
            {
              "type": "metric"
            },
            {
              "type": "metric"
            }
          ],
          "composition": {
            "mode": "row"
          }
        }
      ]
    }
  }
}

The layout composition arranges those blocks in the declared row, column, or grid.

Image Placeholders

Image placeholders accept URLs. The API fetches the image at generation time and embeds it:

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Our New Office",
  "slides": [
    {
      "layout": "image-1x-crop-title-center",
      "title": "Our New Office",
      "image": "https://example.com/office-photo.jpg",
      "design": {
        "titleAlignment": "center",
        "contentAlignment": "center"
      }
    }
  ],
  "catalogs": {
    "layouts": {
      "records": [
        {
          "$schema": "https://openpresentation.org/schema/opf-layout/v1",
          "id": "image-1x-crop-title-center",
          "name": "Image 1x Crop Title Center",
          "placeholders": [
            {
              "type": "title"
            },
            {
              "type": "picture"
            }
          ]
        }
      ]
    }
  }
}

Slide Image vs. Content Image

• Slide image (slideImage) — full-bleed background behind all content
• Content image (image) — placed in a specific image placeholder on the slide

Use slide images for atmosphere. Use content images for specific visuals.

Tips

1. Match your content to the layout. A number-3x layout expects 3 items — sending 2 or 4 may not render as expected.
2. Check the gallery for each layout's placeholder map before writing your content.
3. Keep text short. Placeholders have fixed sizes — long text will be truncated or shrunk.

Next Steps

• Browse all layouts to see placeholder configurations
• Learn about title slides and their placeholders
• Explore image slides for visual content