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

# Engines, effort, and templates

Send a prompt through REST or MCP to create a video. New video jobs default to GVA with `standard` effort. Read engine discovery for your account's available engines, supported efforts and default.

```json theme={null}
{"prompt":"Create a 20-second product launch video"}
```

## Engine and effort

| Engine | Name | Efforts | Default effort |
| - | - | - | - |
| `gva` | GVA 1.0 | `standard`, `extended` | `standard` |
| `motion` (Legacy access required) | Motion | `light`, `medium`, `high` | `medium` |

Motion supports Light, Medium and High effort. Medium is the default. Effort affects runtime and credit use; the task and generated media also affect the final cost.

To choose Motion and High effort explicitly:

```json theme={null}
{"prompt":"Create a product animation", "engine":"motion", "effort":"high"}
```

In an MCP client, ask your agent: "Use Motion with high effort." It can send the same fields to `create_video`.

## Discover available engines

```bash theme={null}
curl https://api.motion.so/api/motion/engines \
  -H "Authorization: Bearer motion_YOUR_API_KEY"
```

MCP clients call `list_engines`. Each result reports `engine`, `name`, `efforts`, `default_effort`, `default`, and whether `templates` are supported. Read this catalog rather than hardcoding every engine; future engines can use the same request surface.

Engine discovery includes only engines your account can use. GVA is available to signed-in accounts. Motion Legacy is available only to eligible existing accounts and administrators. API keys, OAuth scopes, and credits do not change that eligibility. An explicit unavailable engine returns HTTP 403 with `engine_access_required`.

GVA is the default for new jobs without an explicit engine, including requests using the deprecated REST `mode` field. Your existing API key or MCP connection continues to work. Clients that cache engine choices should refresh discovery. Existing projects keep their engine.

Access is checked on creation and every follow-up, including credit-pause resumes. Owners can still read existing outputs.

## GVA

Standard and Extended are effort levels of the same `gva` engine. Use Standard for everyday work or Extended for more demanding tasks:

| Choice | API / MCP fields |
| - | - |
| GVA Standard | `engine: "gva", effort: "standard"` |
| GVA Extended | `engine: "gva", effort: "extended"` |

For Standard:

```json theme={null}
{"prompt":"Create a product animation", "engine":"gva", "effort":"standard"}
```

For Extended:

```json theme={null}
{"prompt":"Edit this into a 30-second story", "engine":"gva", "effort":"extended"}
```

In ChatGPT or another MCP client, ask "Use GVA Standard" or "Use GVA Extended." The agent sends the matching `engine` and `effort` fields. You can also omit `engine` and send `effort: "extended"` when creating a new GVA job.

Motion Legacy eligibility is separate from GVA access. Read engine discovery before choosing Motion explicitly.

## Engine-specific templates

List templates for your selected engine:

```bash theme={null}
curl 'https://api.motion.so/api/motion/templates?engine=motion' \
  -H "Authorization: Bearer motion_YOUR_API_KEY"
```

Or call MCP `list_templates({"engine":"motion"})`. Without an engine, discovery uses your account's default. Only published templates available to your account appear; an empty list means none are currently available.

Use a returned identifier as `template` when creating a job. Templates seed the editable project before the first turn and require Pro or Max. Choose a template from the same engine's catalog. Personal Brand templates require GVA Standard; select `effort: "standard"` when using one.

## Revise and resume

Follow-ups keep the project's engine, effort, and template. Omit `effort` to keep the current choice, or set it for the next turn. A GVA job can switch between `standard` and `extended`; an existing Motion job stays on Motion and uses `light`, `medium`, or `high`:

```json theme={null}
{"prompt":"Shorten the opening"}
```

Send the request to `POST /sessions/{job_id}/followups`, or use MCP `create_followup` with the same `job_id`. The job must be completed or waiting on user input. After topping up a credit-paused job, continue that same job.

Create a new job to change engines or templates. Responses include the effective `engine`, `effort`, and `template`; new engine-backed jobs require a downloadable export before reporting `completed`. Older session jobs can report `completed` while an export is pending. For every job, check `output.status === "completed"` and a non-null `output.download_url` before downloading.

## Existing integrations

Endpoint URLs, API-key prefixes, OAuth scopes, tool names, and job IDs remain valid. Existing projects retain their engine. New requests that omit `engine` use GVA. Existing Motion chats, including pre-launch chats without engine metadata, continue using Motion on follow-up.

The following deprecated inputs are supported by REST. MCP clients must use the published `engine` and `effort` fields: `engine: "motion"` selects Motion. MCP schemas do not expose `mode`. Earlier GVA effort values remain accepted by MCP as effort aliases.

| Existing REST input | Behavior |
| - | - |
| `mode` alone on a new job | Uses GVA: `light`/`medium` → `standard`; `high` → `extended` |
| `mode` on an existing Motion job | Keeps Motion and applies its `light`, `medium`, or `high` effort |
| GVA with `light` or `medium` | Normalizes to `standard` |
| GVA with `high` | Normalizes to `extended` |
| Both `effort` and `mode` | Must normalize to the same effort |

New integrations should use `engine` and `effort`. Read the effective selection from the response rather than assuming all saved projects use GVA.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.