Quickstart: TypeScript

npm install @probablyco/sdk
export PROBABLY_API_URL="https://studio.probably.co"
export PROBABLY_API_KEY="prb_..."

// List your Spaces and prepare a video with the TypeScript SDK. Preparing
// spends nothing: it answers with a preview and a confirmation, which you
// confirm with confirm_spend once the person agrees (see quickstart.ts).
// Run it with Bun, Deno or Node 23.6+:
//   npm install @probablyco/sdk
//   PROBABLY_API_KEY=prb_... node sdk-quickstart.ts
import { Probably, ProbablyError } from "@probablyco/sdk"

const apiKey = process.env.PROBABLY_API_KEY

if (!apiKey) throw new Error("Set PROBABLY_API_KEY to a key from Settings → Connections")

// The production API, unless PROBABLY_API_URL names another.
const probably = new Probably({ apiKey, baseUrl: process.env.PROBABLY_API_URL })

try {
  const { spaces } = await probably.tools.list_spaces()

  console.log("Spaces:", spaces.map((space) => space.name).join(", "))

  const [space] = spaces

  if (!space) throw new Error("This key reaches no Space")

  // A new request key per video: retrying with the same key returns the same draft.
  const draft = await probably.tools.prepare_video({
    spaceId: space.id,
    brief: "A 15-second TikTok for a reef-safe SPF 50 sunscreen, filmed on a hiking trail",
    lengthSeconds: 15,
    requestKey: crypto.randomUUID(),
  })

  console.log(`Prepared ${draft.videoId}, nothing spent yet:`, draft.preview)
  console.log(`Confirm ${draft.confirmationId} before ${draft.expiresAt} to start it.`)
} catch (error) {
  // A refusal names its outcome, such as "rate-limited" (see /docs/errors).
  if (!(error instanceof ProbablyError)) throw error

  console.error(
    `Refused: ${error.outcome} (${error.status}), request ${error.requestId}`,
    error.message,
  )
  process.exitCode = 1
}

export PROBABLY_API_URL="https://studio.probably.co"
export PROBABLY_API_KEY="prb_..."
bun add zod

// Prepare a video from a brief, confirm the spend once you agree to its
// preview, and read the video back. Run it with Bun or Node 23.6+, with zod
// installed:
//   PROBABLY_API_KEY=prb_... bun quickstart.ts
// It asks before it spends; pass --yes to agree in advance, as a script you
// have already approved might.
import { createInterface } from "node:readline/promises"

import { z } from "zod"

const apiUrl = process.env.PROBABLY_API_URL ?? "https://studio.probably.co"

const apiKey = process.env.PROBABLY_API_KEY

if (!apiKey) throw new Error("Set PROBABLY_API_KEY to a key from Settings → Connections")

/** A JSON value. */
type Json = string | number | boolean | null | Json[] | { [key: string]: Json }

/** A tool's input: the JSON object its schema describes. */
type ToolInput = { [field: string]: Json }

/** Calls one tool with its input; its answer, checked by `answer`, or an error with the refusal. */
async function call<Answer>(tool: string, input: ToolInput, answer: z.ZodType<Answer>) {
  const response = await fetch(`${apiUrl}/api/v1/tools/${tool}`, {
    method: "POST",
    headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
    body: JSON.stringify(input),
  })

  // A refusal names its outcome, such as "not-enough-credits" (see /docs/errors).
  if (!response.ok) throw new Error(`${tool}: ${response.status} ${await response.text()}`)

  return answer.parse(await response.json())
}

// The fields this script reads; the API reference lists every one.
const spaceList = z.object({ spaces: z.array(z.object({ id: z.string(), name: z.string() })) })

const prepared = z.object({
  videoId: z.string(),
  confirmationId: z.string(),
  expiresAt: z.string(),
  preview: z.looseObject({ kind: z.string() }),
  confirmUrl: z.string().nullable(),
})

const confirmed = z.object({ videoId: z.string(), result: z.looseObject({}) })

const video = z.object({
  name: z.string(),
  run: z.object({ status: z.string() }).nullable(),
})

const { spaces } = await call("list_spaces", {}, spaceList)

const [space] = spaces

if (!space) throw new Error("This key reaches no Space")

// A new request key per video: retrying with the same key returns the same draft.
const draft = await call(
  "prepare_video",
  {
    spaceId: space.id,
    brief: "A 15-second TikTok for a reef-safe SPF 50 sunscreen, filmed on a hiking trail",
    lengthSeconds: 15,
    requestKey: crypto.randomUUID(),
  },
  prepared,
)

console.log(`Prepared a video in ${space.name}:`, draft.preview)

/** Whether the person running this agrees to spend: `--yes` given in advance, or a yes typed now. */
async function agreed(question: string) {
  if (process.argv.includes("--yes")) return true

  const prompt = createInterface({ input: process.stdin, output: process.stdout })
  const answer = await prompt.question(`${question} [y/N] `)

  prompt.close()

  return /^y(es)?$/i.test(answer.trim())
}

// Nothing is spent until the person agrees to the preview above. A key that
// may not spend gets a link for them to confirm it in the studio instead.
if (draft.confirmUrl) {
  console.log(`Confirm it in the studio: ${draft.confirmUrl}`)
} else if (await agreed("Start this video, spending what the preview shows?")) {
  const started = await call("confirm_spend", { confirmationId: draft.confirmationId }, confirmed)

  console.log("Started:", started.result)
} else {
  console.log(`Not started. The confirmation expires at ${draft.expiresAt}.`)
}

const current = await call("get_video", { videoId: draft.videoId }, video)

console.log(current.run ? `${current.name}: ${current.run.status}` : `${current.name}: not started`)