> ## 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.

# Query parameters

Every query parameter the public proxy URL accepts.

# Query parameters

All parameters are optional. Project defaults apply when omitted.

## Content-affecting (changes asset_id)

| Parameter | Type | Default | Effect |
|---|---|---|---|
| `motion` | `subtle` / `medium` / `kinetic` | project default | Motion intensity |
| `mode` | `loop` / `animate-in` / `animate-on-hover` | project default | Playback shape (also picks pipeline) |
| `dur` | int 2..8 | project default | Output length in seconds |
| `prompt` | string ≤500 | — | Replaces brand-aware vision prompt |
| `seed` | int | — | Deterministic random seed |
| `aspect` | `1:1` / `16:9` / `9:16` / `preserve` | `preserve` | Output framing (seedance only) |
| `idem` | string | — | Forces a distinct asset from same source |

Each unique combination produces a unique `asset_id`. Same combination produces the same `asset_id` and serves from cache.

## Non-content (stripped from cache key)

| Parameter | Type | Default | Effect |
|---|---|---|---|
| `wait_ms` | int 0..10000 | 0 | Long-poll up to N ms before returning 202 |
| `sig` | hex string | — | HMAC signature (signed mode) |
| `exp` | unix seconds | — | Expiry (signed mode) |

Adding/removing these doesn't bust the cache.

## `idem` recipes

```text
# Two distinct generations from the same source
…/hero.png.mp4?idem=variant-a
…/hero.png.mp4?idem=variant-b

# Time-windowed rotation
…/hero.png.mp4?idem=2026-q2

# Per-user variants (rare; usually overkill)
…/hero.png.mp4?idem=user-${userId}
```

`idem` is mixed into `asset_id` after motion/mode/dur/prompt/seed. Two URLs with the same content params but different `idem` are different assets.

## `wait_ms` recipes

```bash
# Block up to 8s waiting for the mp4
curl "https://motioness.com/v1/$KEY/cdn.acme.com/hero.png.mp4?wait_ms=8000" -o hero.mp4
```

If the asset finalizes within the deadline you get 200 + mp4. Otherwise 202 + Retry-After. Useful in CI/build scripts where you'd rather block than poll.

## Header equivalents

Two headers can substitute for query params:

| Header | Equivalent param |
|---|---|
| `Idempotency-Key: variant-a` | `?idem=variant-a` |
| `X-Request-Id: req_my-correlation` | (sets the response `X-Request-Id`) |