Template Management

Overview

Templates define the visual design and layout structure of your presentations. Each template contains multiple layouts (e.g., Title Slide, Content Slide, Section Header) that the AI uses to place content.

List Templates

Endpoint: GET /templates/ List all templates available to your account. Request:

curl -X GET "https://poe.poesius.com/api/v1/templates/?limit=50&offset=0" \
  -H "X-API-Key: pk_your_api_key"

Query Parameters:

limit (integer, optional): Maximum number of templates to return (default: 50, max: 100)
offset (integer, optional): Pagination offset (default: 0)

Response:

{
  "templates": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Professional Blue",
      "description": "Corporate presentation template",
      "processing_status": "completed",
      "total_layouts": 15,
      "is_default": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "default_template_id": "123e4567-e89b-12d3-a456-426614174000"
}

Get Default Template

Endpoint: GET /templates/default Get your current default template. Request:

curl -X GET "https://poe.poesius.com/api/v1/templates/default" \
  -H "X-API-Key: pk_your_api_key"

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Professional Blue",
  "description": "Corporate presentation template",
  "processing_status": "completed",
  "total_layouts": 15,
  "is_default": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

If no default template is set, returns null.

Set Default Template

Endpoint: POST /templates/{template_id}/set-default Set a template as your default. The default template will be used automatically when no template_id is specified in slide generation requests. Request:

curl -X POST "https://poe.poesius.com/api/v1/templates/123e4567-e89b-12d3-a456-426614174000/set-default" \
  -H "X-API-Key: pk_your_api_key"

Alternative Method: POST /templates/default

curl -X POST "https://poe.poesius.com/api/v1/templates/default" \
  -H "X-API-Key: pk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Professional Blue",
  "description": "Corporate presentation template",
  "processing_status": "completed",
  "total_layouts": 15,
  "is_default": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Get Template Details

Endpoint: GET /templates/{template_id} Get detailed information about a specific template. Request:

curl -X GET "https://poe.poesius.com/api/v1/templates/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: pk_your_api_key"

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Professional Blue",
  "description": "Corporate presentation template",
  "processing_status": "completed",
  "total_masters": 2,
  "total_layouts": 15,
  "is_default": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Using Templates in Slide Generation

When generating slides, you can specify a template in two ways:

1. Use Default Template

If you have set a default template, simply omit the template_id parameter:

curl -X POST "https://poe.poesius.com/api/v1/slides/generate-from-doc" \
  -H "X-API-Key: pk_your_api_key" \
  -F "document=@document.pdf" \
  -F "num_slides=15"

2. Specify Template ID

curl -X POST "https://poe.poesius.com/api/v1/slides/generate-from-doc" \
  -H "X-API-Key: pk_your_api_key" \
  -F "document=@document.pdf" \
  -F "num_slides=15" \
  -F "template_id=123e4567-e89b-12d3-a456-426614174000"

Template Editing and Layout Zones

Important: Template editing, including layout zone definitions, must be done visually through the web platform at https://app.poesius.com.

What are Layout Zones?

Layout zones define the boundaries where the AI places slide content. Each layout in a template has multiple zones (e.g., TITLE, CONTENT, FOOTER, LEFT_CONTENT, RIGHT_CONTENT) that specify:

Bounding boxes: Where content can be placed (as percentages of slide dimensions)
Background colors: Visual styling for each zone
Text colors: Font colors that work with zone backgrounds
Layout structure: How zones are arranged (horizontal, split-screen, single frame)

Why Zone Definition Matters

The AI relies on these zone definitions to:

Place content in the correct areas of each slide
Match text colors to zone backgrounds (e.g., white text on dark zones)
Respect visual boundaries and avoid overlapping decorative elements
Maintain consistent styling across slides

Editing Templates

Upload Template: Upload your PowerPoint template file (.pptx) through the web app
Process Template: The system automatically extracts layouts and creates initial zone definitions
Edit Zones (Visual): Use the web platform’s visual editor to:
- Adjust zone boundaries to match your design
- Define zone descriptions (e.g., “Main title slide layout”, “Section divider”, “Normal content slide”)
- Ensure zones cover the maximum usable space without overlapping graphics
- Set proper text colors for each zone background

Layout Descriptions

Each layout should have a clear description that helps the AI understand its purpose:

Title Slide Layout: “Main title slide with large title area and subtitle”
Section Header: “Section divider slide with centered title”
Content Slide: “Standard content slide with title and main content area”
Two-Column: “Split-screen layout with left and right content areas”

These descriptions help the AI select the appropriate layout for each slide type.

One-Time Setup

Zone definition is a one-time job done visually on the web platform. Once zones are properly defined:

The AI will use them automatically for all future slide generation
No API calls are needed to modify zones
Changes to zones require re-editing through the web interface

Best Practices

Set a Default Template: Use POST /templates/{id}/set-default to avoid specifying template_id in every request
List Templates First: Use GET /templates/ to see available templates before generating slides
Template Processing: New templates may need processing time. Check processing_status before use
Zone Definitions: Ensure zones are properly defined in the web platform for best AI content placement

Web Platform

Edit templates and define layout zones visually

Getting started

API Usage

MCP Usage

Templates & Configuration

Examples

Error Handling

Overview

List Templates

Get Default Template

Set Default Template

Get Template Details

Using Templates in Slide Generation

1. Use Default Template

2. Specify Template ID

Template Editing and Layout Zones

What are Layout Zones?

Why Zone Definition Matters

Editing Templates

Layout Descriptions

One-Time Setup

Best Practices

Web Platform

​Overview

​List Templates

​Get Default Template

​Set Default Template

​Get Template Details

​Using Templates in Slide Generation

​1. Use Default Template

​2. Specify Template ID

​Template Editing and Layout Zones

​What are Layout Zones?

​Why Zone Definition Matters

​Editing Templates

​Layout Descriptions

​One-Time Setup

​Best Practices

Web Platform

Overview

List Templates

Get Default Template

Set Default Template

Get Template Details

Using Templates in Slide Generation

1. Use Default Template

2. Specify Template ID

Template Editing and Layout Zones

What are Layout Zones?

Why Zone Definition Matters

Editing Templates

Layout Descriptions

One-Time Setup

Best Practices