@blitzreels/sdk

Typed TypeScript client for the BlitzReels public API.

Official website: https://blitzreels.com/

The SDK is the shared API layer used by the BlitzReels CLI and external TypeScript integrations. It is intentionally free of Next.js/server-only imports.

Install

npm install @blitzreels/sdk

Usage

import { BlitzReelsClient } from "@blitzreels/sdk";

const client = new BlitzReelsClient({
  apiKey: process.env.BLITZREELS_API_KEY ?? "",
  baseUrl: "https://blitzreels.com/api/v1",
});

const auth = await client.auth.validate();

const projects = await client.projects.list({
  limit: 20,
  cursor: undefined,
  offset: undefined,
  search: undefined,
  status: "active",
});

const created = await client.projects.create({
  name: "Launch short",
  description: undefined,
  aspectRatio: "9:16",
  projectType: "video",
  carouselSettings: undefined,
});

const benchmark = await client.formats.runVideoModelBenchmark({
  prompt: "A red figure walks toward a circular platform at night.",
  leftModel: "wan-2.1",
  rightModel: "krea-wan-14b-t2v",
  durationSeconds: 5,
  leftLabel: null,
  rightLabel: null,
  brandLabel: "blitzreels",
  projectName: null,
  idempotencyKey: "benchmark:night-platform:v1",
});

await client.jobs.get({ jobId: benchmark.job_id });

await client.workspace.updateSettings({
  name: "Creator Studio",
  description: undefined,
  protectedWords: ["Brand", "Product"],
  iconStorageKey: undefined,
  defaults: undefined,
});

const scan = await client.onboarding.startBrandScan({
  websiteUrl: "https://example.com",
  businessOutcome: "book_calls",
});

await client.onboarding.getBrandScan({ runId: scan.run_id });
const brandProfile = await client.onboarding.getBrandProfile();

await client.onboarding.importLogo({
  profileId: brandProfile.profile?.id ?? null,
  logoUrl: null,
  replaceExisting: false,
});

await client.onboarding.complete({
  businessOutcome: brandProfile.profile?.business_outcome ?? "book_calls",
  websiteUrl: brandProfile.profile?.website_url ?? "https://example.com",
  socialProfiles: brandProfile.profile?.social_profiles ?? null,
  brandName: brandProfile.profile?.brand_name ?? "Creator Studio",
  tagline: brandProfile.profile?.tagline ?? null,
  audience: brandProfile.profile?.audience ?? null,
  offer: brandProfile.profile?.offer ?? null,
  conversionGoal: brandProfile.profile?.conversion_goal ?? null,
  tone: brandProfile.profile?.tone ?? null,
  colorPalette: brandProfile.profile?.color_palette ?? null,
  logoCandidates: brandProfile.profile?.logo_candidates ?? null,
  suggestedSafeWords: brandProfile.profile?.suggested_safe_words ?? null,
  workspaceDescription: null,
  platforms: ["linkedin", "tiktok"],
  saveWorkspaceIcon: true,
});

// Onboarding methods:
// startBrandScan, getBrandScan, getBrandProfile, updateBrandProfile,
// importLogo, complete.

const media = await client.media.list({
  folderId: undefined,
  assetType: "video",
  search: undefined,
  limit: 20,
  offset: undefined,
});

const upload = await client.media.initUpload({
  fileName: "video.mp4",
  contentType: "video/mp4",
  fileSizeBytes: 12_345_678,
});

const finalizedUpload = await client.media.finalizeUpload({
  storageKey: upload.storage_key,
  fileName: "video.mp4",
  contentType: "video/mp4",
  fileSizeBytes: 10_000_000,
  autoProcessEnabled: true,
  autoTranscribe: true,
  autoDescribeAfterTranscribe: undefined,
  autoSuggestShorts: true,
});

console.log(finalizedUpload.processing_run_id);
console.log(finalizedUpload.follow_up.short_suggestions_requested);

await client.media.importYoutube({
  url: "https://www.youtube.com/watch?v=...",
  folderId: undefined,
  quality: "1080p",
  fps: undefined,
  audioLanguage: undefined,
});

await client.media.update({
  assetId: "asset_id",
  name: "Renamed media",
  description: "Useful B-roll",
  folderId: undefined,
  allowUsingAsBroll: true,
});

await client.media.attachToProject({
  projectId: "project_id",
  assetId: "asset_id",
  startSeconds: 0,
  durationSeconds: undefined,
  layerIndex: undefined,
  placementIntent: "overlay",
  allowDuplicate: undefined,
  volume: 0.4,
});

await client.media.reframe.apply({
  assetId: "asset_id",
  projectId: "project_id",
  replaceTimelineItemId: "timeline_item_id",
  aspectRatio: "9:16",
  trimStartSeconds: null,
  trimEndSeconds: null,
  contentTypeHint: "podcast",
  layoutStrategy: "split",
  idempotencyKey: "reframe:project_id:v1",
});

await client.media.reframe.status({ assetId: "asset_id" });
await client.media.reframe.analyze({
  assetId: "asset_id",
  idempotencyKey: "reframe-analysis:asset_id:v1",
});

const reframe = await client.media.reframe.get({
  projectId: "project_id",
  reframeId: "reframe_id",
});

await client.media.reframe.updateSource({
  projectId: reframe.project_id,
  reframeId: reframe.reframe_id,
  sourceAssetId: reframe.views[0].source_asset_id,
  sourceCrop: { x: 0, y: 0, width: 0.5, height: 1 },
  sourceOffsetUnits: null,
  ignored: null,
  replacementAssetId: null,
  idempotencyKey: `reframe-source:${reframe.reframe_id}:v1`,
});

const character = await client.characters.create({
  name: "Virgile",
  type: "human",
  consistencyMode: "reference",
  referenceAssetIds: ["character_sheet_asset_id"],
  primaryReferenceAssetId: "character_sheet_asset_id",
  idempotencyKey: "character:virgile:v1",
});

const plan = await client.faceless.plans.create({
  projectId: "project_id",
  script: "Authored scene-by-scene narration",
  targetDurationSeconds: 30,
  visualStyle: "cinematic 3D animation",
  plannerModelId: undefined,
  imageModelId: undefined,
  videoModel: "seedance-2.0-ref2v",
  voiceId: undefined,
  includeCaptions: true,
  captionStyleId: undefined,
  generateBackgroundMusic: false,
  generateSoundEffects: false,
  characterIds: [character.id],
  idempotencyKey: "faceless:project_id:v1",
});

await client.clips.attachExport({
  assetId: "asset_id",
  projectId: "project_id",
  exportId: "export_id",
  confirmVisualQa: true,
  idempotencyKey: "attach:export_id:v1",
});

await client.media.deleteMany({
  ids: ["asset_id"],
  search: null,
  namePrefix: null,
  confirmDelete: true,
  dryRun: false,
  reason: "Remove duplicate upload",
  idempotencyKey: "media-delete:asset_id:v1",
  deleteGeneratedClips: false,
  deleteLinkedProjects: false,
});

const recordingSet = await client.recordingSets.create({
  name: "Product demo",
  idempotencyKey: "recording-set:create:v1",
});

const readyRecordingSets = await client.recordingSets.list({
  status: "ready",
  limit: 20,
  offset: 0,
});

await client.recordingSets.attachTrack({
  recordingSetId: recordingSet.recording_set_id,
  assetId: "camera_asset_id",
  role: "camera",
  participantLabel: "host",
  participantName: null,
  isPrimary: true,
  idempotencyKey: "recording-set:camera:v1",
});

await client.recordingSets.finalize({
  recordingSetId: recordingSet.recording_set_id,
  idempotencyKey: "recording-set:finalize:v1",
});

await client.media.folders.create({
  name: "B-roll",
  parentFolderId: null,
  description: undefined,
  iconType: "video",
});

const audioResults = await client.audioLibrary.search({
  query: "ambient riser",
  provider: "all",
  license: "cc0",
  audioType: "sound_effect",
  minDurationSeconds: undefined,
  maxDurationSeconds: 12,
  limit: 10,
  page: undefined,
});

await client.audioLibrary.importAsset({
  provider: audioResults.items[0].provider,
  externalId: audioResults.items[0].external_id,
  folderId: undefined,
  projectId: "project_id",
  startSeconds: 0,
  durationSeconds: 12,
  volume: 0.5,
  fadeInSeconds: undefined,
  fadeOutSeconds: undefined,
  loop: true,
  audioType: "sound_effect",
});

const project = await client.projects.inspect({
  projectId: "project_id",
  mode: "full",
});

const snapshot = await client.projects.renderSnapshot({
  projectId: "project_id",
  atSeconds: 3,
  targetWidth: undefined,
  imageFormat: undefined,
});

const silencePlan = await client.silence.plan({
  projectId: "project_id",
  timelineItemId: "timeline_item_id",
  paddingMs: undefined,
  silenceThresholdDb: undefined,
  minSilenceDurationSeconds: undefined,
  removeBlipsMaxDurationSeconds: undefined,
  useCaptionValidation: undefined,
});

await client.silence.apply({
  projectId: "project_id",
  timelineItemId: "timeline_item_id",
  paddingMs: undefined,
  silenceThresholdDb: undefined,
  minSilenceDurationSeconds: undefined,
  removeBlipsMaxDurationSeconds: undefined,
  useCaptionValidation: undefined,
  deleteSilentClips: undefined,
  manualSegmentOverrides: undefined,
  previewConfirmed: true,
});

API requests fail with a retryable timeout error after 30 seconds by default. Set requestTimeoutMs in the client config when an integration needs a different deadline.

Local API

const client = new BlitzReelsClient({
  apiKey: process.env.BLITZREELS_API_KEY ?? "",
  baseUrl: "http://localhost:3000/api/v1",
});

Local/development API keys use br_test_...; production keys use br_live_....

Source, releases, and license

The npm package is publicly installable, but its canonical source is private and proprietary. Version 0.2.0 added generation, bulk deletion, folder-emptying, clip-batch deletion, and richer media models.

Workspace 0.2.5 adds compound Reframe IDs, reads, and source-level updates. It includes the 0.2.3 multipart media, Recording Set, and share-download changes. Large CLI uploads use multipart transfer, and BLITZREELS_REQUEST_TIMEOUT_MS controls SDK API requests. Published behavior depends on the installed package version.

Admin recovery and other internal operator resources are not exported or included in the public artifact.

See LICENSE for the package terms.