Getting started
Authentication
Every authenticated request carries an API key as a Bearer token. Keys map one-to-one to a partner account and are hashed at rest — the raw secret is shown once at issuance and never again.
Sending your key
Put the key in the Authorization header. The scheme is case-insensitive; the token is not.
curl https://myvideogift.com/api/v1/account \
-H "Authorization: Bearer mvg_live_..."Live vs test mode
Both modes use the identical API surface. The prefix on the key decides which.
| Prefix | Mode | Behavior |
|---|---|---|
mvg_live_ | Live | Real renders, real money debited from prepaid credit. |
mvg_test_ | Test | Free sandbox: build and test the whole flow (auth, create, upload, status, errors). Rendering is disabled — a test render returns test_key_cannot_render; use a live key to render a real film. |
Getting a key
Sign up with your email on the developer dashboard, accept the acceptable-use policy, and create and manage your own test and live keys — fully self-serve.
A key has a mode (live / test), a founder-visible label, a prepaid credit balance, and a status of active or revoked. A revoked key stops authenticating immediately.
Treat the key like a password
The secret authorizes spending against your prepaid balance. Store it server-side, never ship it in client code or a public repo, and rotate it if it leaks. Report a compromised key to have it revoked.
Auth failures
All error responses are JSON with a coarse error code and Cache-Control: no-store.
| Field | Type | Description |
|---|---|---|
| not_found | 404 | The API is not enabled. The entire /v1 surface answers 404 when the feature flag is off — it reveals nothing about whether a key is valid. |
| unauthorized | 401 | Missing, malformed, unknown, or revoked key. These cases are deliberately indistinguishable. |
Rate limits
Per-IP and per-key limits back-stop abuse; a burst gets 429 rate_limited with a Retry-After header. The public discovery endpoints (occasions, samples) need no key but are IP-limited. These are generous for legitimate use — a durable edge firewall is the real limiter.
| Endpoint | Per key | Per IP |
|---|---|---|
GET /v1/occasions | — | 60 / min |
GET /v1/samples | — | 60 / min |
GET /v1/account | 60 / min | 120 / min |
POST /v1/gifts | 30 / min, 300 / day | 60 / min |
POST /v1/gifts/{id}/photos | 60 / 10 min | 120 / min |
POST /v1/gifts/{id}/clips | 30 / 10 min | 60 / min |
POST /v1/gifts/{id}/clips/{clip_id} | 10 / 10 min | 20 / min |
POST /v1/gifts/{id}/render | 10 / min, 60 / day | 30 / min |
GET /v1/gifts/{id} | — | 240 / min |
Rate-limit response
{
"error": "rate_limited",
"retryAfter": 42
}Last updated 2026-07-11.