POST /api/v1/generate
POST /api/v1/generate endpoint reference.
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} 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
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
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
Responses
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:
See also
Last updated
Was this helpful?