---
title: "Create an AutoGenerator job"
method: POST
path: "/api/v1/autogenerator"
tags: ["AutoGenerator"]
---

# Create an AutoGenerator job

`POST /api/v1/autogenerator`

Kicks off a background pipeline that turns the supplied prompt,
context files, and assets into a Prezent presentation. Returns a
`callback_id` that the caller polls via
`GET /api/v1/autogenerator/status?callback_id={callback_id}` until
`status` is `success` or `failed`.

## Headers

- `Idempotency-Key` string

## Request body

- AutoGeneratorStartRequest — Request body for `POST /api/v1/autogenerator`.
  - `prompt` string, required — Natural-language description of the deck to generate.
  - `texts` string[] — Additional free-text context to ground the deck.
  - `files` string[] — Previously uploaded supporting files (by id).
  - `web_links` string[] — Web URLs to ingest as additional context.
  - `audience` object — Target audience. Must be an object — `id` and `num_id` are required when `audience` is provided.
    - `id` string, required — Audience id.
    - `num_id` integer, required — Numeric audience id.
    - `audienceId` string
    - `fullName` string
    - `type` string
    - `ownerID` string, nullable
    - `fingerPrint` string
    - `isActive` boolean
    - `isPrivate` boolean
    - `isShared` boolean
    - `shared` boolean
    - `fingerprintResponse` object[]
  - `template_id` string — Target theme/template id.
  - `settings` object — Optional per-generation settings. Every key is optional; omit the object entirely to use the defaults configured for the API key.
    - `template_id` string — Template id to generate against. Used only when the root-level `template_id` is not provided; if both are sent, the root-level value wins and this one is ignored.
    - `ai_model` 'astrid_standard' | 'astrid_advanced' — Generation model to use.
    - `image_preferences` string[] — Image libraries to source imagery from. Cannot be an empty array when provided.
    - `knowledge_base` 'uploaded_only' | 'uploaded_and_web' — Which context sources the generator may draw on.
    - `data_sources` string[] — Where to render source attributions.
    - `speaker_notes` string[] — Speaker-notes generation options.
    - `preserve_text` boolean — Preserve the supplied text verbatim instead of rewriting it.
    - `voice_settings` object — Brand-voice configuration.
      - `type` 'brand' | 'standard' | 'custom', required — Voice profile to apply.
      - `details` object — Required when `type` is `custom`.
        - `tone` string, required
        - `emotion` string, required

## Response `200`

Job accepted; client must poll for completion.

- AutoGeneratorStartResponse — Async-start envelope for `POST /api/v1/autogenerator`. This endpoint does **not** use the canonical `success`/`data` envelope. The payload is returned under `resData`, alongside top-level `message` and `error` keys.
  - `message` string — Human-readable status, for example "Job submitted successfully".
  - `resData` object, required
    - `callback_id` string, required — Server-issued opaque identifier to poll.
    - `token` string — One-time token issued alongside the `callback_id`, used by callback-id-scoped URLs.
  - `error` string, nullable — Null on success; an error string otherwise.

## Other responses

- `400` — Generic client error. `error.code` is one of `BAD_REQUEST`, `INVALID_JSON`, `MISSING_REQUIRED_FIELD`, `MISSING_QUERY_PARAM`, `MISSING_CALLBACK_ID`, `MISSING_SLIDES_ARRAY`, `MISSING_PROMPT`, `MISSING_TEMPLATE_ID`, `MISSING_FILE_CONTENT`, `MISSING_SHARE_DETAILS`, `INVALID_TYPE`, `INVALID_DATA`, `INVALID_DATA_TYPE`, `INVALID_PAYLOAD`, `INVALID_REQUEST`, `API_REQUEST_FAILED`, or `FILE_UPLOAD_FAILED`.
- `401` — Caller did not present a valid Bearer token, or the token has expired. `error.code` is one of `UNAUTHORIZED`, `INVALID_API_KEY`, `EXPIRED_API_KEY`.
- `403` — Caller is authenticated but not allowed to perform this operation. `error.code` is `FORBIDDEN`.
- `404` — Requested endpoint or resource does not exist. `error.code` is one of `ENDPOINT_NOT_FOUND`, `RESOURCE_NOT_FOUND`, `NOT_FOUND`.
- `409` — The supplied `Idempotency-Key` was already used with a different request body. Reuse a key only for identical retried requests.
- `422` — Request was well-formed but failed semantic validation. `error.code` is one of `INVALID_INPUT`, `UNPROCESSABLE_ENTITY`.
- `429` — Rate limit, usage limit, or gateway-level throttle exceeded. `error.code` is `TOO_MANY_REQUESTS` (gateway throttle), `RATE_LIMIT_EXCEEDED` (per-category), or `USAGE_LIMIT_EXCEEDED` (annual quota). Default limits (all configurable per company/key): - Gateway throttle (per API key) → `TOO_MANY_REQUESTS`: 10 requests/second sustained, 5 burst, 1,000 requests/day. - Per-company, per-category sliding 60-second window → `RATE_LIMIT_EXCEEDED`. The applicable category is given by each operation's `x-rate-limit-category`. - Annual usage quota → `USAGE_LIMIT_EXCEEDED`: 50,000 slide generations/year and 1,000,000 presentation downloads/year. `X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset` are returned on successful (2xx) responses from rate-limited endpoints and, with `Retry-After`, on the per-category `RATE_LIMIT_EXCEEDED` 429 (the headers declared below). The gateway `TOO_MANY_REQUESTS` and annual `USAGE_LIMIT_EXCEEDED` responses do not carry them. Read `X-RateLimit-Remaining` to self-throttle and honour `Retry-After` on a 429.
- `500` — Unexpected server error. `error.code` is `INTERNAL_SERVER_ERROR`.
- `503` — Service is temporarily unavailable (downstream dependency unhealthy). `error.code` is `SERVICE_UNAVAILABLE` or `EXTERNAL_SERVICE_ERROR`.
- `504` — A downstream call timed out. `error.code` is `GATEWAY_TIMEOUT`.

---

[API](https://skmtc.net/prezent/apis/prezent-platform-api.md) · [All operations](https://skmtc.net/prezent/apis/prezent-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prezent/prezent-platform-api/revisions/a01cb764a085/schema)