Branded Listing Reels: Assembly, Pacing and White-Label Output

Clips Are Raw Material, Reels Are the Product

The PhotoAIVideo API separates these two steps for a reason. POST /api/v1/videos turns one photo into one cinematic clip. POST /api/v1/reels merges two to twenty completed clips into a single video. The merge costs one credit no matter how many clips go into it.

That split is the leverage point. The clips are commodity raw material — every product built on this API gets the same quality of motion out of the same photo. What differentiates your product is everything you decide about assembly: which clips, in what order, with which effects, at what aspect ratio, wrapped in whose brand. That is a product decision, and it is where you should spend your engineering effort.

This guide covers each of those decisions concretely. For the mechanics of waiting on the underlying jobs, see our async jobs and polling guide, and check the API reference for the current set of parameters each endpoint accepts.

Assigning Effects by Room Type

The single highest-leverage improvement you can make to automated output is to stop using one effect everywhere. Each camera move communicates something different, and matching the move to the subject is what makes a reel feel edited by a person.

In code, this becomes a lookup rather than a hardcoded constant. If your listing data already labels photos by room — and most MLS feeds and photographer deliveries do — you can assign effects automatically with no user input at all.

// Match the camera move to the subject instead of orbiting everything.
const EFFECT_BY_ROOM = {
  exterior_front: "tilt_up",     // rising reveal flatters a facade
  living_room: "orbit_right",    // show depth and volume
  kitchen: "orbit_left",         // opposite direction breaks repetition
  primary_bedroom: "orbit_right",
  bathroom: "pan_right",         // calmer move for a smaller space
  backyard: "pan_left",
  detail: "zoom_in",             // features: fireplace, range, view
  aerial: "zoom_out",
}

const FALLBACK_CYCLE = ["orbit_right", "zoom_in", "orbit_left", "pan_right"]

function effectFor(photo, index) {
  // Prefer a room-aware choice; otherwise rotate so nothing repeats back to back.
  return EFFECT_BY_ROOM[photo.roomType] ?? FALLBACK_CYCLE[index % FALLBACK_CYCLE.length]
}

The fallback cycle matters as much as the lookup. When room labels are missing, rotating through a small set of effects still guarantees that no two adjacent clips use the same move — which removes the most obvious tell of automated output at essentially zero cost.

Ordering Clips Into a Tour

Async rendering returns clips in completion order, which is effectively random. If you merge in that order, you get a slideshow that jumps from a bathroom to the backyard to a bedroom. Buyers read that as disorienting even if they cannot articulate why.

// A walkthrough order a buyer would actually experience.
const TOUR_ORDER = [
  "exterior_front",
  "entry",
  "living_room",
  "kitchen",
  "dining",
  "primary_bedroom",
  "bedroom",
  "bathroom",
  "backyard",
  "aerial",
]

function sortForTour(photos) {
  return [...photos].sort((a, b) => {
    const ai = TOUR_ORDER.indexOf(a.roomType)
    const bi = TOUR_ORDER.indexOf(b.roomType)
    // Unlabeled photos sink to the end rather than scrambling the sequence.
    return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi)
  })
}

async function buildBrandedReel(listing, brand) {
  const ordered = sortForTour(listing.photos).slice(0, 12)  // 12 good > 20 mediocre

  // Start every clip concurrently, but remember the intended position.
  const jobs = await Promise.all(
    ordered.map((photo, i) =>
      fetch(API + "/videos", {
        method: "POST",
        headers: { ...HEADERS, "Content-Type": "application/json" },
        body: JSON.stringify({
          imageUrl: photo.url,
          effect: effectFor(photo, i),
          duration: 5,
        }),
      })
        .then((r) => r.json())
        .then((job) => ({ ...job, position: i })),
    ),
  )

  await Promise.all(jobs.map((j) => waitForVideo(j.jobId)))

  // Re-sort by intended position — completion order is not tour order.
  const inOrder = [...jobs].sort((a, b) => a.position - b.position)

  const reel = await fetch(API + "/reels", {
    method: "POST",
    headers: { ...HEADERS, "Content-Type": "application/json" },
    body: JSON.stringify({ videoJobIds: inOrder.map((j) => j.jobId) }),
  }).then((r) => r.json())

  return waitForReel(reel.jobId)
}

The position field carried through the async boundary is the important detail. Without it, there is no way to recover the intended sequence after twelve concurrent renders finish at unpredictable times.

Aspect Ratios Are Not Interchangeable

Agents publish to Instagram Reels, TikTok, YouTube Shorts, Facebook, their listing page, and the MLS. Those are not the same shape, and cropping between them destroys composition. A horizontal kitchen shot center-cropped to vertical routinely cuts out the island the photo was framed around.

Practically, this means your product should treat output format as a variant of one listing rather than as a separate job the agent has to think about. Check the API reference for the aspect ratio and duration parameters currently supported, then expose a single choice — "where are you posting this?" — and derive the rest.

Branding Without Asking the Agent

Branding fails when it depends on the agent remembering to apply it. Because you are calling the API server-to-server, you already know who the agent is, which brokerage they belong to, and what their brand rules are. Apply them automatically.

// Brand resolution: agent overrides brokerage, brokerage overrides platform default.
async function resolveBrand(agentId) {
  const agent = await db.agents.findById(agentId)
  const brokerage = await db.brokerages.findById(agent.brokerageId)

  return {
    logoUrl: agent.logoUrl ?? brokerage.logoUrl,
    primaryColor: agent.primaryColor ?? brokerage.primaryColor,
    contactLine: agent.phone ?? brokerage.phone,
    // Brokerages can lock branding so agents cannot drift off-template.
    locked: brokerage.enforceBranding === true,
  }
}

// The agent's entire interaction is one click; branding is never a question.
async function generateForAgent(agentId, listingId) {
  const brand = await resolveBrand(agentId)
  const listing = await db.listings.findById(listingId)

  return buildBrandedReel(listing, brand)
}

The locked flag is what brokerages actually buy. Marketing directors care less about producing video than about every agent producing video that looks like it came from the same firm. If your product can guarantee that, you are selling brand control, not rendering.

Cache Clips, Re-Merge Cheaply

Clips cost one credit each; a merge costs one credit total. That asymmetry has a direct architectural consequence: download and keep every finished clip in your own storage. When an agent wants a shorter cut, a different order, or an updated brand, you re-merge the clips you already own instead of re-rendering them.

For a twelve-photo listing, that is the difference between thirteen credits and one. Teams that skip clip caching end up paying full price every time a customer wants a small revision — and small revisions are most of what customers want.

Five Mistakes That Make Output Look Automated

Frequently Asked Questions