Create or update template

POST https://api.json2video.com/v2/templates

Creates a new template or updates an existing one. Templates store a reusable Movie JSON document with variable placeholders. A separate sub-action duplicates an existing template into the caller's account.

Request

Headers

Header	Required	Value
`x-api-key`	yes	API key issued from the dashboard. Requires role `editor`, `manager`, or `admin`.
`Content-Type`	yes	`application/json`

Query parameters

Parameter	Type	Description
`id`	string	Template ID. Present → update. Absent → create with a generated 20-character ID.
`action`	string	When set to `duplicate`, copies the referenced template into the caller's account. Requires `id`.

Body — create / update

{
    "name": "Product showcase",
    "tags": ["showcase", "demo"],
    "movie": { "resolution": "full-hd", "scenes": [] },
    "prompt": ""
}

Field	Type	Description
`name`	string	Required on create. Maximum 100 characters.
`tags`	string\|array	Either a comma-separated string or an array of strings. Tags are trimmed; no length limit per tag.
`movie`	object\|string	Movie JSON. Either a parsed object or a stringified JSON. Up to ~100 KB. If `movie.template` is set, the referenced template's body is loaded and the supplied `variables` are deep-merged on top.
`prompt`	string	Optional AI prompt associated with the template.

Body — duplicate

{
    "name": "My copy of Product showcase",
    "variables": { "headline": "Hello" }
}

name defaults to the original name with " (custom)" appended. variables are deep-merged into the source template's variables.

Response

200 OK — create / update

{
    "success": true,
    "templateId": "abc123def456ghi789jk",
    "timestamp": "2026-05-12T10:49:52.924Z"
}

200 OK — duplicate

{
    "success": true,
    "templateId": "xyz987uvw654rst321qp",
    "name": "Product showcase (custom)",
    "timestamp": "2026-05-12T10:49:52.924Z"
}

Errors

Status	Message	Cause
`400`	`No payload provided`	Empty body.
`400`	`Tags must be a string or an array`	`tags` is the wrong type.
`400`	`Payload movie must be a JSON string or JSON object`	`movie` is the wrong type.
`400`	`No template ID provided`	`action=duplicate` without `id`.
`403`	`Insufficient permissions`	API key role is below `editor`.
`403`	`Template {id} is not owned by you`	Update attempt against another account's template.
`404`	`Template {id} not found`	Unknown source template (update or duplicate).
`500`	`Template movie is not valid JSON or it's too large`	Stringified `movie` failed to parse.
`500`	`Source template movie is not valid JSON`	Duplicate source has a corrupted body.
`500`	`Error saving template`	Server error. Retry with exponential backoff.

Examples

Create

curl --location --request POST 'https://api.json2video.com/v2/templates' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Product showcase",
    "tags": ["demo"],
    "movie": {
      "resolution": "full-hd",
      "variables": { "headline": "Sample" },
      "scenes": [
        { "elements": [{ "type": "text", "text": "{{headline}}" }] }
      ]
    }
  }'

Update

curl --location --request POST \
  'https://api.json2video.com/v2/templates?id=abc123def456ghi789jk' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{"name": "Product showcase v2"}'

Duplicate

curl --location --request POST \
  'https://api.json2video.com/v2/templates?id=abc123def456ghi789jk&action=duplicate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{"variables": {"headline": "Hello"}}'

Create or update template#

Request#

Headers#

Query parameters#

Body — create / update#

Body — duplicate#

Response#

200 OK — create / update#

200 OK — duplicate#

Errors#

Examples#

Create#

Update#

Duplicate#