Generate a presentation with the API

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:

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.

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:

{
  "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:

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.

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:

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:

{
  "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.

Browse the Open Source API

Review the complete endpoint list and request schemas.

Configure authentication

Learn how UI sessions, HTTP Basic, and MCP bearer tokens differ.

Get started

Learn the basics

Features

Tutorials

API guides

Deploy and configure

Develop and contribute

This release

Before you start

1. Make the first request

2. Understand the generation fields

3. Inspect the response

4. Generate from an uploaded document

5. Use custom slide Markdown

6. Prepare for production

Browse the Open Source API

Configure authentication

​Before you start

​1. Make the first request

​2. Understand the generation fields

​3. Inspect the response

​4. Generate from an uploaded document

​5. Use custom slide Markdown

​6. Prepare for production

Browse the Open Source API

Configure authentication

Before you start

1. Make the first request

2. Understand the generation fields

3. Inspect the response

4. Generate from an uploaded document

5. Use custom slide Markdown

6. Prepare for production