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

# Motion modes

Three playback shapes (loop, animate-in, animate-on-hover) and three motion intensities (subtle, medium, kinetic).

# Motion modes

Two orthogonal knobs shape every Motioness asset:

- **Mode** — *how* the video plays back (loop, one-shot, hover-triggered).
- **Motion** — *how much* movement the model puts on screen (subtle, medium, kinetic).

## Mode (playback shape)

| Mode | Pipeline | Behavior | Use case |
|---|---|---|---|
| `loop` | Two-stage stitch | Generates forward motion + a return-to-start segment, merges them so the last frame meshes back into the first | Backgrounds, hero accents, ambient motion that must run forever |
| `animate-in` | Single i2v call | One-shot animation, plays once on entry | Reveal animations, build-ups, story beats |
| `animate-on-hover` | Single i2v call | Same as `animate-in` but client-paused until hover | Interactive cards, gallery items |

`loop` runs **two** image-to-video predictions and counts as one generation; `animate-in` and `animate-on-hover` run **one** prediction each.

### Setting mode

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?mode=loop
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?mode=animate-in
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?mode=animate-on-hover
```

Or set `default_mode` on the project so URLs don't need the param:

```bash
curl -X PUT https://motioness.com/api/projects/$PROJECT_ID/proxy-config \
  -H 'Content-Type: application/json' \
  -d '{"default_mode": "loop"}'
```

## Motion (intensity)

Three preset intensities map to internal prompt amplifiers:

| Motion | Effect | Best for |
|---|---|---|
| `subtle` | Gentle parallax, soft glints, ambient breathing | Editorial sites, dashboards, professional brands |
| `medium` | Default. Clear motion without being distracting | Marketing pages, product hero sections |
| `kinetic` | Strong camera motion, particles, bold transforms | Consumer brands, game pages, attention-getting CTAs |

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?motion=subtle
```

## Loop modes

When `mode=loop` and the source plays back as a continuous video, two loop strategies exist:

| Loop | Tier | What you get |
|---|---|---|
| `native` | Pro+ | Model natively generates a returning sequence — seamless, no visible seam |
| `crossfade` | Free | Output crossfaded into itself in post — cheaper, visible 200ms blend |

You don't pick the loop mode — it's derived from the project owner's tier. Free-tier loops always crossfade; Pro+ loops are native. The response carries `X-Motioness-Loop: native` or `X-Motioness-Loop: crossfade` so the player can adjust.

## Duration

`dur` (or `dur_seconds` in the API) controls output length, clamped to `[2, 8]` seconds:

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?dur=6
```

Project default `default_dur_seconds` (set via [PUT /api/projects/:id/proxy-config](/api/projects/proxy-config)) wins when the param is omitted.

Longer durations cost more compute and produce longer files. For looping backgrounds, `4-5s` is the sweet spot — short enough to feel snappy, long enough to hide the seam.

## Aspect

`aspect` controls the output framing:

| Value | Behavior |
|---|---|
| `preserve` (default) | Match source aspect |
| `1:1` | Square crop, center-anchored |
| `16:9` | Widescreen |
| `9:16` | Vertical (mobile / story) |

Aspect is **only** honored on the `seedance` model (Pro tier). `wan-fast` (Free) and `p-video` (Team) silently ignore aspect for now — see the [Known limitations](/changelog#known-limitations) section.

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?aspect=16:9
```

## Custom prompt override

If the brand-context prompt isn't doing what you want, override it:

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?prompt=cinematic+slow+pan+left
```

Capped at 500 characters. The override **replaces** the generated prompt — your brand context is no longer applied. Use this surgically.

## Seeds

Pass `?seed=42` (any integer) to make a generation deterministic. Same source + opts + seed → bit-identical output. Useful for A/B variants:

```text
?idem=variant-a&seed=42
?idem=variant-b&seed=43
```

The two URLs produce two distinct assets, both reproducible.

## Defaults vs request params

Project defaults are saved on `projects` and apply when the request omits a param:

```ts
// Project config
{ default_motion: 'subtle', default_dur_seconds: 4, default_mode: 'loop' }

// Request:  …/hero.png.mp4
// Effective: motion=subtle, dur=4, mode=loop  ← all from project defaults

// Request:  …/hero.png.mp4?motion=kinetic
// Effective: motion=kinetic, dur=4, mode=loop  ← request wins for motion
```

Set defaults once per project, override per-call when you need variety.