Quickstart

Sign up, create a project, ship your first animated mp4 — all in under five minutes.

Quickstart

By the end of this guide you'll have a proxy URL that returns a brand-aware looping mp4 for any image on your site.

1

Create an account

Sign up at motioness.com. Email + password or Google/GitHub OAuth. Free tier ships 5 generations per month — enough to validate the integration.

2

Create a project

The dashboard creates a default project for you on first sign-in. To create more, hit the project switcher in the top nav.

A project owns:

  • A proxy key (pk_…) used in URLs.
  • A brand context (colors, fonts, tone) injected into the vision prompt.
  • Allowed origins — domains that may load your proxy URLs (CSP-style allowlist).
  • Webhooks for asset.* events.
3

Set allowed origins

Open your project, paste your site domain into Allowed origins (e.g. https://acme.com). Without this, every proxy request returns 403.

For server-to-server use, switch to signed URLs instead — see allowlist vs signed.

4

Build your first proxy URL

Take any image URL on your site and rewrite it like this:

text
Original:  https://cdn.acme.com/hero.pngProxy mp4: https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4Proxy jpg: https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.jpg

The shape is https://motioness.com/v1/{projectKey}/{srcWithoutScheme}.{format}. The .jpg returns a poster (always immediate). The .mp4 returns the animated loop (generated on first hit, cached forever after).

5

Most apps should reach for the React component first — it ships with hover effects, lazy loading, signed-URL props, and SSR-safe progressive enhancement:

bash
npm install @motioness/proxy-client
tsx
import { MotionessImg } from '@motioness/proxy-client/react';<MotionessImg  projectKey="pk_abc"  src="https://cdn.acme.com/hero.png"  motion="medium"  durSeconds={4}/>

See the React SDK reference for all props (callbacks, lazy, signing, etc.).

6

Or use plain HTML (no SDK)

Lowest-level fallback for OG cards, RSS feeds, MDX, or any non-React surface:

html
<video  src="https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4"  poster="https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.jpg"  autoplay muted loop playsinline/>

First load returns 202 Accepted with a Retry-After header while generation runs. Subsequent loads stream the mp4 from the edge cache.

To skip the 202 dance, add ?wait_ms=8000 and the server long-polls up to 8 seconds before falling back.

No hover effects, no lazy loading — you wire those yourself. For HTML pages that want polish without React, use the web component instead.

What just happened

When the browser hit …/hero.png.mp4 for the first time:

  1. Edge worker resolved the project key, validated the source URL against the allowlist.
  2. Vision model (Claude) inspected the source image and generated a motion prompt informed by your brand context.
  3. Image-to-video model (seedance / wan-fast / p-video, picked by your tier) rendered the mp4.
  4. Loop stitching ran (when needed) so the last frame meshes back into the first.
  5. mp4 was written to R2, indexed in KV, and dispatched as asset.completed to your webhook (if configured).
  6. Subsequent calls skip everything and serve from the edge cache.

For a deeper view, read how it works.

Next steps

Configure webhooks

Get a POST to your endpoint when assets finalize.

Learn More
Sign URLs

Generate proxy URLs server-side and ship them anywhere.

Learn More
Tune motion

Subtle / medium / kinetic and the three playback modes.

Learn More
Regenerate

Iterate on the same asset_id — the URL stays stable.

Learn More
Previous Introduction
Next How it works
Ask a question... ⌘I