gslides-builder

Build Google Slides from Python. No EMU math. No field masks. Just inches and hex colors.

A zero-dependency Python library that converts simple JSON layouts into Google Slides API batchUpdate requests. Think of it as the PptxGenJS equivalent for Google Slides.

You describe slides in inches and hex colors. The library handles EMU conversion, field masks, nested color objects, transforms, and every API gotcha so you don't have to.

Installation

pip install gslides-builder

With optional Google API client (for executing requests directly):

pip install "gslides-builder[google]"

Quick Start

from google_slides_builder import SlideBuilder

builder = SlideBuilder()
requests = builder.build(layout={
    "slides": [
        {
            "background": {"color": "#1a1a2e"},
            "elements": [
                {
                    "type": "text",
                    "content": "Q4 Revenue Report",
                    "x": 1.0, "y": 2.0,
                    "width": 8.0, "height": 1.5,
                    "font_size": 36,
                    "color": "#FFFFFF",
                    "bold": True,
                    "alignment": "CENTER",
                }
            ]
        }
    ]
})

# `requests` is a list of dicts ready for the Google Slides API batchUpdate endpoint

Execute with Google API

from google_slides_builder import SlideBuilder
from google_slides_builder.client import GoogleSlidesClient

builder = SlideBuilder()
requests = builder.build(layout={...})

# Use your own Google credentials (OAuth2 or service account)
client = GoogleSlidesClient(credentials=creds)
presentation = client.create("Q4 Revenue Report", requests)
print(client.get_url(presentation))
# https://docs.google.com/presentation/d/abc123/edit

Features

Four Element Types

Text — single or multi-styled text boxes:

{
    "type": "text",
    "content": "Hello World",
    "x": 1.0, "y": 2.0, "width": 8.0, "height": 1.5,
    "font_size": 24, "color": "#2B579A", "font": "Montserrat",
    "bold": True, "alignment": "CENTER",
    "vertical_align": "MIDDLE", "background": "#F0F0F0",
}

Multi-styled text with runs:

{
    "type": "text",
    "x": 1.0, "y": 2.0, "width": 8.0, "height": 1.0,
    "runs": [
        {"text": "Revenue: ", "font_size": 18, "color": "#333333"},
        {"text": "$4.2M", "font_size": 18, "color": "#27AE60", "bold": True},
        {"text": " (+12% YoY)", "font_size": 14, "color": "#7F8C8D", "italic": True},
    ]
}

Table — with headers, alternating rows, and auto-splitting:

{
    "type": "table",
    "headers": ["Name", "Role", "Revenue"],
    "rows": [
        ["Alice Chen", "VP Sales", "$1.2M"],
        ["Bob Park", "Director", "$890K"],
        ["Carol Wu", "Manager", "$650K"],
    ],
    "x": 0.5, "y": 1.5, "width": 9, "height": 3,
    "header_bg": "#2C3E50", "header_color": "#FFFFFF",
    "alt_row_bg": "#F5F5F5", "font_size": 11,
    "col_widths": [3, 3, 2],
}

Tables that exceed the slide height automatically split across continuation slides with repeated headers and "(continued 2/3)" labels.

Shape — rectangles, ellipses, accent bars, badges:

{
    "type": "shape",
    "shape": "RECTANGLE",
    "x": 0, "y": 0, "width": 10, "height": 0.04,
    "fill": "#E74C3C",
    "outline": False,
}

Shapes can contain text that auto-shrinks to fit:

{
    "type": "shape",
    "shape": "ELLIPSE",
    "x": 4, "y": 2, "width": 2, "height": 2,
    "fill": "#3498DB",
    "content": "85%", "font_size": 28, "color": "#FFFFFF",
    "alignment": "CENTER",
}

Image — from any HTTPS URL:

{
    "type": "image",
    "url": "https://example.com/chart.png",
    "x": 1, "y": 1, "width": 4, "height": 3,
}

Smart Behaviors

Font Overrides

Enforce consistent typography across all elements:

requests = builder.build(
    layout=layout,
    font_overrides={"heading": "Montserrat", "body": "Open Sans"},
)

Headings (font_size >= 24pt) get the heading font; everything else gets the body font.

Background Variety

Prevent monotonous presentations by providing a color palette:

requests = builder.build(
    layout=layout,
    palette={"primary": "#1a1a2e", "background": "#f8f5f0"},
)

If >60% of slides share the same background, the builder automatically alternates with the palette colors.

Layout JSON Schema

The full input schema:

{
  "slides": [
    {
      "id": "optional_slide_id",
      "background": {
        "color": "#RRGGBB"
      },
      "elements": [
        {
          "type": "text | table | shape | image",
          ...
        }
      ]
    }
  ]
}

See docs/layout-schema.md for the complete reference.

How It Compares

When to Use This

• You want programmatic control over slide layout — not templates
• Your data drives the content — reports, dashboards, data pipelines
• You're building with AI/LLMs — feed JSON from GPT/Claude/Gemini, get slides
• You need zero dependencies — embed in Lambda, Cloud Functions, containers
• You want the Google Slides API without the pain — EMU math, field masks, nested objects

When NOT to Use This

• You want to fill placeholders in existing templates → use slidio
• You want pandas DataFrames as charts → use gslides
• You want PowerPoint (.pptx) output → use PptxGenJS or python-pptx

Examples

See the examples/ directory:

• 01_hello_world.py — minimal single-slide presentation
• 02_styled_deck.py — multi-slide deck with shapes, tables, images
• 03_from_data.py — generate slides from a data dictionary
• 04_with_google_api.py — full end-to-end with Google auth and execution

API Reference

SlideBuilder

from google_slides_builder import SlideBuilder

builder = SlideBuilder()
requests = builder.build(
    layout={"slides": [...]},           # Required: layout JSON
    font_overrides={"heading": ".."},   # Optional: enforce fonts
    palette={"primary": "#.."},         # Optional: background variety
    known_image_urls={"https://.."},    # Optional: verified image URLs
)

GoogleSlidesClient

from google_slides_builder.client import GoogleSlidesClient

client = GoogleSlidesClient(credentials=creds)

# Create new presentation
presentation = client.create("Title", requests)

# Update existing presentation
client.update(presentation_id, requests)

# Get presentation
pres = client.get(presentation_id)

# Get browser URL
url = client.get_url(presentation)

Need More Than Slides?

This library handles Google Slides. If you need automated branded documents across multiple formats, check out Formatix AI:

Formatix AI creates fully branded, custom document templates — DOCX, PowerPoint, Excel, and Google Slides — all automated. Upload a CV, get a pixel-perfect branded bio. Feed in data, get a board-ready presentation. Your brand guidelines applied automatically, every time.

Used by executive search firms, consultancies, and enterprises to generate thousands of branded documents.

Visit formatix.ai | Contact Dominic

Contributing

See CONTRIBUTING.md. PRs welcome.

License

Apache 2.0 — see LICENSE.

Built and maintained by Dominic Gonsalves at Formatix AI — automated branded document generation across DOCX, PPTX, XLSX, and Google Slides.