Selecting Templates - Poesius API Documentation

Template Selection Flow

Step 1: List Available Templates

First, get the list of available templates:

{
  "method": "tools/call",
  "params": {
    "name": "list_templates",
    "arguments": {
      "limit": 50,
      "offset": 0
    }
  }
}

Step 2: Review Templates

Examine the response to see:

Template names
Available layouts
Thumbnail previews (if available)
Default template (if set)

Step 3: Choose a Template

Select a template_id from the response that matches your needs.

Step 4: Use in Generation

Provide the template_id in your generation request:

{
  "method": "tools/call",
  "params": {
    "name": "generate_slides",
    "arguments": {
      "topic": "My Presentation",
      "instructions": "Create slides",
      "template_id": "uuid-from-list-templates"
    }
  }
}

REST API Usage

For REST API, you can also specify templates:

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 "template_id=123e4567-e89b-12d3-a456-426614174000" \
  -F "num_slides=15"

Default Template

If your account has a default template, you can omit template_id:

{
  "method": "tools/call",
  "params": {
    "name": "generate_slides",
    "arguments": {
      "topic": "My Presentation",
      "instructions": "Create slides"
      // template_id omitted - uses default
    }
  }
}

Template Required Response

If no template_id is provided and there’s no default template, you’ll receive:

{
  "requires_template": true,
  "message": "Please select a template from the list below",
  "available_templates": [
    {
      "template_id": "uuid",
      "template_name": "Professional Blue"
    }
  ],
  "default_template_id": null
}

Solution: Call list_templates first, then provide a template_id in your request.

Layout Selection

You can also specify a specific layout for individual slides:

{
  "method": "tools/call",
  "params": {
    "name": "slide_from_content",
    "arguments": {
      "content": "...",
      "instructions": "...",
      "template_id": "uuid",
      "layout_name": "Title Slide"  // Specific layout
    }
  }
}

Python Example

import requests

API_KEY = "pk_your_api_key_here"
BASE_URL = "https://poe.poesius.com/api/v1/mcp"

# Step 1: List templates
templates_response = requests.post(
    f"{BASE_URL}/messages",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "method": "tools/call",
        "params": {
            "name": "list_templates",
            "arguments": {}
        }
    }
)

templates = templates_response.json()["result"]["templates"]

# Step 2: Choose first template
template_id = templates[0]["template_id"]
print(f"Using template: {templates[0]['template_name']}")

# Step 3: Generate with template
generate_response = requests.post(
    f"{BASE_URL}/messages",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "method": "tools/call",
        "params": {
            "name": "generate_slides",
            "arguments": {
                "topic": "My Presentation",
                "instructions": "Create professional slides",
                "template_id": template_id,
                "num_slides": 15
            }
        }
    }
)

print("Slides generated successfully!")

Best Practices

Preview First: Check template thumbnails before selecting
Consistent Use: Use the same template for related presentations
Cache Results: Template lists don’t change often, so cache them
Default Template: Set a default template in your account for convenience

Templates Overview

Learn more about templates

List Templates

See how to list templates

​Template Selection Flow

​Step 1: List Available Templates

​Step 2: Review Templates

​Step 3: Choose a Template

​Step 4: Use in Generation

​REST API Usage

​Default Template

​Template Required Response

​Layout Selection

​Python Example

​Best Practices