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


---

# 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/api-reference/post-generate.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.