Overview

Images make presentations more engaging and memorable. The pptx.dev API supports one, two, and three-image layouts with crop and fit options, plus image backgrounds behind any layout.

Image Layout Types

Single Image (1x)

Two Images (2x)

Three Images (3x)

Crop vs. Fit

• Crop fills the entire image frame, cutting off edges if the aspect ratio does not match. Best for photos and visual content.
• Fit scales the image to fit inside the frame with no cropping. Best for logos, diagrams, and screenshots.

Use the OPF Image Treatments catalog when you need to choose the presentation behavior around the image, such as Rounded Card, Caption Overlay, or Collage Grid.

Example: Photo Gallery Slide

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Our Offices Around the World",
  "slides": [
    {
      "layout": "gallery",
      "title": "Our Offices Around the World",
      "blocks": [
        {
          "image": {
            "src": "https://example.com/office-nyc.jpg",
            "alt": "New York"
          }
        },
        {
          "image": {
            "src": "https://example.com/office-london.jpg",
            "alt": "London"
          }
        },
        {
          "image": {
            "src": "https://example.com/office-tokyo.jpg",
            "alt": "Tokyo"
          }
        }
      ],
      "design": {
        "titleAlignment": "center",
        "contentAlignment": "center"
      }
    }
  ],
  "catalogs": {
    "default": {
      "source": "https://www.pptx.gallery",
      "layouts": {
        "gallery": {
          "name": "Gallery",
          "summary": "One to six framed pictures: a screenshot, a diagram, a photo set.",
          "tags": [
            "Visuals"
          ],
          "direction": "column",
          "regions": [
            {
              "name": "title"
            },
            {
              "name": "pictures",
              "accepts": [
                "image",
                "video",
                "group"
              ],
              "role": "media",
              "flow": "grid"
            }
          ],
          "description": "Show several related visuals together. Use consistent captions and ordering to make the relationship between them clear.",
          "preview": {
            "vectorSrc": "https://www.pptx.gallery/layout-previews/gallery.svg"
          }
        }
      }
    }
  }
}

Example: Full-Bleed Image Slide

A slide that is entirely an image is a slide with an image background and no layout (fit defaults to cover):

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Presentation example",
  "slides": [
    {
      "design": {
        "background": {
          "type": "image",
          "src": "https://example.com/hero-shot.jpg"
        }
      }
    }
  ]
}

Background Images

Any layout can sit on an image background: the slide's (or the deck's) design.background with "type": "image" places a photo behind your content without moving it. This works on title, text, number, and list layouts alike:

{
  "$schema": "https://openpresentation.org/schema/opf/v1",
  "name": "Welcome",
  "slides": [
    {
      "layout": "cover",
      "title": "Welcome",
      "subtitle": "Annual Conference 2026",
      "design": {
        "titleAlignment": "center",
        "background": {
          "type": "image",
          "src": "https://example.com/conference-stage.jpg"
        }
      }
    }
  ],
  "catalogs": {
    "default": {
      "source": "https://www.pptx.gallery",
      "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"
          }
        }
      }
    }
  }
}

Image Best Practices

1. Use high-resolution images. At least 1920x1080 for background images and 800x600 for content images.
2. Prefer landscape orientation for most slide layouts since slides are wider than they are tall.
3. Use crop mode for photos and fit mode for diagrams or logos.
4. Host images on fast CDNs. The API fetches images at generation time, so slow image URLs slow down your request.

Next Steps

• Combine images with text layouts
• Add data overlays with chart slides
• Browse image layouts and Image Treatments in the gallery