> ## 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.

# Generate Slides from Document

> Create presentations from uploaded documents using the REST API

## Endpoint

```
POST /slides/generate-from-doc
```

## Description

Asynchronously generates slides from an uploaded document. Poesius automatically:

1. **Generates the presentation narrative** - Analyzes your document and creates a McKinsey-style story, summarizing key findings and revealing insights
2. **Retrieves layout details** - Gets template specifications including colors, layout zones, and design elements (defined visually in the web app)
3. **Creates slides** - Combines the narrative with template specs to produce professional PPTX files

Returns immediately with a presentation ID and status URL for polling.

## Request

**Method**: `POST`\
**Content-Type**: `multipart/form-data`\
**Headers**:

* `X-API-Key: <your_api_key>` OR
* `Authorization: Bearer <token>`

## Parameters

| Parameter       | Type    | Required | Description                                                                             |
| --------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `document`      | file    | Yes      | The document file (PDF, DOCX, TXT, MD, etc.)                                            |
| `instructions`  | string  | No       | Custom instructions for generation (default: "Create a presentation from the document") |
| `num_slides`    | integer | No       | Target number of slides (default: 20)                                                   |
| `template_id`   | string  | No       | UUID of the template to use                                                             |
| `deep_research` | boolean | No       | Enable deep research mode (default: false)                                              |

## Example Request

```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=@/path/to/document.pdf" \
  -F "instructions=Create a professional presentation about the key findings" \
  -F "num_slides=15" \
  -F "template_id=123e4567-e89b-12d3-a456-426614174000" \
  -F "deep_research=false"
```

## Response

```json theme={null}
{
  "status": "pending",
  "message": "Generation started in background",
  "conversation_id": "uuid",
  "presentation_id": "uuid",
  "check_status_url": "/api/v1/presentations/{presentation_id}"
}
```

## Presentation Status Flow

When you generate slides from a document, the presentation goes through several status stages before reaching the final `completed` state. Understanding these statuses helps you track progress and know when the presentation is ready for download.

### Status Progression

The presentation status transitions through the following stages:

1. **`pending`** - Initial state when the presentation is created. Generation has been queued but not yet started.

2. **`processing`** - The system has started processing your request. This includes:
   * Reading and analyzing the uploaded document
   * Extracting content and structure
   * Preparing for slide generation

3. **`content_generation`** - The AI is generating the slide content:
   * Creating markdown content for each slide
   * Structuring information from your document
   * Organizing content into logical slide sequences

4. **`content_complete`** - Content has been generated for all slides, but visual design may still be in progress:
   * All slide content is ready
   * Slides may still be undergoing visual rendering or refinement

5. **`design_in_progress`** - Slides are being visually designed and rendered:
   * Applying template layouts
   * Generating slide images/thumbnails
   * Refining visual presentation

6. **`completed`** - All slides are fully generated and ready for download:
   * Content is complete
   * Visual design is finished
   * Presentation can be downloaded

### Other Status Values

* **`partial`** - Some slides are completed while others are still processing (rare, typically during recovery scenarios)
* **`failed`** - Generation encountered an error. Check error details for more information
* **`draft`** - Initial placeholder state (typically only seen during presentation initialization)

### Status Polling

Poll the status endpoint (`GET /presentations/{presentation_id}`) every 5-10 seconds to track progress. The presentation is ready for download when the status reaches `completed`.

## Next Steps

After receiving the response, you'll need to:

1. **Poll for status** using the `check_status_url` or `presentation_id`
2. **Download the presentation** once status is `completed`

<Card title="Check Status" icon="circle-check" href="/api/check-status">
  Learn how to check presentation status
</Card>

<Card title="Download Presentation" icon="download" href="/api/download-presentation">
  Download your completed presentations
</Card>

## Supported File Formats

* PDF (`.pdf`)
* Microsoft Word (`.docx`)
* Plain Text (`.txt`)
* Markdown (`.md`)

## Best Practices

* **File Size**: Keep documents under 50MB for best performance
* **Instructions**: Be specific about what you want in the presentation
* **Slide Count**: Specify a target number of slides based on your needs
* **Templates**: Use templates for consistent branding