> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poesius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Selecting Templates

> Learn how to choose and use templates

## Template Selection Flow

### Step 1: List Available Templates

First, get the list of available templates:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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

## Python Example

```python theme={null}
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

<Card title="Templates Overview" icon="palette" href="/templates/overview">
  Learn more about templates
</Card>

<Card title="List Templates" icon="list" href="/mcp/list-templates">
  See how to list templates
</Card>