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

# Proxy URL

The single URL shape that powers every Motioness embed.

# Proxy URL

Every Motioness embed is built from one URL pattern. Once you understand it, you can hand-write proxy URLs without an SDK.

## The pattern

```text
https://motioness.com/v1/{projectKey}/{srcWithoutScheme}.{format}[?params]
```

| Segment | Description |
|---|---|
| `{projectKey}` | Public proxy key, prefixed `pk_…`. One per project. Find it in Project → Settings → Proxy. |
| `{srcWithoutScheme}` | Source URL with `https://` stripped — e.g. `cdn.acme.com/hero.png`. |
| `{format}` | `.mp4` returns the animated loop. `.jpg` returns the poster (always immediate). |
| `?params` | Optional motion / mode / duration / prompt / seed / idem / aspect / wait_ms / sig+exp. |

## Examples

```text mp4
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4
```

```text jpg poster
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.jpg
```

```text with motion params
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?motion=kinetic&dur=6&mode=loop
```

```text with idem + long-poll
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?idem=variant-a&wait_ms=8000
```

```text signed
https://motioness.com/v1/pk_abc/aHR0cHM6Ly9jZG4uYWNtZS5jb20vaGVyby5wbmc.mp4?sig=abc&exp=1714808400
```

## Two auth modes

A project can use **either** allowlist auth **or** signed auth — pick one per project.

### Allowlist (default)

Source URL is plain text. The worker resolves the origin and rejects requests where the origin doesn't match `allowed_origins`. Best for first-party use where the source images live on a domain you control.

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4
```

### Signed

Source URL is base64url-encoded. Path includes `?sig=…&exp=…`. The worker verifies the HMAC against the project's signing secret. Best for server-to-server use, sharing across domains, or short-lived URLs.

```text
https://motioness.com/v1/pk_abc/{base64url(srcUrl)}.mp4?sig={hmacSha256}&exp={unixSeconds}
```

See [allowlist vs signed](/concepts/allowlist-vs-signed) for the trade-off, and [signed URLs](/guides/signed-urls) for the signing recipe.

## Format selection

| Path suffix | Returns | Generation cost |
|---|---|---|
| `.jpg` | Poster image (the source, optionally re-encoded) | Free, ~5ms cached |
| `.mp4` | Animated loop / hover video | Counts against monthly quota, 20–60s first hit |

A common pattern is to load the poster eagerly and the mp4 lazily:

```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 preload="metadata"
/>
```

## Cache key

The proxy cache key is content-addressed:

```ts
cache_key = canonicalize(url, stripParams: ['wait_ms', 'sig', 'exp'])
asset_id  = sha256(src_url || motion || mode || dur_seconds || prompt || seed || idem || aspect)[0:16]
```

So:

- Two browsers requesting `https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4` always hit the same cache entry.
- Adding `?wait_ms=5000` doesn't busted the cache.
- Adding `?motion=kinetic` does — it's a content param and changes `asset_id`.
- Adding `?idem=variant-a` does — it forces a distinct asset from the same source.

## Anatomy diagram

```text
https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?motion=medium&dur=4
└─────┬─────┘ └┬┘ └─┬──┘ └──────────┬─────────┘ └┬┘ └─────────┬──────────┘
      │        │    │              │            │              │
      │        │    │              │            │              └─ Optional params
      │        │    │              │            │                 (cache-busting where content-affecting)
      │        │    │              │            └─ Format: mp4 (animated) or jpg (poster)
      │        │    │              └─ Source URL (https:// stripped, OR base64url if signed)
      │        │    └─ Project key (public, scopes to your project)
      │        └─ API version (currently always v1)
      └─ Origin
```

## Programmatic construction

The SDK does this for you:

```ts
import { buildProxyUrl } from '@motioness/proxy-client';

const urls = buildProxyUrl({
  origin: 'https://motioness.com',
  projectKey: 'pk_abc',
  src: 'https://cdn.acme.com/hero.png',
  motion: 'medium',
  durSeconds: 4,
});

urls.mp4 // → https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.mp4?motion=medium&dur=4
urls.jpg // → https://motioness.com/v1/pk_abc/cdn.acme.com/hero.png.jpg
```

For full options including signing, see the [SDK reference](/sdks/proxy-client).