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=loophttps://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?mode=animate-inhttps://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) 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 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.