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 background slide images on almost any layout.
Image Layout Types
Single Image (1x)
| Layout | Description |
|---|---|
image-1x-crop |
Single image, cropped to fill the frame |
image-1x-fit |
Single image, scaled to fit without cropping |
image-1x-crop-title-left |
Cropped image with a left-aligned title |
image-1x-fit-title-center |
Fitted image with a centered title |
image-only-crop |
Full-bleed image slide, no text |
image-only-fit |
Full-bleed fitted image, no text |
Two Images (2x)
| Layout | Description |
|---|---|
image-2x-crop |
Two cropped images side by side |
image-2x-fit |
Two fitted images side by side |
image-2x-crop-vertical |
Two cropped images stacked vertically |
Three Images (3x)
| Layout | Description |
|---|---|
image-3x-crop |
Three cropped images in a row |
image-3x-fit |
Three fitted images in a row |
image-3x-crop-vertical |
Three cropped images stacked |
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
{
"layout": "image-3x-crop-title-center",
"content": {
"heading": "Our Offices Around the World",
"items": [
{
"image": "https://example.com/office-nyc.jpg",
"caption": "New York"
},
{
"image": "https://example.com/office-london.jpg",
"caption": "London"
},
{
"image": "https://example.com/office-tokyo.jpg",
"caption": "Tokyo"
}
]
}
}
Example: Full-Bleed Image Slide
For a slide that is entirely an image with no text:
{
"layout": "image-only-crop",
"content": {
"image": "https://example.com/hero-shot.jpg"
}
}
Background Images (Slide Images)
Most layouts support a slideImage field that places a background image behind your content. This works on title, text, number, and list layouts:
{
"layout": "title-center-slideimage",
"content": {
"heading": "Welcome",
"subheading": "Annual Conference 2026",
"slideImage": "https://example.com/conference-stage.jpg"
}
}
Image Best Practices
- Use high-resolution images. At least 1920x1080 for background images and 800x600 for content images.
- Prefer landscape orientation for most slide layouts since slides are wider than they are tall.
- Use crop mode for photos and fit mode for diagrams or logos.
- 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