Templates & inputs

A template is a frozen composition plus a manifest of what may vary. It is the only thing the API renders.

Authoring

/^[a-z][a-zA-Z0-9]{0,63}$/

Input kinds

image and media default to required because a template rendered with a missing picture is not a template rendered wrong — it is a blank frame. A field can override this explicitly with required.

URL rules for image and media

Asset URLs are fetched server-side, so they go through an SSRF gate. Rejected:

• Anything that is not http: or https:
• localhost, 127.0.0.1, private IPv4 ranges, link-local addresses
• .localhost, .local and .internal hostnames
• Raw IPv6 literals
• Cloud metadata hosts

The check is applied to the URL and to what DNS answers, and again across redirects — a hostname that resolves to a private address is refused even though it looks public.

Assets are downloaded into temporary storage before the render, counted against your asset-processing quota, and capped at the smaller of your plan’s maxUploadBytes and 80 MB.

Every media layer needs a durable URL

This is the trap that catches a first template, and it is worth understanding before you publish one.

A media layer stores two things: an assetId naming the library entry, and a src. For footage you imported from your own disk, that src is a blob: URL — it belongs to the editor session that created it and means nothing anywhere else. User library imports are deliberately never uploaded to the cloud: they can be gigabytes of raw footage, so they live in local storage and are re-bound to a fresh object URL every time you open the project.

Publishing captures the document exactly as it stands, blob: srcs included.

{
  "code": "unrenderable_assets",
  "layers": [
    {
      "layer": "Hero Image",
      "reason": "its footage was imported from local storage and was never uploaded, so only this machine can resolve it"
    }
  ]
}

So every media layer in a template must be one of:

If a layer is meant to stay the same on every render, it still needs a real URL — “fixed” is not the same as “local”.

Checking before you rely on it

Render the template once with real inputs and watch the output. A missing background or a blank picture box is the symptom; the fix is to re-host that asset and republish.

Automating a project you already have

POST /v1/templates/import takes a .motion project and gives you back a template your workflow can drive — no editor, no field authoring.

curl -X POST $BASE/v1/templates/import   -H "Authorization: Bearer $PREMATION_API_KEY"   -F "file=@MyProject.motion.zip"   -F "name=Weekly promo"

{
  "id": "tpl_7f8a9b",
  "name": "Weekly promo",
  "width": 1080, "height": 1920, "fps": 30, "durationSeconds": 6,
  "inputs": [
    { "id": "backgroundVideo", "label": "Background Video", "kind": "media",
      "required": false, "default": "https://cdn.example.com/bg.mp4" },
    { "id": "heroImage", "label": "Hero Image", "kind": "image", "required": true }
  ],
  "requiredInputs": ["heroImage"],
  "warnings": [
    "\"Hero Image\" has no usable source in the project, so it is a required input — every render must supply a URL for it."
  ]
}

That is the whole setup. From here it is POST /v1/renders with { templateId, inputs: { heroImage: "https://…" } }.

Zip the bundle

A .motion project is a directory, and HTTP moves files — so send it as a zip. Compressing the folder the normal way is correct: the importer tolerates the whole bundle sitting under one top-level folder, which is what every “compress this folder” command produces.

zip -r MyProject.motion.zip MyProject.motion/

Legacy single-file .motion projects are accepted as-is, unzipped.

Inputs are derived from layer names

Every layer that shows a source becomes an input, and its id is a slug of the layer name — Hero Image becomes heroImage. Never the internal node id: addressing a layer by id would make Premation’s node graph a public contract that no project could ever be refactored out of.

So name your layers before you import. Rename a layer and re-import and the input id changes with it, which is correct — the name is the thing you control.

requiredInputs in the response is the list to send on every render. A missing one is a 400 before the job is queued, not a blank frame afterwards.

Scope: templates:write — not granted by default, so ask for it when you mint the key.

Publishing from the editor is still the richer path

The editor lets you choose exactly which layers are exposed, rename inputs, group them and set slot fit policies. Import gives you every media layer under its own name and nothing else. Both produce the same kind of template, and POST /v1/renders cannot tell them apart.

The public manifest

GET /v1/templates/{id} returns the manifest your automation reads:

{
  "id": "tpl_7f8a9b",
  "name": "Anime cooking reaction",
  "description": "Vertical reaction clip with a swappable character",
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "durationSeconds": 6.5,
  "inputs": [
    { "id": "character", "label": "Character", "kind": "media", "required": true },
    { "id": "headline", "label": "Headline", "kind": "text" },
    { "id": "accentColor", "label": "Accent", "kind": "color" }
  ],
  "createdAt": "2026-08-20T11:04:00.000Z",
  "updatedAt": "2026-08-20T11:04:00.000Z"
}

Publishing over HTTP

POST /v1/templates is session-authenticated by default; an API key needs the non-default templates:write scope.

{
  "name": "Anime cooking reaction",
  "description": "Optional, 500 characters max",
  "document": { "…": "EditorDocument snapshot" },
  "inputs": [
    { "id": "character", "label": "Character", "kind": "media", "required": true }
  ],
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "durationSeconds": 6.5,
  "projectId": "optional cloud project id"
}

In practice you do not hand-build document. Publish from the editor, which captures the whole project — scene, animation, nested comps, timelines, motion blur, guides and colour management — as one consistent snapshot.

Listing and deleting

GET    /v1/templates?limit=50&offset=0
GET    /v1/templates/{id}
DELETE /v1/templates/{id}

Listing is paginated: limit defaults to 50 and is capped at 100. Every response carries { items, total, limit, offset }. Templates are scoped to the account that published them — another account’s id answers 404, not 403.

What is preserved across a render

Everything you did not expose. Replacing a media field’s URL writes exactly one property — that layer’s src. Position, Scale, Rotation, Opacity, easing curves, effects and parenting are untouched, because they live on different props and the input application only ever writes the one target it resolved.

Animation templates are a different thing

/v1/animations is the cloud-synced animation preset library — reusable keyframe presets that sync between your installs. It shares the /v1 prefix and the templates:* scopes, but it is not what /v1/renders renders. If you are automating video, you want /v1/templates.