SDK

@vfrey/sdk is not on npm yet, and it needs the hosted vfrey service, which is not live yet. Today the SDK ships as a packed file next to @vfrey/vfrey in the beta, and you install it from that file. The page shows how it will be used.

@vfrey/sdk is a TypeScript client for the public API. It has no runtime dependencies, uses fetch, and needs Node 22 or newer (or a browser). Errors are typed, rate limits are retried with backoff, and every POST carries an idempotency key.

Install

Until it is published, install the packed file:

npm install ./vfrey-sdk-VERSION.tgz

Start

import { Vfrey } from "@vfrey/sdk";

const vfrey = new Vfrey({
  baseUrl: process.env.VFREY_API_URL!, // the vfrey service address
  token: process.env.VFREY_TOKEN!,     // a personal token, vfr_...
});

const me = await vfrey.me();
console.log(me.org.name, me.plan, me.credits.balance);

Edit a scene, then render it

import { Vfrey, edit } from "@vfrey/sdk";
import { writeFile } from "node:fs/promises";

const vfrey = Vfrey.fromEnv();
const project = await vfrey.cloud.projects.link({ localProjectId: "my-channel", name: "My channel" });

const scene = await vfrey.cloud.scenes.get(project.id, "intro");
await vfrey.cloud.scenes.edit(project.id, "intro", {
  ifMatch: scene.scene.sha256,
  operations: [
    edit.setText("#title", "Summer sale"),
    edit.setStyle(".caption", "color", "#ffcc00"),
  ],
});

const { video } = await vfrey.render.renderScene({
  project,
  scene: "intro",
  script: { title: "Summer sale", lines: ["Everything is 30% off.", "This week only."] },
  runId: "campaign-42-intro", // a retry returns the same job and charges once
});
if (video) await writeFile("intro.mp4", await vfrey.cloud.download(video));

renderScene submits the job, waits for it, and finds the video. Use render.submit, render.wait, and render.getVideo separately to do other work while it renders.

Edit without conflicts

scenes.update reads the scene, runs your function, and writes the edits. If someone else saved first, it reads again and re-runs your function, up to 3 times.

await vfrey.cloud.scenes.update(project.id, "intro", (scene) =>
  scene.elements
    .filter((e) => e.tag === "h1" && e.text?.includes("Hello"))
    .map((e) => edit.setText({ id: e.id }, "Bonjour")),
);

Handle errors

Every failure throws a subclass of VfreyError with status, code, and message.

import { CreditsRequiredError, ConflictError, LimitReachedError } from "@vfrey/sdk";

try {
  await vfrey.render.renderScene({ /* ... */ });
} catch (e) {
  if (e instanceof CreditsRequiredError) console.log(`need ${e.required}, have ${e.balance}: ${e.buyCreditsUrl}`);
  else if (e instanceof LimitReachedError) console.log(`limit resets ${e.resetsAt}`);
  else if (e instanceof ConflictError) console.log(`changed, current sha ${e.currentSha256}`);
  else throw e;
}

The classes match the API error codes. A scene edit that fails throws BadRequestError with .operation, the index of the failing operation.

Page through files

for await (const file of vfrey.cloud.pullAll(project.id, { kinds: ["scene", "meta"] })) {
  const bytes = await vfrey.cloud.download(file); // the token is not sent to the download link
}

The SDK also reads Topics, Creators, and mail drafts: vfrey.topics, vfrey.creators, vfrey.mail.drafts. They use the same plans and credits as Topics, Creators, and Mail.

Getting Started

Commands

Concepts

Paid features

Teams and cloud

Reference

Resources

Install

Start

Edit a scene, then render it

Edit without conflicts

Handle errors

Page through files

​Install

​Start

​Edit a scene, then render it

​Edit without conflicts

​Handle errors

​Page through files

Install

Start

Edit a scene, then render it

Edit without conflicts

Handle errors

Page through files