Trends

The Trends API runs ready-made Cast Swap recipes. A trend is a short clip with slots: the people, pets, products and place you can replace. Fill the slots with your own pictures and run the trend to get the clip back with them in it.

Trends are part of Nodaro Cloud. On a self-hosted install, every route answers 404. The routes take a bearer token. See Authentication.

Only published trends exist here. A draft, an unpublished or an unknown slug is a 404 on every route.

Endpoints

Names, descriptions, slot labels and hints come in the language of ?locale= when it is a platform language. Otherwise they come in your profile's language, and then in English.

A run stays readable in GET /v1/trends/runs after its trend moves to a new version or is unpublished.

What a trend holds

GET /v1/trends/:slug returns:

• slots: each slot's key, label, kind (person, pet, product or location), required, an optional hint and its default chips.
• examples: each example's result video and the pictures every slot used.
• previewSec: 4 when the trend offers a 4-second preview run, else null.
• resolutions: the resolutions the trend can run at.

A catalog card in GET /v1/trends carries the slug, name, tags, needs (how many slots of each kind), the length in seconds and isFavorite.

The run body

POST /v1/trends/:slug/estimate and POST /v1/trends/:slug/runs take the same body: { slots, example?, details?, preview?, resolution?, draft?, sessionId?, projectId? }.

The chips are the slot kind's own traits. Each chip is "new", made from your pictures, or "original", kept as in the clip:

{
  "slots": {
    "dancer": { "images": ["https://example.com/me.jpg"], "outfit": "original" }
  },
  "preview": true,
  "resolution": "480p"
}

The quote

The estimate answers expectedCredits, what the run is expected to be charged, and holdCredits, what is reserved when the run starts. breakdown lists the parts of the quote.

Repeats

POST /v1/trends/:slug/runs takes an Idempotency-Key header, 8 to 200 characters. A repeat with the same key answers with the first run's job. Nothing new is started or charged.

Permissions

An OAuth app needs:

• jobs:read to read the catalog, a trend and your runs;
• workflows:execute to estimate or start a run, plus assets:write to pass a sessionId;
• assets:write for favorites.

Errors

The body of a refusal is { error: { code, message } }. The slot errors also carry the slot's key as slot. The 400 refusals of the estimate and run routes come before anything is charged.

When the video engine refuses an estimate or a run, the trend routes answer with their own codes and fixed messages:

Runs that did not finish

A run in GET /v1/trends/runs that did not finish has error: { code, message }. The message is always the same fixed sentence, so branch on the code:

A run that did not fail and was not cancelled has error: null. A completed run carries videoUrl, posterUrl and creditsCharged. Each slot of the run says whether its pictures came from the example (fromExample).

From the SDK

client.trends wraps the routes. It is also importable as @nodaro/sdk/trends.

list(params?: ListTrendsParams): Promise<TrendPage<TrendCard>>
get(slug: string, params?: { locale?: string }): Promise<TrendDetail>
estimate(slug: string, request: TrendRunRequest): Promise<TrendEstimate>
run(slug: string, request: TrendRunRequest, options?: { idempotencyKey?: string }): Promise<{ jobId: string }>
runs(params?: ListTrendRunsParams): Promise<TrendPage<TrendRun>>
favorite(slug: string): Promise<void>
unfavorite(slug: string): Promise<void>

list() and runs() resolve to the page as it arrives, { data, next }. Pass next back as cursor; it is null on the last page. get(), estimate() and run() resolve to the payload, without the { data } envelope. "runs" is never a slug: the methods that take a slug throw a TypeError for it before any request.

import type { TrendRunRequest } from "@nodaro/sdk"

const { data: cards } = await client.trends.list({ q: "dance" })
const trend = await client.trends.get(cards[0].slug)

const request: TrendRunRequest = {
  // Every required slot needs 1–3 pictures; optional slots left out take the example's.
  slots: Object.fromEntries(
    trend.slots.filter((s) => s.required).map((s) => [s.key, { images: [myPhotoUrl] }]),
  ),
}
const quote = await client.trends.estimate(trend.slug, request)
console.log(`about ${quote.expectedCredits} credits, ${quote.holdCredits} held while it runs`)

const { jobId } = await client.trends.run(trend.slug, request, { idempotencyKey: crypto.randomUUID() })
const job = await client.jobs.get(jobId)

From the CLI

nodaro trends list --search dance
nodaro trends get <slug>
nodaro trends estimate <slug> --slot dancer=https://example.com/me.jpg --choice dancer.outfit=original
nodaro trends run <slug> --slot dancer=https://example.com/me.jpg --idempotency-key <key>
nodaro trends runs --trend <slug>
nodaro trends favorite <slug>

--slot repeats, with 1 to 3 pictures per slot. trends run spends credits, so run trends estimate first. See CLI commands.

From MCP

Four MCP tools cover trends: list_trends, get_trend, estimate_trend and run_trend. See MCP › Video. run_trend without confirm returns the quote and charges nothing. With confirm: true, after the user accepts the price, it starts the run and returns a job id.