> For the complete documentation index, see [llms.txt](https://guide.plusai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.plusai.com/apis-for-presentations/presentations-api.md). # Presentations API {% hint style="info" %} Presentations API requires a **Pro or Team plan**. [Learn more about pricing](/plus-ai/plans-and-billing.md). {% endhint %} The Plus AI Presentations API allows you to create new presentations programmatically via HTTP request. Creating presentations via the Presentations API is a two step process. First, you being presentation creation with a create request, and then you poll for the final presentation file using the presentations endpoint. ## Authentication To authenticate with the Presentations API, you must first generate an API key. You can [generate an API key here](https://app.plusdocs.com/api-settings). \ \ \&#xNAN;*Note: Only one active API key per user is currently allowed.*\ \ Once you have an API key, you can authenticate your requests to the presentations api using [HTTP Bearer authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/): ``` Authorization: Bearer {PLUSAI_API_KEY} ``` ## Creating presentations via HTTP request Creating presentations is done by sending a POST request to the presentations endpoint: ``` POST https://api.plusdocs.com/r/v0/presentation ``` The following content can be sent inside the body payload of the request:
NameRequiredTypeDescription
promptYesstringThe input text prompt and content for the presentation
languageNostring, ISO 639-1Defaults to "en"
numberOfSlidesNointeger, <= 30If not provided, will be determined by AI
includeUserTipsNobooleanIf set to false, Plus user tips will not be added to slides in presentation
templateIdNostringId of the custom template to create the presentation from. Contact us for information on using custom templates
textHandlingNo

string, 

"DEFAULT" |
"PRESERVE" |
"STRICT"
See API text handling section below
generationModeNo

string,

"SLIDES" (default) | 
"IMAGES"
See image mode section below
attachmentsNoarray,
[{"fileId": "<fileId>"}]		Files to use as source content for the presentation, uploaded via the Files API.
#### Text Handling There are three different modes of text handling available via the Presentations API, which allow for control over how much editing Plus AI will do to your inputs while creating your presentation: * Default mode: Plus AI will use your initial input as a reference, but will both edit the initial input and expand upon the input to create the best presentation possible. * Preserve mode: Plus AI will use your initial input as a reference, and will use direct excerpts from your documents in the presentation, while minimizing edits and expansion, but will use editing and expansion of the original input when necessary. * Strict mode: Plus AI will only use directs quotes/excerpts from your initial input when making your presentation. *Note: While Plus AI will only use your initial input in direct quotes, certain types of content such as charts, images, tables, and other formatted content may result in slight changes from your initial document.* ### Image mode Pass `"generationMode": "IMAGES"` to generate a deck where each slide is one AI-generated 16:9 image. Plus AI first writes an outline from your prompt, then generates an image per slide that reflects your prompt's style instructions. ```bash curl -X POST 'https://api.plusdocs.com/r/v0/presentation' \ -H "Authorization: Bearer $PLUSAI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "prompt": "The state of millennial parenting in the style of a hand-drawn comic", "generationMode": "IMAGES", "numberOfSlides": 5 }' ``` The response is the same as slides mode (`pollingUrl` + `status`). Poll the URL until generation finishes — note that image-mode presentations finish with status `COMPLETED` (slides-mode presentations finish with status `GENERATED`): ```json { "id": "cmq84l6pe0002akpcsaonelcm", "status": "COMPLETED", "generationMode": "IMAGES", "slides": ["Introduction", "..."], "images": [ "https://media.plusdocs.com/.../2def29c0....jpg", "https://media.plusdocs.com/.../c2449979....jpg" ], "thumbnailUrl": "https://media.plusdocs.com/.../thumbnail.jpg", "url": "https://media.plusdocs.com/.../image-pptx-....pptx" } ``` * `images` — one stable CDN URL per slide (1920×1080 JPEG), in deck order. Ready to embed directly in a web page or social carousel. * `thumbnailUrl` — a 1200px-wide share-card image derived from slide 1. * `url` — a downloadable .pptx with one full-bleed image per slide. The .pptx is assembled shortly **after** `status` becomes `COMPLETED`, so `url` may be `null` for up to a minute — keep polling until it is non-null if you need the file. #### Using image attachments In image mode, attached PNG and JPEG files are provided to the image model alongside each slide's prompt. Say in your prompt how the images should be used — for example: * **As a style reference:** `"...Match the visual style of the attached reference image."` * **As a logo:** `"...Include the attached logo in the corner of every slide."` * **As content:** `"...Use the attached product photo as the centerpiece of the slide about the product."` Attachments that aren't mentioned in the prompt may have little or no effect on the output. Non-image attachments (PDFs, docs, etc.) are used as source content for the outline in both generation modes. ```json { "prompt": "A 5-slide deck on our Q3 roadmap. Match the visual style of the attached reference image.", "generationMode": "IMAGES", "attachments": [{ "fileId": "" }] } ``` #### Example Request ``` curl \ -X POST \ -H "Content-Type: application/json" \ -H "authorization: Bearer $PLUSAI_API_TOKEN" \ -v \ -d '{"prompt": "a presentation about cows"}' \ https://api.plusdocs.com/r/v0/presentation ``` #### Response The response from the create presentations endpoint will contain a polling endpoint that you can use to access your generated presentation when it finishes generating. ``` { "pollingUrl": "https://api.plusdocs.com/r/v0/presentation/cmffgfzpa00027vidien49upq", "status": "PROCESSING" } ``` ## **Polling for Generated Presentation** ``` GET /v0/presentation/:presentationId ``` Poll this endpoint to check the progress of a presentation generation request. When the status field in the response returns as "GENERATED" (slides mode) or "COMPLETED" (image mode), your presentation file will be included in the request and ready to be downloaded. #### Path Parameters | Name | Required | Type | Description | | ------------------ | -------- | ------ | --------------------------------------------- | | **presentationId** | Yes | string | The ID of the presentation generation request | #### Example Request ``` curl \ -X GET \ -H "Content-Type: application/json" \ -H "authorization: Bearer $PLUSAI_API_TOKEN" \ https://api.plusdocs.com/r/v0/presentation/cmffj17kx0002snyqykn2my2x ``` #### Response 

{
  "createdAt": "2025-09-11T14:51:46.977Z",
  "id": "cmffj17kx0002snyqykn2my2x",
  "language": "en",
  "slides": null,
  "status": "PROCESSING",
  "updatedAt": "2025-09-11T14:52:43.195Z",
  "url": null
}
``` { "createdAt": "2025-09-11T14:51:46.977Z", "id": "cmffj17kx0002snyqykn2my2x", "language": "en", "slides": [ "The History of Cows", "Contents", "Origins of Cows", "Ancient Uses of Cows", "Cows in Different Cultures", "Modern Cattle Breeding", "Economic Impact of Cows", "Environmental Considerations", "Future of Cattle Farming", "Summary and Conclusion", "Thank You" ], "status": "GENERATED", "updatedAt": "2025-09-11T14:52:43.195Z", "url": "https://d2q8qai8hhcosn.cloudfront.net/3245870997/organization/cmffd8fk8000112le1tnx5osw/presentation/cmffj17kx0002snyqykn2my2x/pptx/presentation-84815c3a-2307-40fc-93c9-2f5776778d00.pptx" } ``` ## Polling for all Generated Presentations ``` GET /v0/presentations ``` Poll this endpoint to retrieve all generated presentations you have created via the Presentations API. *Note: This endpoint currently only shows the last 100 generated presentations.* #### Example Request ``` curl \ -X GET \ -H "Content-Type: application/json" \ -H "authorization: Bearer $PLUSAI_API_TOKEN" \ https://api.plusdocs.com/r/v0/presentations ``` #### Response ``` { "presentations": [ { "id": "cmffj17kx0002snyqykn2my2x", "name": "A brief history of cows", "status": "GENERATED", "url": "https://d2q8qai8hhcosn.cloudfront.net/3245870997/organization/cmffd8fk8000112le1tnx5osw/presentation/cmffj17kx0002snyqykn2my2x/pptx/presentation-84815c3a-2307-40fc-93c9-2f5776778d00.pptx" }, { "id": "cmffgfzpa00027vidien49upq", "name": "Dinsoaurs: A look into the past", "status": "GENERATED", "url": "https://d2q8qai8hhcosn.cloudfront.net/3245870997/organization/cmffd8fk8000112le1tnx5osw/presentation/cmffgfzpa00027vidien49upq/pptx/presentation-84815c3a-2307-40fc-93c9-293jh45kj00.pptx" }, ] } ``` ## POST /r/v0/presentation > Generate a presentation from a prompt ```json {"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Presentations","description":"Generate presentations from a text prompt."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"CreatePresentationRequest":{"type":"object","properties":{"prompt":{"type":"string"},"language":{"type":"string","default":"en"},"numberOfSlides":{"type":"integer"},"textHandling":{"type":"string","description":"How existing text content should be handled."},"includeUserTips":{"type":"boolean","default":false},"templateId":{"type":"string"}},"required":["prompt"]},"CreatePresentationResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"pollingUrl":{"type":"string","format":"uri"}},"required":["id","status","pollingUrl"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"BadRequest":{"description":"The request was malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/presentation":{"post":{"operationId":"createPresentation","tags":["Presentations"],"summary":"Generate a presentation from a prompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePresentationRequest"}}}},"responses":{"201":{"description":"Presentation generation started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePresentationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"Concurrent presentation processing limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## GET /r/v0/presentation/{presentationId} > Get a presentation ```json {"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Presentations","description":"Generate presentations from a text prompt."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"Presentation":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"language":{"type":["string","null"]},"slides":{"type":["array","null"],"items":{"type":"string"},"description":"Slide titles."},"url":{"type":["string","null"],"format":"uri","description":"URL to the full generated PPTX."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"BadRequest":{"description":"The request was malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/presentation/{presentationId}":{"get":{"operationId":"getPresentation","tags":["Presentations"],"summary":"Get a presentation","parameters":[{"name":"presentationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The presentation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Presentation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Presentation not found."}}}}}} ``` ## List presentations > Returns up to 50 of the presentations created via this API. ```json {"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Presentations","description":"Generate presentations from a text prompt."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"Presentation":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"language":{"type":["string","null"]},"slides":{"type":["array","null"],"items":{"type":"string"},"description":"Slide titles."},"url":{"type":["string","null"],"format":"uri","description":"URL to the full generated PPTX."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"BadRequest":{"description":"The request was malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/presentations":{"get":{"operationId":"listPresentations","tags":["Presentations"],"summary":"List presentations","description":"Returns up to 50 of the presentations created via this API.","responses":{"200":{"description":"A list of presentations.","content":{"application/json":{"schema":{"type":"object","properties":{"presentations":{"type":"array","items":{"$ref":"#/components/schemas/Presentation"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Code Samples ### cURL Example (Presentation Creation + Polling) ```bash PLUSAI_API_TOKEN="YOUR_TOKEN_HERE" \ PROMPT="the history of cows" \ payload=$(jq -n --arg prompt "$PROMPT" '{prompt:$prompt}'); \ polling_url=$(curl -s -X POST \ -H "authorization: Bearer $PLUSAI_API_TOKEN" \ -H "Content-Type: application/json" \ https://api.plusdocs.com/r/v0/presentation \ -d "$payload" | jq -r '.pollingUrl'); \ while :; do \ resp=$(curl -s -H "authorization: Bearer $PLUSAI_API_TOKEN" "$polling_url"); \ status=$(echo "$resp" | jq -r '.status'); \ if [ "$status" = "GENERATED" ]; then \ echo "$resp" | jq; \ break; \ elif [ "$status" = "FAILED" ]; then \ echo "$resp" | jq; \ exit 1; \ else \ sleep 5; \ fi; \ done ``` ### Python Example (Presentation Creation + Polling) ```python import time import requests API_BASE_URL = "https://api.plusdocs.com/r/v0" PLUSAI_API_TOKEN = "YOUR_TOKEN_HERE" def create_request( prompt: str, retry: int = 0, backoff_delay: float = 1.5, ) -> tuple[str, str]: request = requests.post( f"{API_BASE_URL}/presentation", headers={ "accept": "application/json", "authorization": f"Bearer {PLUSAI_API_TOKEN}", "Content-Type": "application/json", }, json={ "prompt": prompt, }, ) if request.status_code == 429: if retry >= 3: raise Exception( f"Plus AI API request retries exhausted {request.status_code}: {request.text}" ) delay = backoff_delay * (2**retry) # Exponential backoff print(f"Rate limit exceeded, retrying in {delay} seconds...") time.sleep(delay) return create_request(prompt, retry + 1, backoff_delay * 2) if request.status_code not in [200, 201, 429]: raise Exception( f"Plus AI API request failed with status code {request.status_code}: {request.text}" ) data = request.json() request_id = data["id"] polling_url = data["pollingUrl"] return request_id, polling_url def poll_for_result( request_id: str, polling_url: str, timeout: int = 300, wait_time: int = 5 ) -> str | None: start_time = time.time() while True: time.sleep(wait_time) elapsed_time = time.time() - start_time if elapsed_time > timeout: print( f"Polling timed out after {timeout} seconds for request {request_id}." ) return None print(f"Polling for result of generation request {request_id} ...") result = requests.get( polling_url, headers={ "accept": "application/json", "authorization": f"Bearer {PLUSAI_API_TOKEN}", }, params={"id": request_id}, ).json() if result["status"] == "GENERATED": print( f"Generation request {request_id} completed in {time.time() - start_time:.2f} seconds." ) return result["url"] elif result["status"] in ["FAILED"]: print(f"Generation failed: {result}") return None def generate_presentation(prompt: str) -> str | None: request_id, polling_url = create_request(prompt=prompt) time.sleep(30) pptx_url = poll_for_result(request_id, polling_url) if not pptx_url: print("No result returned from the generation request.") return None return pptx_url ``` ```python generate_presentation( "Create a presentation about the history of the internet." ) ``` ### Plus Template IDs If you would like to use a specific Plus template for your presentation generation you can use the associated template ID in your cURL request.
Template IDs | Template Name | Template ID | | ---------------------- | ------------------------------------ | | Aurora | EPX9O042Z6Sv6iQzbuARhS | | Blackboard | ZudB2GVFiv1KzcgdRsbfM8 | | Brut Brick | p8pxA5qoot1I2WffVbQFaj | | Brut Seascape | QBtFc6rV16vJpMoiX6vb8l | | Brut Tigris | kOqAdCKG7xojGCT4ZfXSK4 | | Composition Book | ZudB2GVFiv1KzcgdRz9FC6 | | Corporate Blue | XFzedsfTQ3ccCtO09ZWSav | | Editorial | p8pxA5qoot1I2WffVcrm2D | | Feemo | OjeLTqC7loN3OmaqHD0qby | | Forest Floor | kOqAdCKG7xojGCT4ZfbYAV | | Fred | N12Yg407RXsoVq9xji1jA9 | | Herbert | N12Yg407RXsoVq9xjoYtXV | | Indigo | p8pxA5qoot1I2WffVd69nF | | Insight | iG190W6PEa3wEoxBjE7gtz | | Insight Bold | D9fCV9f59UZFiLIMMzUMhy | | Insight Modern | D9fCV9f59UZFiLIMLoUj3k | | Kin | N12Yg407RXsoVq9xjozV7a | | Mallorca | kqplMC1wKwvcjVhxZGoAQa | | Manila | nXmZO8Fk1P14FXUEQFD78H | | Metro | kqplMC1wKwvcjVhxZGqBaa | | Minimalist Light | XFzedsfTQ3ccCtO09a4pZt | | Modern Sketchpad | OjeLTqC7loN3OmaqHMjIIF | | Modernist Professional | kqplMC1wKwvcjVhxZGz9ia | | Modernist Siena | XFzedsfTQ3ccCtO09aA7vY | | Plus Default | d1e65e54-753c-4368-946b-ddb430583b0d | | Potpourri | 1jelx0KVU9F6jq1WcIQDsD | | Simple Notebook | nXmZO8Fk1P14FXUEQFFZEp | | Spiral Notebook | N12Yg407RXsoVq9xk7LMTR | | Swiss Dark | XFzedsfTQ3ccCtO09aCCgD | | Swiss Light | kqplMC1wKwvcjVhxZHI0qO |
Creating presentations via API with your custom branding or custom template is currently available for Enterprise accounts. If you'd like to inquire about Enterprise please contact us at . ### Rate Limits and Restrictions The Presentations API is currently in beta, and has a rate limit of 3 presentation creation requests a minute. ### Files API ## Upload a file > Uploads a file as \`multipart/form-data\`. The upload is validated and\ > accepted synchronously, then processed asynchronously.\ > \ > Constraints:\ > \- The request method must be \`PUT\`.\ > \- \`Content-Type\` must be \`multipart/form-data\`.\ > \- \`Content-Length\` is required (chunked transfer encoding is not\ > supported).\ > \- Maximum size is 125 MB.
```json {"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Files","description":"Upload, list, and delete user files."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"UploadAccepted":{"type":"object","properties":{"status":{"type":"string"},"uploadId":{"type":"string"},"message":{"type":"string"}},"required":["status","uploadId","message"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"UploadError":{"type":"object","description":"Error envelope returned by the file-upload endpoint.","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/files/upload":{"put":{"operationId":"uploadFile","tags":["Files"],"summary":"Upload a file","description":"Uploads a file as `multipart/form-data`. The upload is validated and\naccepted synchronously, then processed asynchronously.\n\nConstraints:\n- The request method must be `PUT`.\n- `Content-Type` must be `multipart/form-data`.\n- `Content-Length` is required (chunked transfer encoding is not\n supported).\n- Maximum size is 125 MB.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload."}},"required":["file"]}}}},"responses":{"202":{"description":"File received; processing will begin shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"Method not allowed (must use PUT).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}},"411":{"description":"Content-Length header is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}},"413":{"description":"File exceeds the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}},"415":{"description":"Content-Type must be multipart/form-data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://guide.plusai.com/apis-for-presentations/presentations-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.