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.

Create a job, then poll until it's done. The same call in three languages:

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/sku-1.jpg",
      "https://cdn.example.com/sku-2.jpg"
    ],
    "subject": {
      "title": "Aluminum Field Chair",
      "brand": "Field Co.",
      "category": "Outdoor Seating",
      "price": 189,
      "material": "anodized aluminum",
      "color": "slate",
      "keyFeatures": ["folds flat", "weather-sealed"]
    },
    "render_quality": "standard",
    "duration": 16,
    "post_level": 2,
    "narration": { "enabled": true, "auto_generate": true, "tone": "tiktok" },
    "camera_style": "ultra-luxury",
    "end_card_cta": "Shop now",
    "listing_url": "https://store.example.com/products/aluminum-field-chair"
  }'

# → 202 { "id": "<uuid>", "status": "queued" }

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

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 — note captions needs narration.enabled and post_level ≥ 2.

# A vertical listing tour with an auto-written voiceover and burned captions.
# captions requires narration.enabled + post_level >= 2.
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,
    "post_level": 2,
    "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.

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" },
    "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.

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.

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 / post_level ≥ 2, or end_card_cta with post_level < 2). 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.