> For the complete documentation index, see [llms.txt](https://docs.perceptis.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perceptis.ai/api-reference/post-generate.md).

# POST /api/v1/generate

## Purpose

Start an asynchronous single-slide or complete-deck generation job. The response returns a `job_id` immediately; use [`GET /api/v1/status/{job_id}`](/api-reference/get-status.md) to poll until the job completes or fails.

`Idempotency-Key` is a client-supplied retry key for `POST /generate`. It is separate from the Perceptis-generated `job_id`, which is used for status polling and downloads after the job is accepted.

## Request

| Item            | Value                                                                         |
| --------------- | ----------------------------------------------------------------------------- |
| Method and path | `POST {PERCEPTIS_API_BASE_URL}/api/v1/generate`                               |
| Auth            | `Authorization: Bearer <api-key>`                                             |
| Headers         | `Content-Type: application/json`; optional `Idempotency-Key` for safe retries |
| Body            | JSON generation request                                                       |

## Request body

| Field                | Type    | Required | Notes                                                                               |
| -------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt`             | string  | Yes      | Instructions for the slide or deck.                                                 |
| `output_type`        | string  | Yes      | `single_slide` or `deck`.                                                           |
| `template_name`      | string  | No       | Name of an accessible Perceptis template. Omit to use automatic template selection. |
| `variant_count`      | integer | No       | Single-slide requests only.                                                         |
| `reference_images`   | array   | No       | Single-slide requests only. Each item includes base64 `data` and `mime_type`.       |
| `use_web_search`     | boolean | No       | Allow Perceptis to use web search when generating.                                  |
| `use_knowledge_base` | boolean | No       | Allow Perceptis to use your organization knowledge base when generating.            |

## Example

```json
{
  "prompt": "Create an executive summary slide for Q3 revenue growth drivers",
  "output_type": "single_slide",
  "variant_count": 1,
  "template_name": "Acme Executive",
  "use_web_search": false,
  "use_knowledge_base": true
}
```

## Responses

| HTTP  | Meaning                                                                                                                                                                |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Job accepted. Body includes `job_id`, `status`, `output_type`, `downloads`, and `error`.                                                                               |
| `400` | Invalid request.                                                                                                                                                       |
| `401` | Missing, invalid, or revoked API key.                                                                                                                                  |
| `403` | Organization is not eligible for API access. Perceptis API usage requires a paid Business or Enterprise plan; Free, Starter, and trial organizations are not eligible. |
| `409` | Template ambiguity or idempotency conflict.                                                                                                                            |
| `429` | Rate limited. Use `Retry-After` and back off.                                                                                                                          |

Example accepted response:

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "output_type": "single_slide",
  "downloads": null,
  "error": null
}
```

## See also

* [Quickstart: single slide](/perceptis-api-v1/quickstart-single-slide.md)
* [Quickstart: complete deck](/perceptis-api-v1/quickstart-deck.md)
* [Templates](/perceptis-api-v1/templates.md)
* [Errors, rate limits, and billing](/perceptis-api-v1/errors-and-limits.md)