CRM & IDX Platform Video API Integration

Why Platforms Are the Natural Home for Listing Video

Every standalone video tool in real estate has the same structural problem: it has to convince an agent to leave the software they already work in, upload photos a second time, retype the address, and remember to come back. That friction is why adoption of listing video has stayed low despite universal demand for it.

A CRM or IDX platform has none of that friction. The photos are already uploaded. The address is already validated. The agent's headshot, logo, and brokerage colors are already on file. When a listing goes active, your system knows before anyone else does. You are one webhook away from a feature the standalone tools cannot match.

What has stopped platforms from shipping it is infrastructure. Rendering video means GPU capacity, a job queue, encoding pipelines, storage, and a team to keep it running. That is a multi-quarter commitment that never survives roadmap prioritization against features your agents are actively asking for. An API removes the infrastructure question entirely and leaves you with an integration problem your existing backend team can finish in a sprint.

The Integration Architecture

There are three components to build, regardless of your stack. A trigger that decides when a listing deserves a video, a proxy endpoint that calls the API with your server-side key, and a webhook receiver that attaches the finished video back to the listing record. Everything else is detail.

Start with the data model. You need a job table that maps the API's job id to your internal listing and tenant, because the webhook will arrive with the job id and nothing else. Without this table you cannot route a completed video back to the right listing.

-- Minimal schema for platform-side job tracking
CREATE TABLE api_video_jobs (
  id            BIGSERIAL PRIMARY KEY,
  job_id        TEXT UNIQUE NOT NULL,   -- id returned by the API
  listing_id    BIGINT NOT NULL REFERENCES listings(id),
  tenant_id     BIGINT NOT NULL REFERENCES tenants(id),
  status        TEXT NOT NULL DEFAULT 'processing',
  credits_used  INT,
  video_url     TEXT,
  error         TEXT,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  completed_at  TIMESTAMPTZ
);

CREATE INDEX idx_jobs_tenant_month ON api_video_jobs (tenant_id, created_at);
CREATE UNIQUE INDEX idx_one_active_per_listing
  ON api_video_jobs (listing_id) WHERE status = 'processing';

That partial unique index is doing important work. It makes it impossible to have two in-flight jobs for the same listing, which is the database-level defense against duplicate generation when your listing webhook fires twice in quick succession.

Choosing Your Generation Trigger

This decision determines your credit spend more than any other. Each option is defensible and most mature platforms end up combining two — an automatic trigger for the common case plus a manual button for exceptions.

Wiring the Trigger to Generation

Here is the core handler. It runs inside your platform when a listing becomes active, selects the best photos, enforces a per-tenant cap, and enqueues the render. Note that it never blocks on the render itself.

// POST /internal/listings/:id/generate-video  (server-side only)
import { db } from "@/lib/db"

const API_BASE = "https://app.photoaivideo.com/api/v1"

export async function generateListingVideo(listingId: number) {
  const listing = await db.listing.findUnique({
    where: { id: listingId },
    include: { photos: { orderBy: { position: "asc" } }, tenant: true },
  })

  // 1. Guard: already generated or in flight?
  const existing = await db.apiVideoJob.findFirst({
    where: { listingId, status: { in: ["processing", "completed"] } },
  })
  if (existing) return { skipped: "already_generated" }

  // 2. Guard: enough usable photos?
  const photos = listing.photos.filter((p) => p.isPublic).slice(0, 10)
  if (photos.length < 6) return { skipped: "insufficient_photos" }

  // 3. Guard: tenant within monthly cap?
  const startOfMonth = new Date(new Date().setDate(1))
  const used = await db.apiVideoJob.count({
    where: { tenantId: listing.tenantId, createdAt: { gte: startOfMonth } },
  })
  if (used >= listing.tenant.monthlyVideoCap) {
    return { skipped: "tenant_cap_reached" }
  }

  // 4. Enqueue the render
  const res = await fetch(`${API_BASE}/videos/create-reel`, {
    method: "POST",
    headers: {
      "X-API-Key": process.env.PHOTOAIVIDEO_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      images: photos.map((p) => ({ url: p.url, effect: pickEffect(p.roomType) })),
      aspect_ratio: "9:16",
      text_overlay: { text: listing.address, position: "bottom" },
      logo_url: listing.tenant.logoUrl,
      webhook_url: `${process.env.APP_URL}/webhooks/photoaivideo`,
    }),
  })

  if (!res.ok) {
    const body = await res.text()
    throw new Error(`Generation failed (${res.status}): ${body}`)
  }

  const { job_id } = await res.json()

  // 5. Record the mapping so the webhook can find its way home
  await db.apiVideoJob.create({
    data: { jobId: job_id, listingId, tenantId: listing.tenantId, status: "processing" },
  })

  return { jobId: job_id }
}

Three guards before any credit is spent, and the job mapping written immediately after the call succeeds. That ordering matters: if you write the mapping before the API call and the call fails, you will have a phantom job that blocks future generation for that listing.

Receiving the Finished Video

The webhook is where the video becomes visible to your agents. Keep the handler small, idempotent, and fast — acknowledge with a 200 before doing anything slow like copying the file to your own storage.

// POST /webhooks/photoaivideo
export async function POST(req: Request) {
  const event = await req.json()
  const { job_id, status, video_url, credits_used, error } = event

  const job = await db.apiVideoJob.findUnique({ where: { jobId: job_id } })
  if (!job) return new Response("ok", { status: 200 })      // unknown job, ignore
  if (job.status !== "processing") return new Response("ok", { status: 200 }) // idempotent

  if (status === "completed") {
    await db.$transaction([
      db.apiVideoJob.update({
        where: { jobId: job_id },
        data: { status: "completed", videoUrl: video_url, creditsUsed: credits_used, completedAt: new Date() },
      }),
      db.listing.update({
        where: { id: job.listingId },
        data: { videoUrl: video_url, hasVideo: true },
      }),
    ])
    await notifyAgent(job.listingId)   // in-app badge or email
  } else {
    await db.apiVideoJob.update({
      where: { jobId: job_id },
      data: { status: "failed", error: error ?? "unknown" },
    })
  }

  return new Response("ok", { status: 200 })
}

The two early returns make this handler safe to call repeatedly, which matters because webhook delivery is at-least-once. Updating the job and the listing inside one transaction means an agent never sees a listing marked as having video without a URL attached.

If your architecture cannot accept inbound webhooks, poll GET /videos/{job_id} on a schedule instead. The async jobs and polling guide covers backoff strategy and reconciliation sweeps in depth.

Multi-Tenant Credits and Billing

This is where platform integrations differ most from single-company ones. You hold one API plan and resell capacity to many tenants, so you need your own accounting layer on top of the API's credit balance.

A listing costs photos + 1 credits — one per clip plus one to merge. An eight-photo reel is nine credits, roughly $3.17 on the API Growth plan. Your job table already records every generation with a tenant id, so per-tenant usage is a single aggregate query.

-- Monthly usage per tenant, for invoicing and cap enforcement
SELECT
  t.name,
  COUNT(*)                     AS videos_generated,
  SUM(j.credits_used)          AS credits_consumed,
  ROUND(SUM(j.credits_used) * 0.352, 2) AS cost_usd
FROM api_video_jobs j
JOIN tenants t ON t.id = j.tenant_id
WHERE j.status = 'completed'
  AND j.created_at >= date_trunc('month', now())
GROUP BY t.name
ORDER BY credits_consumed DESC;

For packaging, most platforms land on one of three models: bundle a set number of videos into existing tiers, charge a flat monthly video add-on per agent seat, or bill per listing generated. The SaaS packaging guide works through the margin math on each.

Handling IDX Gallery Quirks

IDX feeds introduce problems a normal upload flow never sees. The API fetches images by URL, so anything your feed does to those URLs becomes your problem.

Expiring signed URLs are the most common failure. If your IDX provider serves photos through short-lived tokens, the URL may be dead by the time the render worker fetches it. Copy the selected photos to your own persistent storage first and pass those URLs instead. Watermarked feed images are the second issue — generating from a watermarked source bakes the watermark into every frame, so prefer the unbranded original whenever your feed exposes one.

Finally, filter aggressively. IDX galleries routinely include floor plans, blurry exteriors, and duplicate angles. Selecting eight strong frames produces a better reel than passing thirty mediocre ones, and it costs a third as much. Ordering matters too — lead with the exterior, move through living spaces, and close on the primary bedroom or yard.

Mistakes That Cost Platforms Real Money

A Four-Phase Rollout

Resist the urge to ship this to your whole tenant base at once. Credit consumption at scale is hard to predict from a test account, and the failure modes you will hit are cheaper to fix small.

Positioning It to Your Agents and Your Market

The feature sells itself best when agents never have to think about it. The strongest framing is not "we added a video tool" — it is "every listing you enter now comes with a video." One is a feature you have to teach; the other is a benefit that lands instantly in a demo.

For sales and marketing, this becomes a differentiator in every competitive deal. Most CRM and IDX competitors have video on a roadmap. Being able to demo a listing going active and a finished vertical reel appearing minutes later is a moment competitors cannot match without the same infrastructure investment you just avoided.

Because generation is server-to-server, nothing in the output references PhotoAIVideo. The videos carry your platform's branding and your agents' logos, which means the feature strengthens your brand rather than introducing a third party into your product experience.

Common Questions

Getting Started

The integration is genuinely small relative to its impact: a job table, a guarded generation function, and a webhook handler. Everything hard about video — GPU capacity, encoding, storage, retries — sits on the other side of the API call.

Start with one internal listing and the code in this article. Once you see a finished vertical reel land on a listing record automatically, the rollout plan writes itself.