SDK

@howells/motif-sdk runs the same Tasks as the CLI from Node, with a Model chosen for you and a price you can read first.

@howells/motif-sdk is the public Node SDK for Motif: Task-first image, video and utility work on fal, plus a provider-agnostic image layer. The CLI is built on it, so a command and its SDK function choose the same Model.

Install

npm install @howells/motif-sdk

Run a Task

The Task client, createMotif, is the fal surface. Name a Task and, optionally, a Tier, and Motif chooses the Model, builds its request and runs it on fal.

import { createMotif } from "@howells/motif-sdk";

const motif = createMotif(); // reads FAL_KEY

const result = await motif.generate({
  prompt: "editorial product photo",
  resolution: "2K",
  tier: "quality",
});

if (result.isErr()) {
  throw result.error;
}

console.log(result.value.model, result.value.files[0]?.url, result.value.cost);

Every Task function returns a Result from neverthrow and does not throw for fal request failures. Check isErr() or isOk().

Plan without calling fal

plan(task, input, { dryRun: true }) resolves the Model and returns the endpoint, body and projected cost with no network call and no key. It is the SDK’s form of --dry-run.

const plan = motif.plan(
  "erase",
  { image: "https://example.com/room.png", prompt: "the chair" },
  { dryRun: true }
);

if (plan.isOk()) {
  console.log(plan.value.model, plan.value.cost);
}

Token-billed Models report cost: { usd: null, basis: "unknown" }. A published representative price is not an exact total.

Tiers

Each Task ranks its Models by Tier. balanced is the default. TASKS.generate and TASKS.vary expose the current choices, and explicit Models, Looks and pins take precedence over the ranking.

Main exports

• createMotif: the Task client, with one function per Task plus run, stream, plan, upload and deletePayloads.
• TASKS, TASK_IDS, TIERS, resolveTask, modelProfile, tierChangesChoice: the Task registry and Model resolution.
• createMotifImage from @howells/motif-sdk/image: generate, edit and best-of-N across OpenRouter, OpenAI, Replicate and fal.
• ASPECT_RATIOS, RESOLUTIONS, FORMAT_PRESETS: shared sizing metadata.
• LOOKS, CREATIVE_TAXONOMY, enrichPrompt, validateCreativeDirection: the house Looks and Moods.
• formatCost, sumCosts: cost formatting and totals.
• getFalKeyFromEnv: key parsing.

The image layer

createMotifImage is for callers who choose the provider and Model themselves. It is built on the Vercel AI SDK image interface, and every result carries a per-call cost.

The full reference, including streaming and best-of-N, is in the package README.