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

# Presentation generation flows

> Choose a deployment and follow only the presentation-generation workflows and API references available there.

Choose your deployment once. The selected tab contains its complete workflow, diagrams, numbered API sequences, and reference links.

<Tip>
  Keep every call in a workflow on one deployment. Files, template identifiers, task IDs, and presentation IDs belong to the deployment that created them.
</Tip>

<Tabs>
  <Tab title="Cloud v3" icon="cloud">
    Presenton hosts Cloud v3 at `https://api.presenton.ai/api/v3`. Authenticate every request with a Cloud bearer token.

    ## Cloud generation map

    ```mermaid theme={null}
    flowchart TD
        cloudStart([Prompt or application data]) --> cloudInput{Add context or design?}
        cloudInput -->|"Source files"| cloudUpload["POST /api/v3/files/upload"]
        cloudInput -->|"Standard template"| cloudTemplates["GET /api/v3/standard-template/all"]
        cloudInput -->|"Smart Design"| cloudDesigns["GET /api/v3/smart-design/all"]
        cloudInput -->|"No preparation"| cloudMode{Choose delivery mode}
        cloudUpload --> cloudMode
        cloudTemplates --> cloudMode
        cloudDesigns --> cloudMode
        cloudMode -->|"Wait for result"| cloudSync["POST /api/v3/presentation/generate"]
        cloudMode -->|"Run in background"| cloudAsync["POST /api/v3/presentation/generate/async"]
        cloudAsync --> cloudStatus["GET /api/v3/async-task/status/{id}"]
        cloudSync --> cloudReview([Review the presentation])
        cloudStatus --> cloudReview
        cloudReview --> cloudExport["POST /api/v3/presentation/export"]
    ```

    ### Recommended Cloud sequence

    1. **Optional — upload source material:** call [Upload source files](/api-reference/v3-files/upload-source-files), then keep the returned file values.
    2. **Optional — select a visual system:** call [List Standard templates](/api-reference/v3-standard-template/list-standard-templates) or [List Smart Designs](/api-reference/v3-smart-design/list-smart-designs).
    3. **Optional — approve the narrative:** call [Generate an outline](/api-reference/v3-presentation/generate-an-outline) before building the deck.
    4. **Generate:** call [Generate synchronously](/api-reference/v3-presentation/generate-a-presentation-synchronously) or [Generate asynchronously](/api-reference/v3-presentation/generate-a-presentation-asynchronously).
    5. **Resolve background work:** process a subscribed webhook or call [Get task status](/api-reference/v3-async-task/get-task-status).
    6. **Deliver:** review the returned edit path, then call [Export a presentation](/api-reference/v3-presentation/export-a-presentation) when a new PPTX or PDF is required.

    ## Choose a Cloud workflow

    | Goal                            | API sequence                                               |
    | ------------------------------- | ---------------------------------------------------------- |
    | Generate directly from a prompt | Optional outline → generate → review → export              |
    | Ground a deck in documents      | Upload files → generate → verify → export                  |
    | Apply a Standard template       | List templates → optional inspection → generate            |
    | Apply a Smart Design            | List Smart Designs → generate                              |
    | Use a PPTX-based template       | Import and validate in the app → list templates → generate |
    | Create from application data    | Inspect template schema → validate JSON → create           |
    | Run a background job            | Optional webhook → async generate → status or event        |

    ## Flow 1: Generate directly

    Use direct generation when the prompt contains enough context and no source upload is required.

    1. **Optional:** [Generate an outline](/api-reference/v3-presentation/generate-an-outline) and review the returned slide plan.
    2. **Generate:** [Generate synchronously](/api-reference/v3-presentation/generate-a-presentation-synchronously) for an interactive request or use [asynchronous generation](/api-reference/v3-presentation/generate-a-presentation-asynchronously).
    3. **Optional:** [Export the presentation](/api-reference/v3-presentation/export-a-presentation) after review or editing.

    ## Flow 2: Generate from source files

    ```mermaid theme={null}
    sequenceDiagram
        title Cloud generation from source files
        participant Client
        participant Cloud as Cloud v3 API
        participant Generator

        Client->>Cloud: POST /api/v3/files/upload
        Cloud-->>Client: Return file values
        Client->>Cloud: POST /api/v3/presentation/generate with files
        Cloud->>Generator: Ground the deck in uploaded content
        Generator-->>Cloud: Store the presentation
        Cloud-->>Client: Return ID, path, and edit path
    ```

    1. **Upload:** call [Upload source files](/api-reference/v3-files/upload-source-files).
    2. **Generate:** pass the returned values in `files` to [Generate a presentation](/api-reference/v3-presentation/generate-a-presentation-synchronously).
    3. **Verify:** compare names, dates, claims, calculations, and charts with the original sources.
    4. **Deliver:** call [Export a presentation](/api-reference/v3-presentation/export-a-presentation) when the reviewed result needs another format.

    ## Flow 3: Generate with a Cloud design

    ```mermaid theme={null}
    flowchart TD
        designStart([Choose a visual system]) --> designType{Which Cloud design?}
        designType -->|"Standard template"| standardList["GET /api/v3/standard-template/all"]
        standardList --> standardInspect["GET /api/v3/standard-template/{id}"]
        standardInspect --> standardGenerate["POST /api/v3/presentation/generate with standard_template"]
        designType -->|"Smart Design"| smartList["GET /api/v3/smart-design/all"]
        smartList --> smartGenerate["POST /api/v3/presentation/generate with smart_design"]
    ```

    ### Standard template sequence

    1. [List Standard templates](/api-reference/v3-standard-template/list-standard-templates).
    2. Optionally [inspect the selected template](/api-reference/v3-standard-template/get-a-standard-template).
    3. Call [Generate a presentation](/api-reference/v3-presentation/generate-a-presentation-synchronously) with its ID in `standard_template`.

    ### Smart Design sequence

    1. [List Smart Designs](/api-reference/v3-smart-design/list-smart-designs).
    2. Call [Generate a presentation](/api-reference/v3-presentation/generate-a-presentation-synchronously) with its ID in `smart_design`.

    ## Flow 4: Import a PPTX template, then generate

    Template creation happens in the Presenton application in this documented public workflow.

    ```mermaid theme={null}
    flowchart TD
        pptxSource([Filled PPTX]) --> templateStudio[Import in Template Studio]
        templateStudio --> fontCheck[Resolve missing fonts]
        fontCheck --> layoutReview[Review layouts and content schemas]
        layoutReview --> templateTest[Test and save the template]
        templateTest --> templateList["GET /api/v3/standard-template/all"]
        templateList --> templateUse["POST /api/v3/presentation/generate with standard_template"]
    ```

    1. Follow the [custom PPTX template workflow](../user-guide/branding-and-design/custom-presentation-templates).
    2. [List Standard templates](/api-reference/v3-standard-template/list-standard-templates) and keep the saved template ID.
    3. [Generate a presentation](/api-reference/v3-presentation/generate-a-presentation-synchronously) with that ID in `standard_template`.

    ## Flow 5: Create from structured JSON

    Use structured JSON when the application owns the exact slide data and needs deterministic layout selection.

    ```mermaid theme={null}
    flowchart TD
        jsonData([Application slide data]) --> jsonTemplates["GET /api/v3/standard-template/all"]
        jsonTemplates --> jsonTemplate["GET /api/v3/standard-template/{id}"]
        jsonTemplate --> jsonValidate[Validate slides against layout json_schema]
        jsonValidate --> jsonMode{Choose delivery mode}
        jsonMode -->|"Synchronous"| jsonSync["POST /api/v3/presentation/from-json"]
        jsonMode -->|"Asynchronous"| jsonAsync["POST /api/v3/presentation/from-json/async"]
        jsonAsync --> jsonStatus["GET /api/v3/async-task/status/{id}"]
        jsonSync --> jsonReview([Review the presentation])
        jsonStatus --> jsonReview
    ```

    1. [List Standard templates](/api-reference/v3-standard-template/list-standard-templates).
    2. [Get the selected template](/api-reference/v3-standard-template/get-a-standard-template) and inspect each layout's `json_schema`.
    3. Optionally [view a template example](/api-reference/v3-standard-template/get-a-template-example).
    4. Validate every slide object against its selected layout.
    5. Call [Create from JSON synchronously](/api-reference/v3-presentation/create-from-json-synchronously) or [Create from JSON asynchronously](/api-reference/v3-presentation/create-from-json-asynchronously).
    6. For background work, call [Get task status](/api-reference/v3-async-task/get-task-status).

    ## Flow 6: Run Cloud jobs asynchronously

    ```mermaid theme={null}
    sequenceDiagram
        title Cloud asynchronous generation
        participant Client
        participant Cloud as Cloud v3 API
        participant Worker
        participant Callback as Webhook receiver

        Client->>Cloud: POST /api/v3/webhook/subscribe
        Client->>Cloud: POST /api/v3/presentation/generate/async
        Cloud-->>Client: Return task ID
        Cloud->>Worker: Queue generation
        Worker-->>Cloud: Store completed presentation
        Cloud->>Callback: Send completion event
        Client->>Cloud: GET /api/v3/async-task/status/{id}
        Cloud-->>Client: Return status and result
    ```

    1. **Optional:** [Subscribe a webhook](/api-reference/v3-webhook/subscribe-a-webhook).
    2. **Submit:** [Generate asynchronously](/api-reference/v3-presentation/generate-a-presentation-asynchronously).
    3. **Store:** persist the returned task ID before starting other work.
    4. **Resolve:** process the webhook idempotently or call [Get task status](/api-reference/v3-async-task/get-task-status) with bounded backoff.

    <CardGroup cols={3}>
      <Card title="Cloud API quickstart" icon="rocket" href="./quickstart">
        Review the shortest complete Cloud request chain.
      </Card>

      <Card title="Cloud authentication" icon="key" href="../user-guide/api-and-automation/authentication">
        Prepare and protect the bearer token.
      </Card>

      <Card title="Cloud generation reference" icon="book-open" href="/api-reference/v3-presentation/generate-a-presentation-synchronously">
        Inspect exact fields, schemas, and examples.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Open Source v1" icon="server">
    Your deployment hosts Open Source v1 at `https://<your-host>/api/v1`. Use HTTP Basic authentication when it is enabled on the instance.

    ## Open Source generation map

    ```mermaid theme={null}
    flowchart TD
        osStart([Prompt or application data]) --> osInput{Use source files?}
        osInput -->|"Yes"| osUpload["POST /api/v1/ppt/files/upload"]
        osInput -->|"No"| osTemplate{Use an installed template?}
        osUpload --> osTemplate
        osTemplate -->|"Template name or default"| osMode{Choose delivery mode}
        osMode -->|"Wait for result"| osSync["POST /api/v1/ppt/presentation/generate"]
        osMode -->|"Run in background"| osAsync["POST /api/v1/ppt/presentation/generate/async"]
        osAsync --> osStatus["GET /api/v1/ppt/presentation/status/{id}"]
        osSync --> osResult["GET /api/v1/ppt/presentation/{id}"]
        osStatus --> osResult
        osResult --> osManage([Review, edit, or derive])
    ```

    ### Recommended Open Source sequence

    1. **Configure the instance:** complete [API authentication](../user-guide/api-and-automation/authentication), connect the required providers, and keep every request on the same Presenton origin.
    2. **Optional — upload source material:** call [Upload source files](/api-reference/files/upload-source-files), then keep the returned file paths.
    3. **Optional — choose an installed template:** create or install it in Presenton, then send its supported name in `template`.
    4. **Generate:** call [Generate synchronously](/api-reference/presentation/generate-a-presentation-synchronously) or [Generate asynchronously](/api-reference/presentation/generate-a-presentation-asynchronously).
    5. **Resolve background work:** process a subscribed webhook or call [Get generation status](/api-reference/presentation/get-generation-status).
    6. **Retrieve and continue:** call [Get a presentation](/api-reference/presentation/get-a-presentation), then edit or derive when another revision is needed.

    ## Choose an Open Source workflow

    | Goal                            | API sequence                                            |
    | ------------------------------- | ------------------------------------------------------- |
    | Generate directly from a prompt | Generate → retrieve → review                            |
    | Ground a deck in documents      | Upload files → generate → retrieve → verify             |
    | Apply a reusable template       | Install or create template → generate with its name     |
    | Use a PPTX-based template       | Import and validate in the app → generate with its name |
    | Run a background job            | Optional webhook → async generate → generation status   |
    | Revise a stored deck            | Retrieve → edit in place or derive a copy               |

    ## Flow 1: Generate directly

    1. **Generate:** call [Generate synchronously](/api-reference/presentation/generate-a-presentation-synchronously) or [Generate asynchronously](/api-reference/presentation/generate-a-presentation-asynchronously).
    2. **Retrieve:** call [Get a presentation](/api-reference/presentation/get-a-presentation) with the returned presentation ID.
    3. **Optional:** continue with [Edit a presentation](/api-reference/presentation/edit-a-presentation), [Derive a presentation](/api-reference/presentation/derive-a-presentation), or [Edit a slide](/api-reference/slide/edit-a-slide).

    ## Flow 2: Generate from source files

    ```mermaid theme={null}
    sequenceDiagram
        title Open Source generation from source files
        participant Client
        participant Instance as Open Source v1 API
        participant Generator

        Client->>Instance: POST /api/v1/ppt/files/upload
        Instance-->>Client: Return local file paths
        Client->>Instance: POST /api/v1/ppt/presentation/generate with files
        Instance->>Generator: Ground the deck in uploaded content
        Generator-->>Instance: Store the presentation
        Instance-->>Client: Return ID, path, and edit path
    ```

    1. **Upload:** call [Upload source files](/api-reference/files/upload-source-files).
    2. **Generate:** pass the returned paths in `files` to [Generate a presentation](/api-reference/presentation/generate-a-presentation-synchronously).
    3. **Retrieve:** call [Get a presentation](/api-reference/presentation/get-a-presentation) when the application needs the stored presentation data.
    4. **Verify:** compare names, dates, claims, calculations, and charts with the original sources.

    ## Flow 3: Generate with an installed template

    Template creation and installation happen in the Presenton application in this documented public workflow.

    ```mermaid theme={null}
    flowchart TD
        templateStart([Choose a template]) --> templateExists{Already installed?}
        templateExists -->|"No"| templateCreate[Create or import in Presenton]
        templateCreate --> templateValidate[Test layouts and fonts]
        templateExists -->|"Yes"| templateName[Keep the supported template name]
        templateValidate --> templateName
        templateName --> templateGenerate["POST /api/v1/ppt/presentation/generate with template"]
    ```

    1. [Create or install a custom template](../user-guide/branding-and-design/custom-presentation-templates) on the instance.
    2. Test its layouts, fonts, and representative content in the application.
    3. Call [Generate a presentation](/api-reference/presentation/generate-a-presentation-synchronously) with the installed name in `template`.

    ## Flow 4: Run Open Source jobs asynchronously

    ```mermaid theme={null}
    sequenceDiagram
        title Open Source asynchronous generation
        participant Client
        participant Instance as Open Source v1 API
        participant Worker
        participant Callback as Webhook receiver

        Client->>Instance: POST /api/v1/webhook/subscribe
        Client->>Instance: POST /api/v1/ppt/presentation/generate/async
        Instance-->>Client: Return task ID
        Instance->>Worker: Queue generation
        Worker-->>Instance: Store completed presentation
        Instance->>Callback: Send completion event
        Client->>Instance: GET /api/v1/ppt/presentation/status/{id}
        Instance-->>Client: Return status and result
    ```

    1. **Optional:** [Subscribe a webhook](/api-reference/webhook/subscribe-a-webhook).
    2. **Submit:** [Generate asynchronously](/api-reference/presentation/generate-a-presentation-asynchronously).
    3. **Store:** persist the returned task ID before starting other work.
    4. **Resolve:** process the webhook idempotently or call [Get generation status](/api-reference/presentation/get-generation-status) with bounded backoff.

    ## Flow 5: Manage and revise stored presentations

    1. **Discover:** [List presentations](/api-reference/presentation/list-presentations).
    2. **Retrieve:** [Get a presentation](/api-reference/presentation/get-a-presentation).
    3. **Revise in place:** [Edit a presentation](/api-reference/presentation/edit-a-presentation) or [Edit a slide](/api-reference/slide/edit-a-slide).
    4. **Preserve the original:** [Derive a presentation](/api-reference/presentation/derive-a-presentation).
    5. **Remove when appropriate:** [Delete a presentation](/api-reference/presentation/delete-a-presentation).

    <CardGroup cols={3}>
      <Card title="Open Source tutorial" icon="terminal" href="../user-guide/api-and-automation/open-source-api-tutorial">
        Build one complete self-hosted request.
      </Card>

      <Card title="Open Source authentication" icon="key" href="../user-guide/api-and-automation/authentication">
        Configure and protect instance credentials.
      </Card>

      <Card title="Open Source generation reference" icon="book-open" href="/api-reference/presentation/generate-a-presentation-synchronously">
        Inspect exact fields, schemas, and examples.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>