---
title: "Save a render template"
method: POST
path: "/templates"
tags: ["templates"]
---

# Save a render template

`POST /templates`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/templates`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Save a set of render settings — the look, the voice, the length, the shape — under a name, so every render after this one can ask for it by id. Nothing here is a lock: a template is a set of DEFAULTS and any render may override any of them. At most 50 per account; the 51st is 409 `template_limit`.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `description` string
  - `name` string, required
  - `settings` object: Omit for a template that pins nothing but its name.
  - `sourceRenderId` string, uuid: A finished render of this account's that these settings were taken from, for your own records. A render id that is not this account's is a 404.

## Response `201`

Save a render template

- object
  - `template` object, required
    - `background` string, nullable, required
    - `captureId` string, nullable, required
    - `custom` boolean, required: true for one of this account's saved templates, false for a system template.
    - `description` string, required
    - `id` string, required
    - `isDefault` boolean, required
    - `language` string, nullable, required
    - `lengthPreset` string, nullable, required
    - `limits` object, nullable, required: The engine limits this template pins. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.
    - `name` string, required
    - `orientationId` string, nullable, required
    - `sourceRenderId` string, nullable
    - `speedFactor` number, nullable: System templates only: a factor on the voice's own speed.
    - `ttsSpeed` number, nullable, required
    - `updatedAt` string, date-time, nullable
    - `voiceId` string, nullable, required
    - `voiceStyle` string, nullable: System templates only: the delivery the narrator reads in.

## Other responses

- `400`: `validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `name_invalid` — That template name is not valid. · `description_invalid` — That template description is too long. · `settings_invalid` — Those template settings are not valid. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be.
- `401`: `unauthorized` — Authentication is required.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs.
- `404`: `not_found` — No such resource. · `template_not_found` — No such template. · `source_render_not_found` — No such render on this account.
- `409`: `idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `template_limit` — This account already holds the most templates it may. Delete one to save another.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `429`: `rate_limited` — Too many requests. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.
- `503`: `service_unavailable` — That service is temporarily unavailable.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)