Generate asynchronously

Asynchronous generation returns a task immediately and completes the presentation outside the request. Use it for production integrations, longer presentations, or any workflow that should not keep one HTTP connection open during generation.

Task lifecycle

An asynchronous task has one of three schema-defined statuses:

Status	Meaning	Application action
`pending`	The task is queued or still running	Continue waiting with bounded backoff
`completed`	Generation finished successfully	Read the presentation details from `data`
`error`	Generation failed	Stop polling and inspect `error` and `message`

1. Submit the generation request

Send the same body accepted by synchronous generation to POST /presentation/generate/async:

curl --request POST \
  --url https://api.presenton.ai/api/v3/presentation/generate/async \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "content": "Create an eight-slide executive briefing about the rollout of a new customer analytics platform",
    "n_slides": 8,
    "language": "English",
    "tone": "professional",
    "standard_template": "neo-modern",
    "export_as": "pptx",
    "trigger_webhook": false
  }'

The initial response contains a task identifier:

{
  "id": "task-9a827c13f4",
  "status": "pending",
  "message": "Presentation generation task created",
  "data": null,
  "error": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:00:00Z"
}

Persist id before returning control to your caller. Your application needs it to resume monitoring after a restart or failed handoff.

2. Check the task status

Request GET /async-task/status/{id} with the same API key:

curl --request GET \
  --url https://api.presenton.ai/api/v3/async-task/status/task-9a827c13f4 \
  --header "Authorization: Bearer YOUR_API_KEY"

When the task completes, data contains the generated presentation information:

{
  "id": "task-9a827c13f4",
  "status": "completed",
  "message": "Presentation generated successfully",
  "data": {
    "presentation_id": "8f29a2e7-4f26-48d2-9d1d-9b0716909a6d",
    "path": "https://example.com/generated-presentation.pptx",
    "edit_path": "https://presenton.ai/presentation?id=8f29a2e7-4f26-48d2-9d1d-9b0716909a6d",
    "credits_consumed": 8
  },
  "error": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:01:30Z"
}

3. Poll with a deadline

This Python example uses a capped delay and a total timeout. The API key is read from the environment instead of being placed in source code.

import os
import random
import time

import requests

BASE_URL = "https://api.presenton.ai/api/v3"
API_KEY = os.environ["PRESENTON_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def wait_for_task(task_id: str, timeout_seconds: int = 600) -> dict:
    deadline = time.monotonic() + timeout_seconds
    delay = 2.0

    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/async-task/status/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "completed":
            return task["data"]

        if task["status"] == "error":
            raise RuntimeError(task.get("error") or task.get("message"))

        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 1.5, 15.0)

    raise TimeoutError(f"Task {task_id} did not finish before the deadline")

Make polling reliable

Use one poller per task. Multiple workers polling the same task waste capacity and complicate handoffs.
Persist the task identifier, latest status, and timestamps in your application database.
Apply a total deadline even when individual HTTP requests have their own timeouts.
Add small random jitter so many tasks do not poll at exactly the same moment.
Stop immediately on completed or error; these are terminal states.
Preserve sanitized failure data for diagnostics, but never log the API key.
Decide what your product should do when its own timeout expires: continue in a background worker, notify the user, or allow a manual status refresh.

Polling or webhooks?

Polling is simple and works without a public callback endpoint. Webhooks reduce repeated status requests and work well when your application already exposes a secure HTTPS receiver. To receive generation events, subscribe to a webhook and set trigger_webhook to true in the generation request. See Receive generation webhooks.

A successfully accepted task can still finish with error. Do not treat the initial 200 response as proof that the presentation will complete.

Synchronous generation

Review the request controls and the completed presentation response.

Get started

Learn the basics

Features

Tutorials

Business automation

API guides

Task lifecycle

1. Submit the generation request

2. Check the task status

3. Poll with a deadline

Make polling reliable

Polling or webhooks?

Synchronous generation

​Task lifecycle

​1. Submit the generation request

​2. Check the task status

​3. Poll with a deadline

​Make polling reliable

​Polling or webhooks?

Synchronous generation

Task lifecycle

1. Submit the generation request

2. Check the task status

3. Poll with a deadline

Make polling reliable

Polling or webhooks?