Template Converter API

The Template Converter API applies a target brand template to an uploaded deck. The pipeline is asynchronous: kick off a job with POST /api/v1/template-conversions, then poll the recommended v2 status endpoint until the workflow reaches a terminal state.

REST resource paths (v1.1). This page documents the REST-resource path names (/api/v1/template-conversions/...). The legacy RPC-style paths under /api/v1/template-converter/* continue to be served indefinitely — they return a Deprecation: true header pointing to the successor alias documented here. New integrations should use the paths shown on this page.

Full schemas, request/response examples, and per-field documentation live in the interactive API Reference.

Skip the polling loop. If you can expose an HTTPS endpoint, subscribe to template_conversion.completed / template_conversion.failed via the Webhooks API and receive signed completion callbacks instead of polling for status.

Authentication

All endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

See Getting Started → Authentication for details.

Response envelope

Every endpoint returns the canonical envelope:

{ "success": true, "data": { "..." } }

…or, on error:

{ "success": false, "data": null, "error": { "code": "...", "message": "..." } }

Endpoint summary

Method	Path	Description	Sync/Async
`POST`	`/api/v1/template-conversions`	Create a template-conversion job	Async
`GET`	`/api/v2/template-converter/status/{callback_id}`	Recommended. Poll a job with strict HTTP-status mapping	Sync
`GET`	`/api/v1/templates?feature=template_converter`	List templates available to Template Converter	Sync
`POST`	`/api/v1/template-conversions/preprocessings`	Upload a PPTX in chunks	Sync
`POST`	`/api/v1/template-conversions/finalisations`	Finalise a chunked PPTX upload	Sync
`GET`	`/api/v1/template-conversions/{callback_id}/review-suggestions`	Get editorial review suggestions	Sync
`PATCH`	`/api/v1/template-conversions/{callback_id}/review-suggestions`	Apply a subset of review suggestions	Async
`POST`	`/api/v1/template-conversions/{callback_id}/template-changes`	Re-convert to a different template	Async
`GET`	`/api/v1/template-conversions/{callback_id}/download`	Get a signed download URL	Sync
`POST`	`/api/v1/template-conversions/{callback_id}/comply-metrics`	Record Comply metrics	Sync
`PUT`	`/api/v1/template-conversions/{callback_id}/reactions`	Record like / feedback (PUT, legacy quirk)	Sync
`GET`	`/api/v1/template-conversions/{callback_id}/work-area-options`	Get work-area options for a slide	Sync
`POST`	`/api/v1/template-conversions/{callback_id}/work-area-adjustments`	Apply a work-area adjustment	Sync
`GET`	`/api/v1/template-conversions/{callback_id}/layouts`	Get layout options for a slide / deck	Sync
`POST`	`/api/v1/template-conversions/{callback_id}/layout-updates`	Change the layout of a slide	Async
`POST`	`/api/v1/template-conversions/{callback_id}/format-modifications`	Apply title/body formatting changes	Async
`GET`	`/api/v1/template-conversions/{callback_id}/format-modifications/settings`	Get available modify-format settings	Sync

All endpoints are in the template_converter rate-limit category. The start and download operations also count against per-key annual usage quotas (negotiated per customer — contact CS for your tier). See Developer Guide → Usage quotas and rate limits.

`POST /api/v1/template-conversions` — Create a conversion

Kicks off a template-conversion pipeline. Returns a callback_id to poll. Counts against the TC_START usage limit.

Pass either fileId (an id returned by a previous upload) or inputDeck (an inline reference to the input deck) — never both.

Request body

Field	Type	Required	Description
`fileId`	string	conditional	Id of a previously uploaded input deck.
`inputDeck`	object	conditional	Inline reference to the input deck (S3 path / chunk identifier).
`templateName`	string	yes	Name of the target brand template.
`includeImageWithoutData`	boolean	no	Carry over images that have no associated data.
`includeImageWithData`	boolean	no	Carry over images that have associated data.
`includeIcons`	boolean	no	Carry over icons.
`includeSpecialColor`	boolean	no	Preserve special color treatments.
`settings`	object	no	Per-conversion settings (`ai_mode`, `work_area_option`, `modifyFormat`, `color_preference`, `content_formatting`).
`modifyFormat`	object	no	Optional top-level format overrides.

Example

cURL
Python
Node.js

curl -X POST https://api.prezent.ai/api/v1/template-conversions \
  -H "Authorization: Bearer $PREZENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "file_abc123",
    "templateName": "Corporate 2024",
    "includeImageWithData": true,
    "settings": {
      "ai_mode": "balanced",
      "color_preference": "brand"
    }
  }'

import os
import requests

url = "https://api.prezent.ai/api/v1/template-conversions"
headers = {
    "Authorization": f"Bearer {os.environ['PREZENT_API_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "fileId": "file_abc123",
    "templateName": "Corporate 2024",
    "includeImageWithData": True,
    "settings": {
        "ai_mode": "balanced",
        "color_preference": "brand",
    },
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

const axios = require('axios');

const createConversion = async () => {
  const { data } = await axios.post(
    'https://api.prezent.ai/api/v1/template-conversions',
    {
      fileId: 'file_abc123',
      templateName: 'Corporate 2024',
      includeImageWithData: true,
      settings: {
        ai_mode: 'balanced',
        color_preference: 'brand'
      }
    },
    {
      headers: {
        Authorization: `Bearer ${process.env.PREZENT_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log(data);
  return data.data.callback_id;
};

createConversion();

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "token": "tok_one_time_xyz",
    "presentation_name": "Q3 review.pptx",
    "status": "in_progress"
  }
}

`GET /api/v2/template-converter/status/{callback_id}` — Poll a job (v2, strict mapping)

The recommended polling endpoint for the Template Converter family. Uses strict HTTP-status mapping so agents can branch on HTTP status alone, without inspecting body fields.

200 OK — Conversion has completed successfully.
202 Accepted — Conversion is still in progress.
4xx / 5xx — Workflow failure, with the standard error envelope.

A separate v1 polling endpoint exists for backwards compatibility; it always returns HTTP 200 and requires inspecting data.status. New integrations should not use it. The v2 status path will be renamed to /api/v2/template-conversions/{callback_id} in a future cleanup; until then it continues to live at the path above.

Path parameters

Parameter	Type	Required	Description
`callback_id`	string	yes	Conversion job id (from `POST /api/v1/template-conversions`).

Query parameters

Parameter	Type	Required	Description
`source`	string (`nexus`)	no	Pass `nexus` to include the full `outputs` blob in the response.

Example

cURL
Python
Node.js

curl -i "https://api.prezent.ai/api/v2/template-converter/status/cb_tc_xyz" \
  -H "Authorization: Bearer $PREZENT_API_KEY"

import os
import requests

url = "https://api.prezent.ai/api/v2/template-converter/status/cb_tc_xyz"
headers = {
    "Authorization": f"Bearer {os.environ['PREZENT_API_KEY']}",
}

response = requests.get(url, headers=headers)

# Strict status mapping: 200 = done, 202 = in progress, 4xx/5xx = failure
print(response.status_code)
print(response.json())

const axios = require('axios');

const pollStatus = async () => {
  const response = await axios.get(
    'https://api.prezent.ai/api/v2/template-converter/status/cb_tc_xyz',
    {
      headers: {
        Authorization: `Bearer ${process.env.PREZENT_API_KEY}`
      },
      // Inspect 202 (in progress) without throwing
      validateStatus: (status) => status < 500
    }
  );

  // Strict status mapping: 200 = done, 202 = in progress, 4xx/5xx = failure
  console.log(response.status);
  console.log(response.data);
};

pollStatus();

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "status": "success",
    "presentation_name": "Q3 review (Corporate 2024).pptx",
    "template_name": "Corporate 2024",
    "outputs": { "...": "..." }
  }
}

In-progress response (`202`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "status": "in_progress",
    "presentation_name": "Q3 review.pptx",
    "template_name": "Corporate 2024",
    "progress": { "stage": "rendering", "percent": 67 }
  }
}

Failure responses

On workflow failure the response is 4xx or 5xx with the standard error envelope:

{
  "success": false,
  "data": null,
  "error": {
    "code": "EXTERNAL_SERVICE_ERROR",
    "message": "Conversion failed at the layout-resolution stage.",
    "details": { "stage": "layout" }
  }
}

HTTP	Typical codes
`400`	`MISSING_CALLBACK_ID`, `INVALID_INPUT`.
`401`	`UNAUTHORIZED`, `INVALID_API_KEY`, `EXPIRED_API_KEY`.
`404`	`RESOURCE_NOT_FOUND` (unknown `callback_id`).
`422`	`UNPROCESSABLE_ENTITY` (job was malformed at start).
`429`	`RATE_LIMIT_EXCEEDED`, `USAGE_LIMIT_EXCEEDED`.
`500`	`INTERNAL_SERVER_ERROR`.
`502`	`EXTERNAL_SERVICE_ERROR` (downstream conversion pipeline error).
`503`	`SERVICE_UNAVAILABLE`.
`504`	`GATEWAY_TIMEOUT`.

`GET /api/v1/templates?feature=template_converter` — List templates

Returns themes/templates available to Template Converter. This single endpoint replaces the legacy /api/v1/autogenerator/templates and /api/v1/template-converter/templates paths — pass feature to scope results.

Query parameters

Parameter	Type	Required	Description
`feature`	string (`auto_generator` / `template_converter`)	no	Filter to templates enabled for a specific feature.
`name`	string	no	Case-insensitive name filter.
`sort`	string	no	Sort expression.
`source`	string	no	Source filter.

Success response (`200`)

{
  "success": true,
  "data": {
    "items": [
      { "id": "tmpl_corp_2024", "name": "Corporate 2024", "code": "CORP24", "source": "brand" }
    ],
    "next_cursor": null
  }
}

Chunked upload — `preprocessings` + `finalisations`

For input decks too large to send in a single request, use the chunked-upload flow.

`POST /api/v1/template-conversions/preprocessings`

Accepts one chunk of a multi-chunk PPTX upload. See the shared schema on the File Upload page (PreprocessFileRequest).

Only .pptx files are accepted.

`POST /api/v1/template-conversions/finalisations`

Concludes the chunked upload identified by fileIdentifier. The finalised file must be a .pptx, no larger than 200 MB, and no more than 100 pages.

Request body

Field	Type	Required	Description
`fileIdentifier`	string	yes	Identifier shared across all chunks.
`fileName`	string	yes	Final filename. Must end in `.pptx`.

Success response (`200`)

{
  "success": true,
  "data": {
    "file_id": "file_abc123",
    "s3_prefix": "uploads/co_xyz/file_abc123/",
    "s3_bucket": "prezent-uploads",
    "type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
    "size_kb": 18432,
    "num_of_pages": 42
  }
}

data.file_id is what you pass to POST /api/v1/template-conversions as fileId.

Smart-edit endpoints

These endpoints let you refine an already-converted deck without re-running the full conversion from scratch.

`GET /api/v1/template-conversions/{callback_id}/review-suggestions`

Returns the editorial suggestions produced for the converted deck.

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "presentation_name": "Q3 review (Corporate 2024).pptx",
    "suggestions": [ { "..." : "..." } ]
  }
}

`PATCH /api/v1/template-conversions/{callback_id}/review-suggestions`

Applies a subset of suggestions. Kicks off a background pipeline; the response carries a new callback_id to poll.

Request body

{
  "suggestions": [
    { "id": "sug_1", "accepted": true },
    { "id": "sug_2", "accepted": false }
  ]
}

Success response (`200`)

{ "success": true, "data": { "callback_id": "cb_tc_xyz_v2" } }

`POST /api/v1/template-conversions/{callback_id}/template-changes`

Re-runs the conversion pipeline for an already-converted deck against a different templateName. Returns a new callback_id to poll.

Request body

Field	Type	Required	Description
`templateName`	string	yes	New target brand template name.
`settings`	object	no	Override conversion settings.

Success response (`200`)

{ "success": true, "data": { "callback_id": "cb_tc_xyz_v3" } }

`GET /api/v1/template-conversions/{callback_id}/work-area-options`

Returns available work-area adjustment options for a slide.

Path parameters

Parameter	Type	Required	Description
`callback_id`	string	yes	Conversion job id.

Query parameters

Parameter	Type	Required	Description
`slide_index`	integer ≥ 0	yes	Zero-based slide index.

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "work_area_adjustments": [ { "..." : "..." } ]
  }
}

`POST /api/v1/template-conversions/{callback_id}/work-area-adjustments`

Applies a selected work-area adjustment to a slide.

Request body

Field	Type	Required	Description
`slide_index`	integer ≥ 0	yes	Zero-based slide index.
`selection`	object	yes	Selected work-area-option payload.

Success response (`200`)

{ "success": true, "data": { "message": "Adjustment applied." } }

`GET /api/v1/template-conversions/{callback_id}/layouts`

Returns available layouts for the target template and, optionally, the input deck's layouts for a slide.

Path parameters

Parameter	Type	Required	Description
`callback_id`	string	yes	Conversion job id.

Query parameters

Parameter	Type	Required	Description
`slide_index`	integer ≥ 0	no	Zero-based slide index. Omit to return layouts for every slide.

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "status": "success",
    "layouts": {
      "target_template_layouts": [ { "..." : "..." } ],
      "input_deck_layouts": [ { "..." : "..." } ]
    }
  }
}

`POST /api/v1/template-conversions/{callback_id}/layout-updates`

Updates the layout of a slide and re-renders the affected portion of the deck. Returns a new callback_id to poll.

Request body

Field	Type	Required	Description
`slide_index`	integer ≥ 0	yes	Zero-based slide index.
`layout_id`	string	yes	Target layout id (from `/template-conversions/{callback_id}/layouts`).

Success response (`200`)

{ "success": true, "data": { "callback_id": "cb_tc_xyz_v4" } }

`POST /api/v1/template-conversions/{callback_id}/format-modifications`

Applies a batch of title/body formatting changes and re-renders the affected slides. Returns a new callback_id to poll.

Request body

Field	Type	Required	Description
`modify_format_config`	array of object	yes	Per-slide formatting modifications. Each item may contain `title` and `body` objects.

Success response (`200`)

{ "success": true, "data": { "callback_id": "cb_tc_xyz_v5" } }

`GET /api/v1/template-conversions/{callback_id}/format-modifications/settings`

Returns the available formatting controls (font sizes, weight, alignment) for title/body text in the converted deck.

Path parameters

Parameter	Type	Required	Description
`callback_id`	string	yes	Conversion job id.

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "modify_format_settings": [ { "..." : "..." } ]
  }
}

`GET /api/v1/template-conversions/{callback_id}/download` — Download

Returns a signed download URL for the converted deck. Counts against the TC_DOWNLOAD usage limit.

Success response (`200`)

{
  "success": true,
  "data": {
    "download_url": "https://...signed-url...",
    "file_name": "Q3 review (Corporate 2024).pptx",
    "message": "Ready to download."
  }
}

`POST /api/v1/template-conversions/{callback_id}/comply-metrics` — Comply metrics

Records compliance metrics for a converted deck. The body is forwarded to the ComplyMetrics service. Typically invoked via a callback_id + token URL handed back to the caller after a conversion.

Success response (`200`)

{ "success": true, "data": { "message": "Metrics recorded." } }

`PUT /api/v1/template-conversions/{callback_id}/reactions` — Like / feedback

Records a like or qualitative feedback against a converted deck. Uses PUT rather than POST — a legacy quirk preserved from the original endpoint.

Path parameters

Parameter	Type	Required	Description
`callback_id`	string	yes	Converted-deck callback id.

Request body

Field	Type	Required	Description
`type`	string	yes	`liked` or `feedback`.
`value`	boolean or string	yes	Boolean when `type=liked`; string when `type=feedback`.

Success response (`200`)

{
  "success": true,
  "data": {
    "callback_id": "cb_tc_xyz",
    "type": "liked",
    "message": "Reaction recorded.",
    "warnings": []
  }
}

Errors

All endpoints on this page return the standard error envelope. Common codes:

400 — MISSING_CALLBACK_ID, MISSING_TEMPLATE_ID, INVALID_INPUT, INVALID_PAYLOAD.
401 — INVALID_API_KEY, EXPIRED_API_KEY, UNAUTHORIZED.
404 — ENDPOINT_NOT_FOUND, RESOURCE_NOT_FOUND.
415 — UNSUPPORTED_FILE_TYPE (uploads / chunking only).
429 — RATE_LIMIT_EXCEEDED, USAGE_LIMIT_EXCEEDED.
500 / 502 / 503 / 504 — standard server-side codes.

See the full catalog in Developer Guide → Error codes.

Authentication​

Response envelope​

Endpoint summary​

POST /api/v1/template-conversions — Create a conversion​

Request body​

Example​

Success response (200)​

GET /api/v2/template-converter/status/{callback_id} — Poll a job (v2, strict mapping)​

Path parameters​

Query parameters​

Example​

Success response (200)​

In-progress response (202)​

Failure responses​

GET /api/v1/templates?feature=template_converter — List templates​

Query parameters​

Success response (200)​

Chunked upload — preprocessings + finalisations​

POST /api/v1/template-conversions/preprocessings​

POST /api/v1/template-conversions/finalisations​

Request body​

Success response (200)​

Smart-edit endpoints​

GET /api/v1/template-conversions/{callback_id}/review-suggestions​

Success response (200)​

PATCH /api/v1/template-conversions/{callback_id}/review-suggestions​

Request body​

Success response (200)​

POST /api/v1/template-conversions/{callback_id}/template-changes​

Request body​

Success response (200)​

GET /api/v1/template-conversions/{callback_id}/work-area-options​

Path parameters​

Query parameters​

Success response (200)​

POST /api/v1/template-conversions/{callback_id}/work-area-adjustments​

Request body​

Success response (200)​

GET /api/v1/template-conversions/{callback_id}/layouts​

Path parameters​

Query parameters​

Success response (200)​

POST /api/v1/template-conversions/{callback_id}/layout-updates​

Request body​

Success response (200)​

POST /api/v1/template-conversions/{callback_id}/format-modifications​

Request body​

Success response (200)​

GET /api/v1/template-conversions/{callback_id}/format-modifications/settings​

Path parameters​

Success response (200)​

GET /api/v1/template-conversions/{callback_id}/download — Download​

Success response (200)​

POST /api/v1/template-conversions/{callback_id}/comply-metrics — Comply metrics​

Success response (200)​

PUT /api/v1/template-conversions/{callback_id}/reactions — Like / feedback​

Path parameters​

Request body​

Success response (200)​

Errors​

Authentication

Response envelope

Endpoint summary

`POST /api/v1/template-conversions` — Create a conversion

Request body

Example

Success response (`200`)

`GET /api/v2/template-converter/status/{callback_id}` — Poll a job (v2, strict mapping)

Path parameters

Query parameters

Example

Success response (`200`)

In-progress response (`202`)

Failure responses

`GET /api/v1/templates?feature=template_converter` — List templates

Query parameters

Success response (`200`)

Chunked upload — `preprocessings` + `finalisations`

`POST /api/v1/template-conversions/preprocessings`

`POST /api/v1/template-conversions/finalisations`

Request body

Success response (`200`)

Smart-edit endpoints

`GET /api/v1/template-conversions/{callback_id}/review-suggestions`

Success response (`200`)

`PATCH /api/v1/template-conversions/{callback_id}/review-suggestions`

Request body

Success response (`200`)

`POST /api/v1/template-conversions/{callback_id}/template-changes`

Request body

Success response (`200`)

`GET /api/v1/template-conversions/{callback_id}/work-area-options`

Path parameters

Query parameters

Success response (`200`)

`POST /api/v1/template-conversions/{callback_id}/work-area-adjustments`

Request body

Success response (`200`)

`GET /api/v1/template-conversions/{callback_id}/layouts`

Path parameters

Query parameters

Success response (`200`)

`POST /api/v1/template-conversions/{callback_id}/layout-updates`

Request body

Success response (`200`)

`POST /api/v1/template-conversions/{callback_id}/format-modifications`

Request body

Success response (`200`)

`GET /api/v1/template-conversions/{callback_id}/format-modifications/settings`

Path parameters

Success response (`200`)

`GET /api/v1/template-conversions/{callback_id}/download` — Download

Success response (`200`)

`POST /api/v1/template-conversions/{callback_id}/comply-metrics` — Comply metrics

Success response (`200`)

`PUT /api/v1/template-conversions/{callback_id}/reactions` — Like / feedback

Path parameters

Request body

Success response (`200`)

Errors