Quickstart: complete deck

Quickstart for complete-deck generation with safe polling.

This quickstart starts a complete-deck generation job and polls until the .pptx deck is ready to download.

Set environment variables

Set PERCEPTIS_API_BASE_URL to the API origin only. Do not include /api; the examples append /api/v1/....

export PERCEPTIS_API_BASE_URL="https://app.perceptis.ai"
export PERCEPTIS_API_KEY="sk-live-per-..."

Install the Python HTTP client used by this quickstart:

python3 -m pip install requests

Start generation

Use this as quickstart_deck.py:

import os
import time
import uuid

import requests


base_url = os.environ["PERCEPTIS_API_BASE_URL"].rstrip("/")
api_key = os.environ["PERCEPTIS_API_KEY"]

response = requests.post(
    f"{base_url}/api/v1/generate",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "prompt": "Ten-slide board deck on market entry for EU expansion",
        "output_type": "deck",
    },
    timeout=60,
)
response.raise_for_status()

job_id = response.json()["job_id"]
print(f"Job ID: {job_id}")


def poll_status(job_id, timeout_sec=300):
    deadline = time.monotonic() + timeout_sec

    while time.monotonic() < deadline:
        status_response = requests.get(
            f"{base_url}/api/v1/status/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=60,
        )
        status_response.raise_for_status()

        body = status_response.json()
        if body["status"] in {"completed", "failed"}:
            return body

        time.sleep(3)

    raise TimeoutError(f"Job did not finish within {timeout_sec} seconds")


final = poll_status(job_id)

if final["status"] == "failed":
    raise RuntimeError(final.get("error") or "Generation failed")

for download in final.get("downloads") or []:
    print(download["url"])

The response includes a job_id:

{
  "job_id": "3b4f1f54-66a9-4f5e-a681-60b1c55a8c9d",
  "status": "pending",
  "output_type": "deck",
  "downloads": null,
  "error": null
}

Poll status

Poll GET /api/v1/status/{job_id} with the same API key that created the job. The example above checks every 3 seconds and stops after 5 minutes. For retries, backoff, and Retry-After handling, see the full client script example.

Completion

When status is completed, the deck appears in downloads:

{
  "job_id": "3b4f1f54-66a9-4f5e-a681-60b1c55a8c9d",
  "status": "completed",
  "output_type": "deck",
  "downloads": [
    {
      "url": "https://app.perceptis.ai/downloads/3b4f1f54-66a9-4f5e-a681-60b1c55a8c9d.pptx?expires=3600&signature=...",
      "format": "pptx",
      "slide_count": 10
    }
  ],
  "error": null
}

If a URL expires, poll status again for fresh links while the generated files remain available. Use the same API key that created the job.

Deck-specific fields

Use output_type: "deck" for complete-deck generation. Do not send variant_count or reference_images with deck requests.

You can also include template_name, use_web_search, or use_knowledge_base when needed. See the POST /api/v1/generate reference for the full request body.