templates.create

Save a render template

POST/templates

Operation: templates.create
MCP tool: templates_create

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.

curl 'https://api.gogoscreen.com/api/v1/templates' \
  -X POST \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Idempotency-Key: templates-create-mubixu8b" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product tour, portrait",
  "description": "Phone view, 60 seconds, English."
}'

A request to this operation.

json

{
  "template": {
    "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000012",
    "name": "Product tour, portrait",
    "description": "Phone view, 60 seconds, English.",
    "isDefault": false,
    "custom": true,
    "limits": {
      "editor": {},
      "executor": {},
      "render": {}
    },
    "voiceId": null,
    "lengthPreset": null,
    "orientationId": null,
    "captureId": null,
    "language": null,
    "background": null,
    "ttsSpeed": null,
    "sourceRenderId": null,
    "updatedAt": "2026-09-21T11:16:00.000Z"
  }
}

201 response, captured from a real call. Ids, timestamps and signed URLs are replaced; the shape is untouched.

At a glance

Fact	Detail
Scopes	`renders:write`
Credentials	a signed in dashboard session or an API key.
Rate limit	120 requests a minute per credential, in the `write` class.
Idempotency	Required. Send an `Idempotency-Key` header; a retry with the same key and the same body returns the stored answer with `Idempotent-Replayed: true`. How idempotency works.
MCP tool	`templates_create`
Always sets	`Cache-Control: private, no-store`

Request body

A JSON body is required. Unknown fields are refused rather than ignored, so a typo is a 400 validation_failed rather than a setting that silently did nothing.

Name	Type	Required	Description
name	string	Required	1–80 characters
description	string	Optional	max 300 characters
settings	object	Optional	Omit for a template that pins nothing but its name.any keys
sourceRenderId	string	Optional	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.format: uuid

Response

Answers 201. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

201 Created

Save a render template

201 Created body

Name

Type

Description

template

object

17 fields inside template

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

201 Created headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.
`Idempotent-Replayed`	Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
description_invalid	400	A saved template's description is longer than allowed.	Keep it to 300 characters or fewer.
idempotency_key_required	400	A mutating operation arrived over HTTP with no `Idempotency-Key` header. It is refused before the body is parsed, so a caller missing both learns about both at once.	Add an `Idempotency-Key` header of up to 128 characters, unique to this request. Over MCP the same value goes in the `idempotencyKey` tool argument.
length_below_minimum	400	The length asked for is shorter than a walkthrough can be. The floor is 30 seconds.	Ask for at least 30 seconds, or omit `targetSeconds` for Auto, which sizes itself.
name_invalid	400	A saved template's name is empty or longer than 80 characters.	Send a name between 1 and 80 characters.
orientation_unknown	400	The `orientation` named is not in the catalogue.	Read `GET /catalog/render-options` and send an id from `orientations`.
settings_invalid	400	The settings object on a saved template is not valid.	Send only keys the template settings schema declares, with values the catalogue offers.
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
voice_unknown	400	The `voiceId` named is not in the catalogue.	Read `GET /catalog/voices` and send an id it lists.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
source_render_not_found	404	The `sourceRenderId` or `renderId` named is not a render of this account.	Send a render id this account owns. A render belonging to somebody else answers the same way.
template_not_found	404	No saved template of that id belongs to this account.	Check the id, or list the account's templates.
conflict	409	The request conflicts with the state the resource is in, and no more specific code applies.	Re-read the resource and decide from its current state. Retrying the same request unchanged will not help.
idempotency_conflict	409	That idempotency key has already been used on this operation with a different request body.	Use a fresh key for a different request. A key stands for one intent, not for one attempt.
idempotency_in_progress	409	The first request under that key is still being worked. Two concurrent identical requests both reach the store and one of them is told this.	Wait the `Retry-After` seconds, which is 2, and send exactly the same request again with the same key. Do not change the body and do not mint a new key.
template_limit	409	The account already holds the most saved render templates it may.	Delete one, then save the new one.
payload_too_large	413	The request body is over the transport's limit: 256 kb over HTTP, 1 mb over MCP.	Send less. `details.limit` carries the limit. Version 1 has no upload operations, so a body this size is usually a mistake.
unsupported_media_type	415	The request carried a body whose `Content-Type` is not `application/json`, whose charset is not utf-8, or whose `Content-Encoding` this API does not decode. A body nobody can read would otherwise be silently discarded.	Send `Content-Type: application/json` and utf-8 bytes. `details` names the charset, encoding or content type that was objected to.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.
service_unavailable	503	A service this API depends on could not be reached. `details.reason` is a short category, never an internal error message.	Back off and retry. `Retry-After` and `details.retryAfterSeconds` say how long to wait.