Partner API

GET /v1/videos

List active videos. Cursor pagination + basic filters.

curl "https://awfrtgkoramnvpsvrjjv.supabase.co/functions/v1/partner-api/v1/videos?limit=20&genre=hip-hop" \
  -H "Authorization: Bearer $MVM_API_KEY"

limit (max 100), cursor, genre, mood, q, min_duration, max_duration.

GET /v1/videos/:id

curl "https://awfrtgkoramnvpsvrjjv.supabase.co/functions/v1/partner-api/v1/videos/<uuid>" \
  -H "Authorization: Bearer $MVM_API_KEY"

Response includes preview.available_kinds — render only buttons for kinds listed there.

GET /v1/collections · /v1/collections/:id

Curated bundles of videos.

GET /v1/categories · /v1/tags

Taxonomy for filtering.

POST /v1/media/preview-url

Mint a short-lived proxied stream_url. Tokens expire in 15 minutes; re-mint per playback.

curl -X POST "https://awfrtgkoramnvpsvrjjv.supabase.co/functions/v1/partner-api/v1/media/preview-url" \
  -H "Authorization: Bearer $MVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "video_id": "<uuid>", "kind": "full" }'

kind: full | reel | bts (legacy variant also accepted). Response: { data: { stream_url, expires_in: 900 } }.

GET | HEAD /v1/media/stream/:token

Opaque proxied MP4. Supports Range (returns 206 Partial Content) and HEAD for metadata preflight. Carries X-Stream-Proxy: mvm/1. Your <video> calls this — you do not.

# verify range support
curl -I -H "Range: bytes=0-1023" "<stream_url>"
# → HTTP/2 206
# → content-type: video/mp4
# → content-range: bytes 0-1023/...

Required player capabilities

• Native HTML5 <video> tag
• MP4 container, H.264 video, AAC audio
• HTTP Range requests (for seeking)
• playsInline on iOS
• crossorigin="anonymous" only if you need <canvas> frames

Forbidden

• Vimeo Player SDK / @vimeo/player / player.vimeo.com iframes
• YouTube IFrame API or any YouTube embed
• hls.js, dash.js, Shaka, Video.js, JW Player, Plyr, Bitmovin
• Caching, sharing, or persisting stream_url across users, sessions, sitemaps, or CDNs
• Sniffing the response to discover the upstream CDN and hitting it directly

Vanilla HTML — full video (with controls)

<video
  src="<stream_url with kind:'full'>"
  controls
  playsinline
  preload="metadata"
  style="width: 100%; aspect-ratio: 16 / 9; background: #000;"
></video>

Vanilla HTML — reel (vertical, autoplay loop)

<video
  src="<stream_url with kind:'reel'>"
  autoplay
  muted
  loop
  playsinline
  preload="metadata"
  style="height: 100%; aspect-ratio: 9 / 16; background: #000;"
></video>

Vanilla HTML — behind-the-scenes

<video
  src="<stream_url with kind:'bts'>"
  controls
  playsinline
  preload="metadata"
  style="width: 100%; aspect-ratio: 16 / 9; background: #000;"
></video>

Vanilla HTML — hover preview on a grid card

<div class="card" data-video-id="<uuid>" style="position:relative;aspect-ratio:16/9">
  <img class="poster" src="<thumbnails.poster>" alt=""
       style="width:100%;height:100%;object-fit:cover" />
  <video class="hover-video" muted loop playsinline preload="none"
         style="position:absolute;inset:0;width:100%;height:100%;
                object-fit:cover;opacity:0;transition:opacity .2s"></video>
</div>
<script>
const DEBOUNCE_MS = 150;
document.querySelectorAll('.card').forEach((card) => {
  const video = card.querySelector('.hover-video');
  const id = card.dataset.videoId;
  let timer = null;

  card.addEventListener('mouseenter', () => {
    timer = setTimeout(async () => {
      const r = await fetch('https://awfrtgkoramnvpsvrjjv.supabase.co/functions/v1/partner-api/v1/media/preview-url', {
        method: 'POST',
        headers: {
          Authorization: 'Bearer ' + window.MVM_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ video_id: id, kind: 'full' }),
      });
      const { data } = await r.json();
      video.src = data.stream_url;
      video.style.opacity = '1';
      video.play().catch(() => {});
    }, DEBOUNCE_MS);
  });

  card.addEventListener('mouseleave', () => {
    clearTimeout(timer);
    video.pause();
    video.removeAttribute('src'); // stop bandwidth immediately
    video.load();
    video.style.opacity = '0';
  });
});
</script>

The 150 ms debounce avoids burning your daily mint quota when a user sweeps the cursor across a grid. Always remove src + call load() on leave — pausing alone keeps the connection open.

React — universal player hook

import { useEffect, useState } from "react";

async function mintPreview(
  videoId: string,
  kind: "full" | "reel" | "bts" = "full",
) {
  const res = await fetch("https://awfrtgkoramnvpsvrjjv.supabase.co/functions/v1/partner-api/v1/media/preview-url", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${import.meta.env.VITE_MVM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ video_id: videoId, kind }),
  });
  if (!res.ok) throw new Error(`mint failed: ${res.status}`);
  const { data } = await res.json();
  return data.stream_url as string; // valid 15 min
}

export function VideoPreview({
  videoId,
  kind = "full",
}: { videoId: string; kind?: "full" | "reel" | "bts" }) {
  const [src, setSrc] = useState<string | null>(null);

  useEffect(() => {
    let cancelled = false;
    mintPreview(videoId, kind).then((url) => {
      if (!cancelled) setSrc(url);
    });
    return () => { cancelled = true; };
  }, [videoId, kind]);

  if (!src) return <div>Loading…</div>;
  const vertical = kind === "reel";
  return (
    <video
      src={src}
      controls={kind !== "reel"}
      autoPlay={kind === "reel"}
      muted={kind === "reel"}
      loop={kind === "reel"}
      playsInline
      preload="metadata"
      style={{
        width: vertical ? "auto" : "100%",
        height: vertical ? "100%" : "auto",
        aspectRatio: vertical ? "9 / 16" : "16 / 9",
        background: "#000",
      }}
    />
  );
}

React — hover preview card

import { useRef } from "react";

export function HoverPreviewCard({
  videoId,
  poster,
}: { videoId: string; poster: string }) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const timerRef = useRef<number | null>(null);

  const onEnter = () => {
    timerRef.current = window.setTimeout(async () => {
      const url = await mintPreview(videoId, "full");
      const v = videoRef.current;
      if (!v) return;
      v.src = url;
      v.style.opacity = "1";
      v.play().catch(() => {});
    }, 150); // debounce
  };

  const onLeave = () => {
    if (timerRef.current) clearTimeout(timerRef.current);
    const v = videoRef.current;
    if (!v) return;
    v.pause();
    v.removeAttribute("src");
    v.load();
    v.style.opacity = "0";
  };

  return (
    <div
      onMouseEnter={onEnter}
      onMouseLeave={onLeave}
      style={{ position: "relative", aspectRatio: "16 / 9" }}
    >
      <img
        src={poster}
        alt=""
        style={{ width: "100%", height: "100%", objectFit: "cover" }}
      />
      <video
        ref={videoRef}
        muted
        loop
        playsInline
        preload="none"
        style={{
          position: "absolute",
          inset: 0,
          width: "100%",
          height: "100%",
          objectFit: "cover",
          opacity: 0,
          transition: "opacity .2s",
        }}
      />
    </div>
  );
}

Re-minting & caching

stream_url is valid for 15 minutes and bound to the partner key + request origin. Mint a fresh URL every time a user starts a new playback session. Don't store it in your database; don't put it in a sitemap; don't share it across users.