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

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

**Create an account**

Sign up at [motioness.com](https://motioness.com/sign-up). Email + password or Google/GitHub OAuth. Free tier ships 5 generations per month — enough to validate the integration.

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

  **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](/concepts/allowlist-vs-signed).

  **Build your first proxy URL**

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

    ```text
    Original:  https://cdn.acme.com/hero.png
    Proxy mp4: https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4
    Proxy 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).

  **Drop it in (React, recommended)**

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](/sdks/react) for all props (callbacks, lazy, signing, etc.).

  **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](/sdks/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](/how-it-works).

## Next steps

**[Configure webhooks](/guides/webhooks)**

Get a `POST` to your endpoint when assets finalize.
  **[Sign URLs](/guides/signed-urls)**

Generate proxy URLs server-side and ship them anywhere.
  **[Tune motion](/concepts/motion-modes)**

Subtle / medium / kinetic and the three playback modes.
  **[Regenerate](/guides/regenerate)**

Iterate on the same `asset_id` — the URL stays stable.