> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Templates

> Programmatic MP4 video from templates — render, generate with AI, and manage over the same API token

# Video Templates API

Render MP4 video the same way you render images: build a **video template** once, then render it with different variables per request. Templates come in two kinds — **timeline** templates built in the visual studio, and **code** templates written as single-file Remotion (React) scenes — and both render through the same endpoint.

All endpoints live under `/video` and accept your normal API key as a Bearer token.

<Note>
  Video renders are long requests: expect up to a few minutes for a full render. The request waits and returns the finished MP4 URL. Each render consumes credits like any other generation.
</Note>

## List your video templates

```bash theme={null}
curl https://api.pictify.io/video/templates \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `{ "templates": [...] }` with each template's `uid`, `kind`, dimensions, fps, duration and variable definitions — everything you need to render it.

## Render a template — MP4 or GIF

```bash theme={null}
curl -X POST https://api.pictify.io/video/templates/TEMPLATE_UID/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variables": {
      "title": "Welcome, Maya!",
      "accentColor": "#ff5533"
    },
    "format": "mp4"
  }'
```

`format` is `"mp4"` (default) or `"gif"` — the same template and the same render, encoded for places an MP4 cannot autoplay. Timeline templates are palette-converted and capped at 15fps / 720px wide so files stay shareable; code (tsx) templates encode GIF natively at half the composition's frame rate with no width cap.

Response:

```json theme={null}
{
  "url": "https://media.pictify.io/videos/....mp4",
  "durationInFrames": 240,
  "format": "mp4"
}
```

For timeline templates, variable VALUES are validated against the declared definitions — a malformed value (bad colour, unsafe URL, missing required) returns `422` with `code: "invalid_variable"`, while unknown variable names are ignored by design. Code (tsx) templates receive variables directly as component props with no server-side validation — the scene's zod defaults govern what renders.

## Get a template's variables

```bash theme={null}
curl https://api.pictify.io/video/templates/TEMPLATE_UID/variables \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use this to build forms or map spreadsheet columns before rendering.

## Generate a template with AI

Describe the video; the API designs a motion brief, writes the scene code, compiles it, renders preview frames and reviews them visually — then returns a draft template ready to render or refine in the studio.

```bash theme={null}
curl -X POST https://api.pictify.io/video/templates/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "prompt": "An 8 second product launch teaser for a developer tool called ShipFast — dark, electric, type-driven",
    "width": 1080,
    "height": 1080,
    "durationSeconds": 8,
    "brandColor": "#00ff41"
  }'
```

Response: `{ "template": {...}, "previewUrl": "https://..." }` — the template's schema fields (texts, colours, optional image) are derived from the generated scene, so the result is immediately parameterisable.

Generation takes 30–60 seconds and is metered as one render.

## Preview a single frame

```bash theme={null}
curl -X POST https://api.pictify.io/video/templates/TEMPLATE_UID/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{ "variables": {}, "frame": 45 }'
```

Renders one frame to PNG — a cheap way to check a variable set before committing to a full video render. Metered as one image. Code (tsx) templates only: timeline templates return `501` with `code: "preview_not_supported"` (the studio previews them live in the browser instead).

## Template management

| Method   | Path                              | Purpose                                                  |
| -------- | --------------------------------- | -------------------------------------------------------- |
| `POST`   | `/video/templates`                | Create a template (timeline `projectJson` or code `tsx`) |
| `GET`    | `/video/templates/:uid`           | Fetch one template                                       |
| `PUT`    | `/video/templates/:uid`           | Update — code templates are recompiled and re-validated  |
| `DELETE` | `/video/templates/:uid`           | Delete                                                   |
| `POST`   | `/video/templates/:uid/duplicate` | Copy — the natural way to make a variant                 |

Code (`tsx`) templates pass a compile gate on every create and update: imports are restricted to `remotion` (including `@remotion/*` subpackages), `react` and `zod`, and a template that does not build is rejected with `422` and the compiler errors, so a template that saves is a template that renders.