--- title: "Create a template-conversion job" method: POST path: "/api/v1/template-converter/start" tags: ["Template Converter"] --- # Create a template-conversion job `POST /api/v1/template-converter/start` Kicks off a pipeline that applies the target brand template (`templateName`) to the input PowerPoint (`fileId` or `inputDeck`). Returns a `callback_id` to poll. Counted against the `TC_START` usage limit. Subsequent calls in the same conversion lifecycle: poll `GET /api/v1/template-converter/status/{callbackId}` until the pipeline reaches a terminal state. ## Headers - `Idempotency-Key` string ## Request body - TemplateConverterStartRequest — Request body for `POST /api/v1/template-converter/start`. Supply the input deck **either** as `fileId` (a previously uploaded file, whose details are resolved server-side) **or** as an inline `inputDeck` object. `fileId` takes precedence when both are sent. Every optional setting below falls back to the defaults configured for the API key, and then to the documented default. - `fileId` string — Identifier of a previously uploaded input deck. Supply either `fileId` or `inputDeck`. - `inputDeck` object — Inline reference to the input deck. All four properties below are required when `inputDeck` is used. - `numOfPages` integer, required — Number of slides in the input deck. Also used for the projected usage-limit check. - `s3Bucket` string, required — S3 bucket holding the input deck. - `s3Prefix` string, required — S3 key (prefix) of the input deck. - `sizeKb` number, required — Size of the input deck in kilobytes. - `presentationName` string — Display name for the converted deck. - `templateName` string, required — Code of the target brand template. Must be one the caller's company is authorised to use — an unknown or unauthorised code is rejected. - `includeImageWithoutData` boolean — Carry over images that have no associated data. - `includeImageWithData` boolean — Carry over images that have associated data. - `includeIcons` boolean — Carry over icons. - `includeSpecialColor` boolean — Preserve special color treatments from the source deck. - `color_preference` 'standard' | 'advanced' — Color treatment preference. Also accepted as `colorPreference`. - `content_formatting_preference` 'standard' | 'advanced' — Content-formatting preference. Also accepted as `contentFormattingPreference`. - `modifyFormat` 'source' | 'target' — Which deck's formatting to apply. Also accepted as `modify_format`. - `settings` object — Per-conversion settings. Each key overrides the corresponding API-key default. - `ai_mode` 'standard' | 'thinking' — Conversion AI mode. - `work_area_option` 'no-adjust' | 'auto-adjust' | 'scale-to-fit' | 'auto-adjust-la' — Work-area adjustment behaviour. - `modifyFormat` 'source' | 'target' — Which deck's formatting to apply. Also accepted as `settings.modify_format`. - `color_preference` 'standard' | 'advanced' — Color treatment preference. ## Response `200` Job accepted; client must poll for completion. - TemplateConverterStartResponse — Response body for `POST /api/v1/template-converter/start`. This endpoint does **not** use the canonical `success`/`data` envelope — the fields below are returned at the **top level**, in camelCase. - `callbackId` string, required — Conversion job id to poll. Note the camelCase spelling. - `status` 'processing' | 'failed', required — `processing` once the pipeline has been accepted; `failed` if it could not be started. - `presentationName` string — Resolved presentation name. May be an empty string. - `token` string — Token for callback-id-scoped URLs. ## 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)