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

# Generate a presentation with the API

> Authenticate, submit a complete generation request, use source files, and open the result.

This tutorial uses the Open Source v1 API at `http://localhost:5001/api/v1`. Cloud v3 requests use different endpoints and schemas.

## Before you start

* Install the self-hosted web application.
* Configure a working text provider.
* Create the admin account for authenticated API access.
* Confirm you can generate a short deck in the browser.

Store credentials in shell variables so they do not appear in the request itself:

```bash theme={null}
export PRESENTON_URL=http://localhost:5001
export PRESENTON_USERNAME=admin
export PRESENTON_PASSWORD=YOUR_PASSWORD
```

## 1. Make the first request

`curl --user` sends HTTP Basic authentication using the same admin username and password as the web UI.

```bash theme={null}
curl --request POST \
  --url "$PRESENTON_URL/api/v1/ppt/presentation/generate" \
  --user "$PRESENTON_USERNAME:$PRESENTON_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data '{
    "content": "Create a practical introduction to customer discovery for product teams",
    "instructions": "Use concrete examples and end with a short action plan",
    "tone": "professional",
    "verbosity": "standard",
    "web_search": false,
    "n_slides": 5,
    "language": "English",
    "template": "general",
    "include_title_slide": true,
    "include_table_of_contents": false,
    "export_as": "pptx"
  }'
```

## 2. Understand the generation fields

| Field                       | Required | Purpose                                                                       |
| --------------------------- | -------- | ----------------------------------------------------------------------------- |
| `content`                   | Yes      | Main prompt or source content                                                 |
| `slides_markdown`           | No       | Supply your own slide-by-slide Markdown instead of automatic outlining        |
| `instructions`              | No       | Additional requirements for the deck                                          |
| `tone`                      | No       | `default`, `casual`, `professional`, `funny`, `educational`, or `sales_pitch` |
| `verbosity`                 | No       | `concise`, `standard`, or `text-heavy`                                        |
| `web_search`                | No       | Enable configured web grounding; default `false`                              |
| `n_slides`                  | No       | Requested number of slides; default `8`                                       |
| `language`                  | No       | Presentation language; default `English`                                      |
| `template`                  | No       | Template name; default `general`                                              |
| `include_title_slide`       | No       | Include a title slide; default `true`                                         |
| `include_table_of_contents` | No       | Include a table of contents; default `false`                                  |
| `files`                     | No       | Paths returned by the file-upload endpoint                                    |
| `export_as`                 | No       | `pptx` or `pdf`; default `pptx`                                               |

## 3. Inspect the response

A successful response contains identifiers and paths similar to:

```json theme={null}
{
  "presentation_id": "d3000f96-096c-4768-b67b-e99aed029b57",
  "path": "/app_data/d3000f96-096c-4768-b67b-e99aed029b57/Customer_Discovery.pptx",
  "edit_path": "/presentation?id=d3000f96-096c-4768-b67b-e99aed029b57"
}
```

Prepend the Presenton server root to a relative result path. For example, the edit URL becomes:

```text theme={null}
http://localhost:5001/presentation?id=d3000f96-096c-4768-b67b-e99aed029b57
```

Open the result in the browser, review every slide, and confirm the requested export is available.

## 4. Generate from an uploaded document

Upload the source first with `/api/v1/ppt/files/upload`. The exact response schema is shown in the Open Source API reference.

```bash theme={null}
curl --request POST \
  --url "$PRESENTON_URL/api/v1/ppt/files/upload" \
  --user "$PRESENTON_USERNAME:$PRESENTON_PASSWORD" \
  --form 'files=@./quarterly-report.pdf'
```

Pass the returned file path in `files`:

```bash theme={null}
curl --request POST \
  --url "$PRESENTON_URL/api/v1/ppt/presentation/generate" \
  --user "$PRESENTON_USERNAME:$PRESENTON_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data '{
    "content": "Turn the uploaded report into an executive review",
    "instructions": "Preserve the source metrics and clearly label recommendations",
    "files": ["RETURNED_FILE_PATH"],
    "n_slides": 8,
    "tone": "professional",
    "export_as": "pdf"
  }'
```

## 5. Use custom slide Markdown

Supply `slides_markdown` when your application already knows the exact outline:

```json theme={null}
{
  "content": "Quarterly business review",
  "slides_markdown": [
    "# Q2 Business Review\n## Performance, decisions, and next steps",
    "# Revenue performance\n- Revenue grew 12% quarter over quarter\n- Enterprise expansion led net retention",
    "# Next steps\n- Improve onboarding\n- Expand enterprise pipeline"
  ],
  "template": "general",
  "export_as": "pptx"
}
```

## 6. Prepare for production

* Use the asynchronous generation endpoint for longer jobs.
* Poll the status endpoint or subscribe to a webhook instead of holding one request open.
* Keep credentials and uploaded source files out of logs.
* Set client timeouts and distinguish provider failures from network failures.
* Avoid automatic blind retries that could create duplicate presentations.
* Store `presentation_id` with your own job record.
* Validate output before publishing or sending it to users.
* Use HTTPS and restrict access to the self-hosted instance.

<CardGroup cols={2}>
  <Card title="Browse the Open Source API" icon="book-open" href="/open-source/v0.9.0-beta/api-reference/introduction">
    Review the complete endpoint list and request schemas.
  </Card>

  <Card title="Configure authentication" icon="shield-keyhole" href="/open-source/v0.9.0-beta/configuration/authentication">
    Learn how UI sessions, HTTP Basic, and MCP bearer tokens differ.
  </Card>
</CardGroup>