# Quickstart: complete deck

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/...`.

```bash
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:

```bash
python3 -m pip install requests
```

## Start generation

Use this as `quickstart_deck.py`:

```python
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`:

```json
{
  "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](/perceptis-api-v1/examples.md).

## Completion

When `status` is `completed`, the deck appears in `downloads`:

```json
{
  "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](/api-reference/post-generate.md) for the full request body.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.perceptis.ai/perceptis-api-v1/quickstart-deck.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.