My Video Gift
My Video GiftDevelopers

Getting started

Quickstart

The My Video Gift API turns photos, optional video clips, and a few details into a finished personalized film with an original song — server-side, no preview step, one flat price per delivery. This walkthrough goes from a key to a delivered film in five calls.

Every request is JSON over HTTPS. Authenticated calls carry your key as a Bearer token. The API base is below.

API base
https://myvideogift.com/api/v1

The flow, end to end

  1. 1

    Get a key

    Keys are issued to partner accounts as mvg_live_ (real money) or mvg_test_ (same API, sandbox). See Authentication for how to get one.

  2. 2

    Create a gift

    POST /v1/gifts with the occasion, recipient, and story. Returns a gift_id — the server owns the order from here.

  3. 3

    Add photos

    POST /v1/gifts/{id}/photos by public URL or inline base64. The server fetches, verifies, and stores them. Optionally add video clips the same way via POST /v1/gifts/{id}/clips.

  4. 4

    Render

    POST /v1/gifts/{id}/render with consent: true. This is the one paid call — it debits the tier price and starts the render.

  5. 5

    Poll for the film

    GET /v1/gifts/{id} until status is delivered-paid, then read film_url and gift_url.

1. Confirm your key and balance

A cheap authenticated read — good for verifying your key works before you spend.

curl
curl https://myvideogift.com/api/v1/account \
  -H "Authorization: Bearer mvg_live_..."
200 OK
{
  "key_id": "ak_1a2b3c4d",
  "label": "acme-gifts",
  "mode": "live",
  "status": "active",
  "balance_cents": 5000,
  "total_spent_cents": 2500,
  "total_deliveries": 1,
  "created_at": "2026-07-08T12:00:00.000Z"
}

2. Create a gift

occasion must be a real slug — browse them with GET /v1/occasions. tier defaults to signature and style defaults to gift. An optional Idempotency-Key makes a retried create return the original gift instead of a duplicate.

curl
curl -X POST https://myvideogift.com/api/v1/gifts \
  -H "Authorization: Bearer mvg_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8f21c9" \
  -d '{
    "occasion": "anniversary-video",
    "recipient_name": "Maria",
    "relationship": "wife",
    "memory": "Twenty-five years since the courthouse wedding in the rain.",
    "story_note": "She still hums the song from our first dance.",
    "feeling_words": ["tender", "grateful", "playful"],
    "tier": "signature",
    "style": "gift"
  }'
201 Created
{
  "gift_id": "b3f1c2a4-9e7d-4c6b-8a1f-2d5e6f7a8b9c",
  "status": "reserved",
  "tier": "signature",
  "style": "gift",
  "occasion": "anniversary-video",
  "share_slug": "maria-7x2k9q1p4m3n",
  "photo_limit": 30
}

3. Add photos

Up to 10 photos per request, up to 30 per gift. Each is fetched (public URL) or decoded (base64), verified to be a real JPEG/PNG/WebP, and stored. subject_photo_index marks the main person.

curl
curl -X POST https://myvideogift.com/api/v1/gifts/b3f1c2a4-9e7d-4c6b-8a1f-2d5e6f7a8b9c/photos \
  -H "Authorization: Bearer mvg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "photos": [
      { "url": "https://example.com/photos/wedding.jpg" },
      { "url": "https://example.com/photos/anniversary-trip.jpg" }
    ],
    "subject_photo_index": 0
  }'
200 OK
{
  "photo_count": 2,
  "photo_ids": ["p01", "p02"],
  "subject_photo_id": "p01"
}

4. Render — the paid call

consent: true is a required attestation that you hold the rights to these photos and the recipient's depiction. This debits the tier price and starts the render; it returns immediately with 202.

curl
curl -X POST https://myvideogift.com/api/v1/gifts/b3f1c2a4-9e7d-4c6b-8a1f-2d5e6f7a8b9c/render \
  -H "Authorization: Bearer mvg_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "consent": true }'
202 Accepted
{
  "status": "rendering",
  "tier": "signature",
  "charged_cents": 2500,
  "balance_cents": 2500,
  "poll_after_sec": 60
}

5. Poll until the film is ready

Wait poll_after_sec between polls (a render takes minutes). When status is delivered-paid, the delivery URLs appear. A held or failed run auto-refunds the charge.

curl
curl https://myvideogift.com/api/v1/gifts/b3f1c2a4-9e7d-4c6b-8a1f-2d5e6f7a8b9c \
  -H "Authorization: Bearer mvg_live_..."
200 OK — delivered
{
  "gift_id": "b3f1c2a4-9e7d-4c6b-8a1f-2d5e6f7a8b9c",
  "status": "delivered-paid",
  "tier": "signature",
  "occasion": "anniversary-video",
  "recipient_name": "Maria",
  "share_slug": "maria-7x2k9q1p4m3n",
  "photo_count": 2,
  "clip_count": 1,
  "created_at": "2026-07-08T12:00:00.000Z",
  "fulfillment": { "state": "succeeded", "stage": "deliver" },
  "charged_cents": 2500,
  "film_url": {
    "16x9": "https://myvideogift.com/api/gift/maria-7x2k9q1p4m3n/film?aspect=16x9",
    "9x16": "https://myvideogift.com/api/gift/maria-7x2k9q1p4m3n/film?aspect=9x16"
  },
  "gift_url": "https://myvideogift.com/gift/maria-7x2k9q1p4m3n"
}

Two ways to deliver

film_url is the raw full-HD MP4 (both aspect ratios) you can hand to your user or embed. gift_url is a hosted gift page that plays the film — send whichever fits.

Next steps

Read the API reference for every endpoint, field, and constraint. See Authentication for keys and rate limits, Pricing for the per-delivery tiers, and Errors for the coarse error codes.

An MCP server that wraps these endpoints for agents is coming soon.

Last updated 2026-07-11.