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

# Models

## The Template object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"Template":{"type":"string","description":"Design theme id (case-sensitive, no spaces). Custom user-uploaded templates are not supported via the public API.","enum":["Tokyo","NewYork","Seoul","Rome","Berlin","Copenhagen","Oslo","Rotterdam","Cambridge","Houston"],"default":"Tokyo"}}}}
```

## The OutputFormat object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"OutputFormat":{"type":"string","description":"Output file format.","enum":["pptx","pdf"],"default":"pptx"}}}}
```

## The ImageSource object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"ImageSource":{"type":"string","description":"Where slide images come from. `unsplash`/`pexels`/`scrapingdog` are stock; `ai`/`flux` are AI-generated.","enum":["unsplash","pexels","scrapingdog","ai","flux"],"default":"unsplash"}}}}
```

## The ImageStyle object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"ImageStyle":{"type":"string","description":"Image style. Applies only when `imageSource` is `ai` or `flux`.","enum":["auto","photorealistic","illustration","neon","abstract","black-and-white","3d","linear"]}}}}
```

## The NumSlides object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"NumSlides":{"type":"integer","description":"Slide count: `-1` for auto, or `1`–`50`. `0` is invalid.","oneOf":[{"const":-1,"description":"Automatic slide count."},{"minimum":1,"maximum":50}],"default":-1}}}}
```

## The ContentVerbosity object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"ContentVerbosity":{"type":"string","description":"Text verbosity of the generated slides.","enum":["short","detailed","bulletPoints"]}}}}
```

## The ContentModificator object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"ContentModificator":{"type":"string","description":"How the source content is treated when building slides.","enum":["preserve","expand","condense"],"default":"expand"}}}}
```

## The TextDensity object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"TextDensity":{"type":"string","description":"Density of text on each slide.","enum":["minimal","concise","detailed"],"default":"concise"}}}}
```

## The PresentationType object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"PresentationType":{"type":"string","enum":["General","Educational Project","Business Pitch","Reports and Insights"]}}}}
```

## The TopicRequest object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"TopicRequest":{"type":"object","required":["topic"],"properties":{"topic":{"type":"string","maxLength":450,"description":"Subject of the presentation."},"numSlides":{"$ref":"#/components/schemas/NumSlides"},"language":{"type":"string","description":"Output language. Defaults to auto-detect."},"template":{"$ref":"#/components/schemas/Template"},"format":{"$ref":"#/components/schemas/OutputFormat"},"imageSource":{"$ref":"#/components/schemas/ImageSource"},"imageStyle":{"$ref":"#/components/schemas/ImageStyle"},"content":{"$ref":"#/components/schemas/ContentVerbosity","description":"Text verbosity. Defaults to `detailed`."},"presentationType":{"$ref":"#/components/schemas/PresentationType"},"targetAudience":{"type":"string","maxLength":200,"description":"Free-text audience description."},"toneAndStyle":{"type":"string","maxLength":200,"description":"Free-text tone/style description."},"debugMode":{"type":"boolean","default":false,"description":"Internal diagnostics."}},"additionalProperties":false},"NumSlides":{"type":"integer","description":"Slide count: `-1` for auto, or `1`–`50`. `0` is invalid.","oneOf":[{"const":-1,"description":"Automatic slide count."},{"minimum":1,"maximum":50}],"default":-1},"Template":{"type":"string","description":"Design theme id (case-sensitive, no spaces). Custom user-uploaded templates are not supported via the public API.","enum":["Tokyo","NewYork","Seoul","Rome","Berlin","Copenhagen","Oslo","Rotterdam","Cambridge","Houston"],"default":"Tokyo"},"OutputFormat":{"type":"string","description":"Output file format.","enum":["pptx","pdf"],"default":"pptx"},"ImageSource":{"type":"string","description":"Where slide images come from. `unsplash`/`pexels`/`scrapingdog` are stock; `ai`/`flux` are AI-generated.","enum":["unsplash","pexels","scrapingdog","ai","flux"],"default":"unsplash"},"ImageStyle":{"type":"string","description":"Image style. Applies only when `imageSource` is `ai` or `flux`.","enum":["auto","photorealistic","illustration","neon","abstract","black-and-white","3d","linear"]},"ContentVerbosity":{"type":"string","description":"Text verbosity of the generated slides.","enum":["short","detailed","bulletPoints"]},"PresentationType":{"type":"string","enum":["General","Educational Project","Business Pitch","Reports and Insights"]}}}}
```

## The TextRequest object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"TextRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Source text. Maximum 390,000 tokens, measured with the `gpt-3.5-turbo` tokenizer. Exceeding the limit returns `400 BAD_REQUEST` with `tokensCount` and `tokenLimit` in the error body.\n"},"numSlides":{"$ref":"#/components/schemas/NumSlides"},"template":{"$ref":"#/components/schemas/Template"},"format":{"$ref":"#/components/schemas/OutputFormat"},"contentModificator":{"$ref":"#/components/schemas/ContentModificator"},"textDensity":{"$ref":"#/components/schemas/TextDensity"},"verbosity":{"$ref":"#/components/schemas/ContentVerbosity"},"imageSource":{"$ref":"#/components/schemas/ImageSource"},"imageStyle":{"$ref":"#/components/schemas/ImageStyle"},"debugMode":{"type":"boolean","default":false}},"additionalProperties":false},"NumSlides":{"type":"integer","description":"Slide count: `-1` for auto, or `1`–`50`. `0` is invalid.","oneOf":[{"const":-1,"description":"Automatic slide count."},{"minimum":1,"maximum":50}],"default":-1},"Template":{"type":"string","description":"Design theme id (case-sensitive, no spaces). Custom user-uploaded templates are not supported via the public API.","enum":["Tokyo","NewYork","Seoul","Rome","Berlin","Copenhagen","Oslo","Rotterdam","Cambridge","Houston"],"default":"Tokyo"},"OutputFormat":{"type":"string","description":"Output file format.","enum":["pptx","pdf"],"default":"pptx"},"ContentModificator":{"type":"string","description":"How the source content is treated when building slides.","enum":["preserve","expand","condense"],"default":"expand"},"TextDensity":{"type":"string","description":"Density of text on each slide.","enum":["minimal","concise","detailed"],"default":"concise"},"ContentVerbosity":{"type":"string","description":"Text verbosity of the generated slides.","enum":["short","detailed","bulletPoints"]},"ImageSource":{"type":"string","description":"Where slide images come from. `unsplash`/`pexels`/`scrapingdog` are stock; `ai`/`flux` are AI-generated.","enum":["unsplash","pexels","scrapingdog","ai","flux"],"default":"unsplash"},"ImageStyle":{"type":"string","description":"Image style. Applies only when `imageSource` is `ai` or `flux`.","enum":["auto","photorealistic","illustration","neon","abstract","black-and-white","3d","linear"]}}}}
```

## The FileRequest object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"FileRequest":{"type":"object","required":["file"],"description":"multipart/form-data body. All non-file fields arrive as strings; the API coerces `numSlides` and `debugMode`.\n","properties":{"file":{"type":"string","format":"binary","description":"Source document, max 25 MB. Accepted types (validated via magic-byte sniffing): PDF (`application/pdf`), PowerPoint (`application/vnd.openxmlformats-officedocument.presentationml.presentation`), Word (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`), plain text (`text/plain`).\n"},"numSlides":{"type":"string","description":"Slide count as a string: `-1` for auto, or `1`–`50`."},"template":{"$ref":"#/components/schemas/Template"},"format":{"$ref":"#/components/schemas/OutputFormat"},"contentModificator":{"$ref":"#/components/schemas/ContentModificator"},"textDensity":{"$ref":"#/components/schemas/TextDensity"},"verbosity":{"$ref":"#/components/schemas/ContentVerbosity"},"imageSource":{"$ref":"#/components/schemas/ImageSource"},"imageStyle":{"$ref":"#/components/schemas/ImageStyle"},"debugMode":{"type":"string","enum":["true","false"],"default":"false","description":"Boolean as string in form-data."}}},"Template":{"type":"string","description":"Design theme id (case-sensitive, no spaces). Custom user-uploaded templates are not supported via the public API.","enum":["Tokyo","NewYork","Seoul","Rome","Berlin","Copenhagen","Oslo","Rotterdam","Cambridge","Houston"],"default":"Tokyo"},"OutputFormat":{"type":"string","description":"Output file format.","enum":["pptx","pdf"],"default":"pptx"},"ContentModificator":{"type":"string","description":"How the source content is treated when building slides.","enum":["preserve","expand","condense"],"default":"expand"},"TextDensity":{"type":"string","description":"Density of text on each slide.","enum":["minimal","concise","detailed"],"default":"concise"},"ContentVerbosity":{"type":"string","description":"Text verbosity of the generated slides.","enum":["short","detailed","bulletPoints"]},"ImageSource":{"type":"string","description":"Where slide images come from. `unsplash`/`pexels`/`scrapingdog` are stock; `ai`/`flux` are AI-generated.","enum":["unsplash","pexels","scrapingdog","ai","flux"],"default":"unsplash"},"ImageStyle":{"type":"string","description":"Image style. Applies only when `imageSource` is `ai` or `flux`.","enum":["auto","photorealistic","illustration","neon","abstract","black-and-white","3d","linear"]}}}}
```

## The Me object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"Me":{"type":"object","description":"Account associated with the API key.","required":["userId","email","plan","credits"],"properties":{"userId":{"type":"integer","description":"Internal account id."},"email":{"type":"string","format":"email","description":"Account owner's email address."},"plan":{"type":"string","description":"Subscription plan of the account (e.g., `pro`, `team`)."},"credits":{"type":"object","required":["remaining"],"properties":{"remaining":{"type":["integer","null"],"description":"Remaining generation credits. `null` for internal/unlimited keys.\n"}}}}}}}}
```

## The JobStatus object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"JobStatus":{"type":"string","enum":["queued","processing","completed","failed"]}}}}
```

## The JobAccepted object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"JobAccepted":{"type":"object","description":"Job descriptor returned by all POST endpoints.","required":["id","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/JobStatus"},"createdAt":{"type":"string","format":"date-time"}}},"JobStatus":{"type":"string","enum":["queued","processing","completed","failed"]}}}}
```

## The Job object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"Job":{"type":"object","required":["id","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/JobStatus"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","description":"Present only when `status` is `completed` or `failed`."},"result":{"type":"object","description":"Present only when `status` is `completed`.","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Permanent download URL for the generated PPTX/PDF."}}},"error":{"type":"object","description":"Present only when `status` is `failed`.","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/JobErrorCode"},"message":{"type":"string","description":"Human-readable failure reason."}}}}},"JobStatus":{"type":"string","enum":["queued","processing","completed","failed"]},"JobErrorCode":{"type":"string","description":"Job-level failure codes:\n- `TIMEOUT` — generation exceeded the soft timeout\n- `WORKER_TIMEOUT` — worker aborted the job (default 5 min)\n- `UPSTREAM_FAILURE` — underlying AI/build pipeline failed; retry\n- `UNSUPPORTED_TEMPLATE` — custom (user-uploaded) templates are not supported via the public API\n- `INPUT_TOO_LARGE` — source content exceeded internal processing limits\n","enum":["TIMEOUT","WORKER_TIMEOUT","UPSTREAM_FAILURE","UNSUPPORTED_TEMPLATE","INPUT_TOO_LARGE"]}}}}
```

## The JobErrorCode object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"JobErrorCode":{"type":"string","description":"Job-level failure codes:\n- `TIMEOUT` — generation exceeded the soft timeout\n- `WORKER_TIMEOUT` — worker aborted the job (default 5 min)\n- `UPSTREAM_FAILURE` — underlying AI/build pipeline failed; retry\n- `UNSUPPORTED_TEMPLATE` — custom (user-uploaded) templates are not supported via the public API\n- `INPUT_TOO_LARGE` — source content exceeded internal processing limits\n","enum":["TIMEOUT","WORKER_TIMEOUT","UPSTREAM_FAILURE","UNSUPPORTED_TEMPLATE","INPUT_TOO_LARGE"]}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","description":"Uniform error envelope for all 4xx/5xx responses.","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","UNPROCESSABLE_ENTITY","RATE_LIMIT_EXCEEDED","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable message. For invalid enum fields, lists the allowed values.\n"},"status":{"type":"integer","description":"HTTP status code mirrored in the body."},"request_id":{"type":"string","description":"Present only on 5xx — include in support tickets."}},"additionalProperties":true}}}}}}
```

## The TextTokenLimitError object

```json
{"openapi":"3.1.0","info":{"title":"Twistly Presentation Generation API","version":"1.0.0"},"components":{"schemas":{"TextTokenLimitError":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"tokensCount":{"type":"integer","description":"Token count of the submitted text."},"tokenLimit":{"type":"integer","description":"Maximum allowed tokens (390,000)."}}}}}]},"ErrorResponse":{"type":"object","description":"Uniform error envelope for all 4xx/5xx responses.","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","UNPROCESSABLE_ENTITY","RATE_LIMIT_EXCEEDED","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable message. For invalid enum fields, lists the allowed values.\n"},"status":{"type":"integer","description":"HTTP status code mirrored in the body."},"request_id":{"type":"string","description":"Present only on 5xx — include in support tickets."}},"additionalProperties":true}}}}}}
```