Presentation Generation

Generation turns an analyzed template slide into a real .pptx. The template provides the visual system. Your request provides the content, the layout payload, and any overrides you want to apply.

Run template analysis first. Generation uses each slide’s analyzed slideId as template_slide_id.

1. Supported Layouts

Layouts describe how content is arranged on the slide. Your template should contain a slide that structurally matches one of these patterns.

Layout	Payload shape
Title / text slide	`title`, `subtitle`, optional text blocks
Single table	One `table` block
Table + text	One `table` block plus one or more `text` blocks
Single chart	One `chart` block
Agenda	One `agenda` block
Two-column table + chart	`content` as two columns; one side table, one side chart
Two-column table + table	`content` as two columns; both sides table

Do not use a two-column content array for arbitrary layouts. The current renderer routes two-column content for table + chart and table + table layouts; chart + chart and text + text are not treated as distinct left/right content regions. The sections below describe the content blocks used inside those layouts.

2. Content Blocks

Content blocks are the JSON objects placed inside slide_data.content.blocks. Use them to fill the matching regions in a template slide.

Block	Use it for	Details
`text`	Section headers, paragraphs, bullets, and supporting copy	Text Blocks
`table`	Row-and-column data, logos, table styling, conditional formatting, and pagination	Table Blocks
`chart`	Bar and column charts with categories, series, axes, legends, labels, and data rows	Chart Blocks
`agenda`	Agenda slides with section labels and an active section	Slide Input

For a single-column layout, content is one column object:

{
  "content": {
    "blocks": [
      { "type": "text", "text": { "bullets": ["Point 1", "Point 2"] } }
    ]
  }
}

In a text block, bullets is an array of strings. Each string renders as one bullet paragraph in the matching text region. For a two-column layout, content is an array of column objects. The optional column header is only used by two-column templates that include header textboxes marked LHS_header and RHS_header, where LHS means left-hand side and RHS means right-hand side.

{
  "content": [
    {
      "header": "Renewal pipeline",
      "blocks": [
        { "type": "table", "table": { "table": { "rows": [] } } }
      ]
    },
    {
      "header": "ARR at risk",
      "blocks": [
        { "type": "chart", "chart": { "categories": [], "series": [] } }
      ]
    }
  ]
}

Table Blocks

Author table rows, dynamic columns, logos, reusable styles, conditional formatting, and pagination.

Chart Blocks

Author bar and column charts with series, axes, legends, labels, and data rows.

Text Blocks

Author slide text, text sections, bullets, and formatting overrides.

3. Template Inheritance

By default, generation inherits from the template. If you omit formatting fields, the renderer uses the fonts, sizes, colors, table styling, chart presets, placeholder positions, and master layouts already encoded in the .pptx. Use overrides only where the generated content needs to differ from the template.

If you send	Result
No formatting	Template styling is used wherever available
Partial formatting	Specified fields override; unspecified fields continue to inherit where supported
Full formatting	Payload controls that element’s font, size, color, emphasis, or cell styling

The common pattern is: let the template carry the brand, then override only data-driven styling such as status colors, risk flags, chart series colors, or one-off title sizing.

4. Generate Slides

There are two generation modes:

Mode	Endpoint	Use when
Single slide	`POST /api/v1/presentations/generate`	You need one logical slide generated as an async job
Deck	`POST /api/v1/presentations/generate-deck`	You need multiple slides in one `.pptx`

Both modes use the same slide object shape:

{
  "template_slide_id": "slide_a3f81c92",
  "slide_data": {},
  "options": {}
}

Field	What it controls
`template_slide_id`	Which analyzed template slide to clone and populate
`slide_data`	The content and optional formatting for that slide
`options`	Pagination, font-fit, footer, and slide-number behavior

For layout guidance, option fields, defaults, and deck inheritance rules, see Layout & Rendering Controls.

What you can specify in `slide_data`

Area	Fields
Slide text	`title`, `subtitle`, `footer`, `footnote`
Text blocks	Single-column: `content.blocks[].text.{header,text,bullets}`. Two-column: `content[].blocks[].text.{header,text,bullets}`
Text formatting	`slide_format.title`, `slide_format.subtitle`, `slide_format.body`, `slide_format.textbox.{header,text,bullets}`, plus text-block `header_format`, `text_format`, `bullets_format`
Tables	`rows`, `rows[].cells`, row `is_header`, cell `value`, cell `is_logo`, multi-paragraph or bullet cell values, `column_configs`
Table formatting	`table_format`, `format_templates`, `format_template` references from cells, paragraphs, or `column_configs[]`, conditional `rules`, text formatting, and cell formatting
Charts	Bar/column chart fields: `chart_type`, `categories`, `series[].{name,values,color}`, `title`, `title_format`, `legend`, `value_axis`, `category_axis`, `value_axis_unit`, `caption`, `show_bar_labels`, `bar_label_mode`, `bar_label_decimals`, `show_data_table`, `data_rows`, `data_table_header_column`, `data_table_format`
Agenda	`sections`, `active_index`, `active_font_color`, `active_bold`, `active_underline`

Formatting objects commonly accept:

{
  "font_name": "Arial",
  "font_size": 12,
  "bold": true,
  "italic": false,
  "color": "#333333",
  "alignment": "left",
  "line_spacing": 1.2
}

Generate One Slide

Use generate for one logical slide. The endpoint returns immediately with a generation_id; poll status until the generated file is ready.

Single-slide request example

POST /api/v1/presentations/generate
X-API-Key: your-api-key
Content-Type: application/json

{
  "template_slide_id": "slide_customer_health_table",
  "slide_data": {
    "title": "Customer Health Overview",
    "footnote": "Source: CRM export, April 2026",
    "slide_format": {
      "title": {
        "font_name": "Arial",
        "font_size": 30,
        "bold": true,
        "color": "#111827"
      }
    },
    "content": {
      "blocks": [
        {
          "type": "table",
          "table": {
            "table": {
              "format_templates": {
                "health_score": {
                  "rules": [
                    {
                      "condition": { "field": "value", "operator": "greater_than_or_equal", "value": 8 },
                      "cell": { "background_color": "#E7F4EE" },
                      "text": { "bold": true, "color": "#0F5132" }
                    },
                    {
                      "condition": { "field": "value", "operator": "less_than", "value": 6 },
                      "cell": { "background_color": "#FDECEC" },
                      "text": { "bold": true, "color": "#842029" }
                    }
                  ]
                }
              },
              "column_configs": [
                { "column_index": 2, "format_template": "health_score" }
              ],
              "rows": [
                {
                  "is_header": true,
                  "cells": [
                    { "value": "Company" },
                    { "value": "Owner" },
                    { "value": "Health" },
                    { "value": "Signal" },
                    { "value": "Next step" }
                  ]
                },
                {
                  "cells": [
                    { "value": "stripe.com", "is_logo": true },
                    { "value": "Sarah Chen" },
                    { "value": "9" },
                    { "value": "Expansion-ready" },
                    { "value": "Send pricing proposal" }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  },
  "options": {
    "auto_paginate_tables": true,
    "table_min_font_size": 8,
    "show_slide_numbers": true,
    "footer_text": "Confidential"
  }
}

Example response:

{
  "generation_id": "gen_def456",
  "status": "pending",
  "message": "Generation started. Poll status URL for progress.",
  "status_url": "https://api.example.com/api/v1/presentations/gen_def456/status",
  "created_at": "2026-04-30T17:35:00Z"
}

The final status response includes total_pages_generated, slide_results, file size, and a signed download_url. total_pages_generated can be greater than 1 when a table-only slide paginates.

Generate a Deck

Use generate-deck for multi-slide output. The endpoint returns immediately with a generation_id; poll status until the deck is ready. Slides render in the same order as the slides array. Each slide can use a different template_slide_id, including slides from different analyzed templates in the same organization.

Deck request example

POST /api/v1/presentations/generate-deck
X-API-Key: your-api-key
Content-Type: application/json

{
  "slides": [
    {
      "template_slide_id": "slide_cover",
      "slide_data": {
        "title": "Q2 2026 Portfolio Review",
        "subtitle": "Investment Committee Draft"
      }
    },
    {
      "template_slide_id": "slide_agenda",
      "slide_data": {
        "title": "Agenda",
        "content": {
          "blocks": [
            {
              "type": "agenda",
              "agenda": {
                "sections": [
                  "Portfolio snapshot",
                  "Customer health",
                  "Renewal outlook",
                  "Action plan"
                ],
                "active_index": 1,
                "active_bold": true,
                "active_underline": true
              }
            }
          ]
        }
      }
    },
    {
      "template_slide_id": "slide_chart_and_table",
      "slide_data": {
        "title": "Renewal Outlook by Cohort",
        "content": [
          {
            "header": "ARR at risk",
            "blocks": [
              {
                "type": "chart",
                "chart": {
                  "chart_type": "stacked_column",
                  "categories": ["Q2", "Q3", "Q4"],
                  "series": [
                    { "name": "Committed", "values": [18.2, 21.4, 24.1], "color": "#0F766E" },
                    { "name": "Upside", "values": [4.5, 3.9, 5.2], "color": "#2563EB" },
                    { "name": "At risk", "values": [2.1, 3.4, 2.8], "color": "#DC2626" }
                  ],
                  "show_bar_labels": true,
                  "value_axis_unit": "$M",
                  "legend": {
                    "position": "bottom",
                    "text_format": { "font_size": 8 }
                  },
                  "data_rows": [
                    ["Total ARR", "$24.8M", "$28.7M", "$32.1M"],
                    ["At-risk %", "8%", "12%", "9%"]
                  ],
                  "data_table_format": {
                    "font_name": "Arial",
                    "font_size": 8,
                    "color": "#333333"
                  }
                }
              }
            ]
          },
          {
            "header": "Management actions",
            "blocks": [
              {
                "type": "table",
                "table": {
                  "table": {
                    "table_format": {
                      "header_row": {
                        "text": { "bold": true, "font_size": 9 },
                        "cell": { "background_color": "#E5E7EB" }
                      },
                      "default": {
                        "text": { "font_size": 8 }
                      }
                    },
                    "rows": [
                      {
                        "is_header": true,
                        "cells": [
                          { "value": "Account group" },
                          { "value": "Action" },
                          { "value": "Owner" }
                        ]
                      },
                      {
                        "cells": [
                          { "value": "Executive sponsor gaps" },
                          { "value": "Schedule renewal risk review" },
                          { "value": "CS leadership" }
                        ]
                      },
                      {
                        "cells": [
                          { "value": "Q3 renewals" },
                          { "value": "Pull forward adoption readout" },
                          { "value": "Product strategy" }
                        ]
                      }
                    ]
                  }
                }
              }
            ]
          }
        ]
      },
      "options": {
        "auto_paginate_tables": false,
        "table_min_font_size": 7,
        "textbox_min_font_size": 8
      }
    }
  ],
  "options": {
    "auto_paginate_tables": true,
    "show_slide_numbers": true,
    "footer_text": "Confidential",
    "footer_font_size": 8,
    "footer_font_name": "Arial",
    "table_min_font_size": 8,
    "textbox_min_font_size": 8
  }
}

Example response:

{
  "generation_id": "gen_ghi789",
  "status": "pending",
  "message": "Generation started. Poll status URL for progress.",
  "status_url": "https://api.example.com/api/v1/presentations/gen_ghi789/status",
  "created_at": "2026-04-30T17:40:00Z"
}

Poll Status

GET /api/v1/presentations/{generation_id}/status
X-API-Key: your-api-key

Poll every 2 to 5 seconds until status is terminal.

Status	Meaning
`pending`	Request is queued
`processing`	Slides are being rendered
`completed`	Every requested slide succeeded
`partial`	Some slides succeeded and some failed
`failed`	No usable deck was generated

Completed example:

{
  "generation_id": "gen_ghi789",
  "status": "completed",
  "progress": 100,
  "message": "Generated 4 pages from 3/3 slides",
  "total_slides_requested": 3,
  "total_pages_generated": 4,
  "slide_results": [
    { "slide_index": 0, "template_slide_id": "slide_cover", "pages_generated": 1, "status": "completed", "error": null },
    { "slide_index": 1, "template_slide_id": "slide_agenda", "pages_generated": 1, "status": "completed", "error": null },
    { "slide_index": 2, "template_slide_id": "slide_chart_and_table", "pages_generated": 2, "status": "completed", "error": null }
  ],
  "file_size": 7450000,
  "download_url": "https://storage.example.com/download/gen_ghi789.pptx?token=...",
  "download_url_expires_in": 3600
}

Always inspect slide_results for async deck jobs. A partial result can still include a downloadable .pptx.

Download

Use the signed download_url when available. To download through the API instead:

GET /api/v1/presentations/{presentation_id}/download
X-API-Key: your-api-key

presentation_id can be either:

gen_xxx from slide generation
gen_xxx from deck generation
pres_xxx from older direct-return generation output, if present

For generation jobs, download is available after status is completed or partial.

Page Counts and Indexes

Pagination can make output slide counts differ from request slide counts:

total_slides_requested is the number of logical slides in the request.
total_pages_generated is the number of actual PowerPoint slides in the output file.
slide_results[].pages_generated tells you which logical slides expanded.
Chart update slide_index values refer to the output presentation, so paginated table-only slides can shift later indexes.

Table Blocks

Rows, cells, logos, reusable styles, conditional formatting, and pagination.

Chart Blocks

Chart types, categories, series, legends, axes, labels, and data rows.

Text Blocks

Slide text, text sections, bullets, and formatting overrides.

Slide Input

Full JSON shapes for text, tables, charts, agendas, and formatting.

Layout & Rendering Controls

Layout compatibility, aspect ratio, pagination, fitting, footers, and slide numbers.

Examples

Complete payloads for common slide and deck patterns.

Introduction

Template management

Generation

AI Agents

Security & Operations

Presentation Generation

Presentation Generation

1. Supported Layouts

2. Content Blocks

Table Blocks

Chart Blocks

Text Blocks

3. Template Inheritance

4. Generate Slides

What you can specify in `slide_data`

Generate One Slide

Generate a Deck

Poll Status

Download

Page Counts and Indexes

Table Blocks

Chart Blocks

Text Blocks

Slide Input

Layout & Rendering Controls

Examples

​Presentation Generation

​1. Supported Layouts

​2. Content Blocks

Table Blocks

Chart Blocks

Text Blocks

​3. Template Inheritance

​4. Generate Slides

​What you can specify in slide_data

​Generate One Slide

​Generate a Deck

​Poll Status

​Download

​Page Counts and Indexes

​Related Guides

Table Blocks

Chart Blocks

Text Blocks

Slide Input

Layout & Rendering Controls

Examples

Presentation Generation

1. Supported Layouts

2. Content Blocks

3. Template Inheritance

4. Generate Slides

What you can specify in `slide_data`

Generate One Slide

Generate a Deck

Poll Status

Download

Page Counts and Indexes

Related Guides