CatalogReel

Every request requires a bearer token in the Authorization header: Authorization: Bearer vid_live_…. Keys are created and revoked in the console. A missing or invalid key returns 401. A machine-readable OpenAPI 3.1 spec drives SDK generation and Postman import — or explore it interactively in the API reference.

Keep these values in your vendor integration environment. The only required server secret is the API key; the rest are stable request variables or values returned by CatalogReel.

A complete commercial takes four fields: vertical, subject, image_urls, and finish: "full" — which auto-fills the voiceover, burned captions, end card and music. Create the job, then poll until it's done. Everything else on this page is optional fine-tuning.

curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "vehicle",
    "image_urls": ["https://cdn.example.com/lot-1.jpg", "https://cdn.example.com/lot-2.jpg"],
    "subject": { "year": 2022, "make": "Toyota", "model": "RAV4", "price": 28990 },
    "finish": "full"
  }'
# → 202 { "id": "<uuid>", "status": "queued",
#         "resolved": { "credits": 30, "duration_seconds": 16, "narration": true, … } }

curl https://api.catalogreel.com/v1/videos/<uuid> \
  -H "Authorization: Bearer vid_live_••••"
# → { "status": "completed", "video_url": "https://.../final.mp4" }

A 16-second video like the above is 30 credits (~$6); the 202 response echoes the exact price and every resolved setting under resolved. Two cheap ways to experiment before spending more: estimate prices any request for free, and an 8-second render on the default fast quality is the cheapest real video (15 credits ≈ $3). Once a render is done, iterate on the finish for ~$1 with reprocess instead of re-rendering. vehicle and property are generally available; ecommerce is in beta — render quality is still being tuned.

Every creative knob belongs to one of three independent axes: Direction (how it's shot, before the render), Finish (how it's polished, after the render), and Intent (why the video exists — per-vertical). Pick what you want on each — they compose orthogonally, and the rest of the schema (subject, photos, branding, audio, format) is additive. When in doubt, set none of them: every axis has a smart default.

1 — Pre-render (HOW it's shot, before the render engine runs)

These fields change what the camera captures. They compose independently: a mountain-run direction at ultra-luxury pace in a mountains scene is a different beat from mountain-run at luxury pace on a dealership-lot.

2 — Post-render (HOW it's finished, after the render engine)

These re-apply during the stitch and can also be re-run via reprocess for ~$1 — no new render.

3 — Intent (the WHY)

Per-vertical "what is the video for" axes. They shape narration, structure, music defaults, and the CTA. All have smart defaults — set them only when you want to override what the listing signals already imply.

Worked example

A high-converting vehicle ad on a freshly arrived listing might combine all three buckets:

• Pre-render: direction: "spec-hero" — a spec-led shot template.
• Post-render: finish: "full" — complete ad, voiceover + captions + end-card + music auto-filled.
• Intent: shopper_intent: "recent_arrival" — narration says "just landed on the lot", the end-card CTA falls back to "Be the first to see it".

Each is independent of the others — picking one doesn't lock the rest. The same shape composes across verticals: swap shopper_intent for objective (ecommerce) or leave both unset (property) and the rest of the request is unchanged.

You send raw product photos; the API does the production work:

1. AI photo selection — every uploaded photo is scored and the strongest set is chosen, so you can send your whole shoot.
2. Cinematography planning — a per-scene plan decides which shot anchors each segment and how the camera moves.
3. Render & finalize — the generated video segments, narration/music, captions, brand overlay, and cinematic grading are stitched into the final MP4.

Complete, copy-pasteable requests for common goals — each shows how to compose the fields documented below for a specific outcome. Start from the closest one and adjust. vid_live_•••• stands in for your key.

Vehicle ad from a VIN

A dealer-ready ad from a VIN and lot photos: the API decodes the spec sheet and EPA MPG, and finish: "full" adds the voiceover, captions, end-card and music.

# Dealer: a finished vehicle ad from a VIN + lot photos. The API decodes the
# spec sheet and EPA MPG, and finish:"full" adds a voiceover,
# burned captions, an end-card CTA and beat-synced music.
curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "vehicle",
    "vin": "1FTFW1RG5NFB12345",
    "image_urls": [
      "https://cdn.example.com/truck-front.jpg",
      "https://cdn.example.com/truck-side.jpg",
      "https://cdn.example.com/truck-interior.jpg"
    ],
    "subject": { "price": 58995, "mileage": 12500 },
    "finish": "full",
    "duration": 24,
    "listing_url": "https://dealer.example.com/inventory/1FTFW1RG5NFB12345"
  }'

# → 202 { "id": "<uuid>", "status": "queued" } — poll GET /v1/videos/<uuid>.
# The on-screen spec callout shows the decoded specs and "28/36" MPG.

Commercial ad with your own script

Bring a hand-written voiceover and a logo overlay; full fills only what you omit and wraps your script with captions, an end-card and music.

# Your script, your logo: a full-finish ecommerce ad with a hand-written
# voiceover and a burned-in brand overlay. full fills only what you omit,
# so it keeps your script and adds captions, an end-card and music.
curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "ecommerce",
    "image_urls": ["https://cdn.example.com/chair-1.jpg", "https://cdn.example.com/chair-2.jpg"],
    "subject": { "title": "Aluminum Field Chair", "brand": "Field Co.", "price": 189 },
    "finish": "full",
    "narration": {
      "enabled": true,
      "script": "Folds flat, follows you anywhere. The Field Chair — weather-sealed aluminum, built for the long weekend."
    },
    "brand_overlay": {
      "logo_url": "https://cdn.example.com/logo.png",
      "brand_name": "Field Co.",
      "cta_text": "Shop the Field Chair"
    }
  }'

Real estate tour (9:16, captions)

A vertical listing tour with an auto-written narration and burned captions — captions just needs narration.enabled; the overlay pass that renders them switches on automatically.

# A vertical listing tour with an auto-written voiceover and burned captions.
# captions just needs narration.enabled — the overlay pass switches on automatically.
curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "property",
    "image_urls": [
      "https://cdn.example.com/home-exterior.jpg",
      "https://cdn.example.com/home-kitchen.jpg",
      "https://cdn.example.com/home-yard.jpg"
    ],
    "subject": {
      "propertyType": "single-family home",
      "bedrooms": 4, "bathrooms": 3, "squareFeet": 2650,
      "price": 825000, "city": "Austin", "state": "TX", "realEstateType": "sale"
    },
    "aspect_ratio": "9:16",
    "duration": 32,
    "narration": { "enabled": true, "auto_generate": true, "tone": "storyteller" },
    "captions": true,
    "music": "real-estate-warmth"
  }'

Agency / multi-tenant

Provision a customer once, then render on their behalf so each customer's jobs stay isolated. See Sub-tenants for the model.

# Agency / platform: provision a customer, then render on their behalf so each
# customer's jobs stay isolated. These calls use an umbrella key.

# 1) Create (or upsert) the sub-tenant under your own stable id.
curl -X POST https://api.catalogreel.com/v1/sub-tenants \
  -H "Authorization: Bearer vid_live_umbrella_••••" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "dealer_42", "name": "Westside Motors" }'

# 2) Mint a key scoped to that sub-tenant (it can only ever see dealer_42 jobs).
curl -X POST https://api.catalogreel.com/v1/keys \
  -H "Authorization: Bearer vid_live_umbrella_••••" \
  -H "Content-Type: application/json" \
  -d '{ "name": "dealer_42 server key", "sub_tenant": "dealer_42" }'
# → { "id": 7, "key": "vid_live_••••", "key_prefix": "vid_live_a1b2", ... }  (key shown once)

# 3) Render with the scoped key — no header needed, the scope is implicit.
curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{ "vertical": "vehicle", "vin": "1FTFW1RG5NFB12345", "image_urls": ["https://cdn.example.com/truck-1.jpg"] }'

Creates a video job and returns 202 with { id, status: "queued" } and a Location header pointing at the job's status URL. Generation takes minutes — poll that URL or set a webhook. All option fields below are wired end-to-end into the render.

The 202 body also carries a resolved object — everything the API already knows for certain about how the job will run, so you never have to guess what a default or smart-resolution did:

Background replacement is currently operator-gated. When VIDEO_API_BACKGROUND_REPLACEMENT_ENABLED is unset or false, create requests that include background are accepted but the field is ignored before the job is priced or rendered. When enabled, background replacement adds per-segment credits and those credits are reflected in estimate responses.

Dry-run the same duration, resolution, plan-cap, and background pricing used by POST /v1/videos without creating a job, holding balance, or touching rate-limit counters. Use this before presenting a price or disabling a submit button.

curl -X POST https://api.catalogreel.com/v1/videos/estimate \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 32,
    "resolution": "1080p",
    "background": true
  }'

# → {
#   "credits": 160,
#   "usd": 32,
#   "duration_seconds": 32,
#   "segments": 4,
#   "resolution": "1080p",
#   "background_credits": 0,
#   "spendable": 500,
#   "sufficient": true
# }

Body

Response

subject is a freeform object — send whatever structured data you have for the listing. Every field is optional; the more you provide, the richer the narration, the more accurate the on-screen highlights, and the more specific the prompt. Unknown keys are ignored, and price additionally feeds the automatic camera_style. The accepted fields per vertical:

Ecommerce (vertical: "ecommerce")

Vehicle (vertical: "vehicle")

# Vehicle: send a VIN and the API fills the spec sheet for you.
curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "vehicle",
    "vin": "1FTFW1RG5NFB12345",
    "image_urls": ["https://cdn.example.com/truck-1.jpg"],
    "subject": { "price": 58995, "mileage": 12500 }
  }'

# The server decodes year/make/model/trim/engine/transmission/drivetrain/fuel
# and looks up EPA city/highway/combined MPG, merging them into subject. Values
# you send yourself (here price + mileage) are always kept.

Real estate (vertical: "property")

Returns the job. Poll until status is completed or failed.

Re-runs only the post-processing (audio stitch, narration, captions, brand overlay, color grade and the full cinematic effects recipe) on a completed video's stored source — no new video generation. It costs a flat 5 credits (about $1), far cheaper than regenerating. Returns 202 with a new job id; poll GET /v1/videos/{new-id} for the result. The original video is unchanged.

curl -X POST https://api.catalogreel.com/v1/videos/<uuid>/reprocess \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "narration": { "enabled": true, "mode": "regenerate" },
    "captions": true,
    "caption_style": "highlight",
    "brand_overlay": { "brand_name": "Field Co.", "cta_text": "Shop now" }
  }'

# → 202 { "id": "<new-uuid>", "status": "processing" }
# Poll GET /v1/videos/<new-uuid> for the reprocessed video_url.

Reprocess or re-render?

Rule of thumb: anything applied after the render engine (the Finish axis) reprocesses for ~$1; anything that changes what the camera captured (the Direction axis, photos, length, fidelity) needs a new render.

Body (all optional)

Returns 404 if the job isn't yours, 409 if it isn't completed or has no stored source, and 402 if you don't have enough prepaid balance. The reprocess is billed as its own job and is refunded if it fails.

Cancels a job that is still pending, queued or processing, and refunds the balance held for it. A job that has already finished returns 409.

POST /v1/lounge creates one stable unlisted showroom URL for the organization, or for one customer when you send X-Sub-Tenant. The public page at /lounge/{token} needs no API key, so it works on kiosk browsers and smart TVs. By default it shows all completed videos with a final URL, deduped by VIN, listing URL, then final video URL. Use per-video overrides to hide a video or force-show a dedupe loser.

Branding settings are intentionally small in v1: logo_url, logo_position, logo_opacity, slide_duration_seconds, transition, muted, autoplay, and show_title_overlay. Rotate the public token with { "rotate_token": true } on PATCH /v1/lounge.

# Create the default lounge URL for the whole organization.
curl -X POST https://api.catalogreel.com/v1/lounge \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "logo_url": "https://cdn.example.com/dealer-logo.png",
      "logo_position": "top-right",
      "slide_duration_seconds": 12,
      "muted": true,
      "autoplay": true
    }
  }'
# → { "data": { "public_url": "https://api.catalogreel.com/lounge/lounge_...", ... } }

# Create/read the lounge URL for one customer instead.
curl -X POST https://api.catalogreel.com/v1/lounge \
  -H "Authorization: Bearer vid_live_umbrella_••••" \
  -H "X-Sub-Tenant: dealer_42" \
  -H "Content-Type: application/json" \
  -d '{}'

# Preview the deduped effective playlist.
curl https://api.catalogreel.com/v1/lounge/videos \
  -H "Authorization: Bearer vid_live_••••"

# Hide or force-show one completed video in the lounge.
curl -X PATCH https://api.catalogreel.com/v1/lounge/videos/<video-uuid> \
  -H "Authorization: Bearer vid_live_••••" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "hidden" }'

If you operate on behalf of many businesses (a DMS, CRM, or agency), an umbrella key can act for any of your customers: send the X-Sub-Tenant header with your own stable id for that customer. The header tags every write and filters reads, so each customer's jobs stay isolated. Sub-tenants are created on first use (or explicitly via POST /v1/sub-tenants). Alternatively, mint a scoped key bound to a single sub-tenant — it ignores the header and can only ever see its own jobs. Account-management routes (keys, sub-tenants, balance, webhook secret) require an umbrella key; sending X-Sub-Tenant with a scoped key returns 403.

# Tag writes — and filter reads — to one of your customers (umbrella key).
curl -X POST https://api.catalogreel.com/v1/videos \
  -H "Authorization: Bearer vid_live_••••" \
  -H "X-Sub-Tenant: dealer_42" \
  -H "Content-Type: application/json" \
  -d '{ "vertical": "vehicle", "vin": "1FTFW1RG5NFB12345", "image_urls": ["https://cdn.example.com/truck-1.jpg"] }'

# List only that customer's jobs:
curl "https://api.catalogreel.com/v1/videos" \
  -H "Authorization: Bearer vid_live_••••" \
  -H "X-Sub-Tenant: dealer_42"

These routes are for server-to-server integrations using an umbrella key. Scoped keys can create, list, retrieve, cancel, and reprocess their own videos, but they cannot manage account balance, keys, sub-tenants, or webhook secrets.

# Balance + usage (umbrella key only)
curl https://api.catalogreel.com/v1/account/balance \
  -H "Authorization: Bearer vid_live_umbrella_••••"

curl "https://api.catalogreel.com/v1/account/usage?limit=20" \
  -H "Authorization: Bearer vid_live_umbrella_••••" \
  -H "X-Sub-Tenant: dealer_42"

# Top up prepaid balance through Stripe Checkout
curl -X POST https://api.catalogreel.com/v1/credits/checkout \
  -H "Authorization: Bearer vid_live_umbrella_••••" \
  -H "Content-Type: application/json" \
  -d '{ "pack_id": "pack_growth" }'

# Webhook signing secret
curl https://api.catalogreel.com/v1/webhook-secret \
  -H "Authorization: Bearer vid_live_umbrella_••••"

curl -X POST https://api.catalogreel.com/v1/webhook-secret \
  -H "Authorization: Bearer vid_live_umbrella_••••"

Billing uses a prepaid balance. Each generation holds a reservation when the job is created and is charged only on success; a failed, cancelled, or partial job is fully refunded — you never pay for a video you didn't receive. Add balance in the console.

Public pricing is shown as an estimated dollar amount for the finished video. Internally, the API still returns the exact reservation for audit and idempotency. Each segment is a full 8s clip, so your requested duration snaps to the nearest 8s multiple — e.g. 16s → 2, 32s → 4, 48s → 6, 64s → 8 segments. Narration is included. Background replacement adds a small per-segment charge (one hero photo per segment). Reprocess is a low flat charge.

Plan limits

Plans are a limits bundle, not a subscription — they gate rate, concurrency, length and resolution. New organizations start on starter limits with 0 balance.

When prepaid balance is insufficient the request is rejected with 402 and { error, required, available } — nothing is queued. Per-key and per-plan limits return 429 (rate limit, with a Retry-After header; or too many concurrent jobs; or the daily job cap), and a duration or resolution beyond your plan returns 400.

Account creation does not require a card, but generation requires prepaid balance. New organizations start with 0 balance, so an unfunded request returns 402 before a job is queued.

Set webhook_url on a create request and we POST a signed event to it the moment the job reaches a terminal state — so you don't have to poll. Two event types: video.completed and video.failed. The data.object is the same job shape returned by GET /v1/videos/{id}.

Payload

{
  "id": "evt_8s9d7f6g5h4j3k2l",
  "type": "video.completed",
  "created_at": "2026-05-29T18:04:11.123Z",
  "data": {
    "object": {
      "id": "b3f1c2a4-…-uuid",
      "status": "completed",
      "video_url": "https://…/final.mp4",
      "thumbnail_url": "https://…/thumb.jpg",
      "duration_seconds": 16
      // …same shape as GET /v1/videos/{id}
    }
  }
}

Headers

Verifying the signature

Every delivery is signed with HMAC-SHA256 over {timestamp}.{raw body} using your organization's signing secret — reveal it under Webhook signing secret in the console or call GET /v1/webhook-secret with an umbrella key. Recompute it over the raw request bytes, constant-time compare against X-Video-Signature, and reject deliveries whose X-Video-Timestamp is more than 5 minutes old.

import crypto from "crypto";
import express from "express";

const app = express();
const SECRET = process.env.VIDEO_WEBHOOK_SECRET; // from the console

// Use the RAW body — verify the exact bytes, never a re-serialized object.
app.post("/webhooks/video", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.header("X-Video-Signature");
  const ts = req.header("X-Video-Timestamp");
  const raw = req.body.toString("utf8");

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() - Number(ts)) > 5 * 60_000) return res.sendStatus(400);

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${ts}.${raw}`)
    .digest("hex");
  const ok =
    !!sig && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(raw);
  // event.type === "video.completed" | "video.failed"
  // event.data.object === the job (same shape as GET /v1/videos/{id})
  res.sendStatus(200); // 2xx = acknowledged; anything else is retried
});

Delivery & retries

Respond 2xx to acknowledge. A non-2xx response, timeout (~5s), or network error is retried with backoff up to 6 attempts; after that the delivery is marked failed. Delivery is at-least-once, so dedupe on the event id. Targets must be public HTTPS URLs (private/loopback addresses are rejected) and redirects are not followed. Webhooks are an optimization — GET /v1/videos/{id} remains the source of truth.

There's no bespoke SDK to wait on — the API is plain REST and the OpenAPI 3.1 spec is the source of truth. Generate a typed client in your language, or browse the spec interactively in the API reference.

# Typed TypeScript types straight from the live spec
npx openapi-typescript https://api.catalogreel.com/v1/openapi.json -o catalogreel.d.ts

Validation failures return 400 with an error message listing every offending field (e.g. an unsupported aspect_ratio, an out-of-set duration, both narration.script and narration.auto_generate, captions without narration, a vertical-scoped field on the wrong vertical, or a pre-2026-06 field name — the message names the replacement). Auth failures return 401; unknown vertical or bad image URLs return 400. Reusing an idempotency_key returns the original job with HTTP 200 and is never double-charged. Credit and limit responses (402 / 429) are covered under Billing & limits.