Skip to Content

JavaScript SDK

Install and use the official VidNavigator JavaScript/TypeScript SDK (v2.5.0) to transcribe, analyze, extract, and search video content.

The official JavaScript and TypeScript SDK for the VidNavigator API. Responses are parsed into typed model classes, and long-running work such as speech-to-text, extraction, tweet analysis and TikTok scraping runs as background jobs, so media of any length works with a single await.

npm version License

npm package

vidnavigator 2.5.0 on the npm registry.

GitHub repository

Source code, issues and changelog.

This page documents version 2.5.0. Coming from 1.x? See Upgrading from 1.x.

Installation

npm install vidnavigator@2.5.0

Requirements: Node.js 16+ (18+ for the examples that use the global fetch). The only runtime dependencies are axios and form-data. Full TypeScript types ship with the package.

The SDK is for server-side use. It reads local files for uploads and schema files, and your API key must never be shipped to a browser.

Initialization

Get your API key in the Developer Dashboard.

import { VidNavigatorClient } from 'vidnavigator';

const vn = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY!,
});

Configuration

OptionDefaultDescription
apiKey(required)Your VidNavigator API key
baseURLhttps://api.vidnavigator.com/v1API base URL
axiosConfigPassed to the underlying axios instance: HTTP timeout, proxy, extra headers, ...
const vn = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY!,
  axiosConfig: {
    timeout: 120_000, // per HTTP request, in ms
    proxy: { protocol: 'http', host: 'proxy.internal', port: 3128 },
  },
});

axiosConfig.timeout limits each HTTP request. How long the SDK waits for a background job is set per call with timeoutMs (see Background jobs).

Supported platforms

PlatformTranscript (captions)Transcribe (speech-to-text)Watch (scenes)Carousel
YouTubeYes-Yes-
Instagram Reels-YesYesYes
Instagram Posts-YesYesYes (all_videos)
TikTokYesYesYes-
X / TwitterYesYesYes-
VimeoYesYesYes-
FacebookYesYesYes-
DailymotionYesYesYes-
LoomYesYesYes-
SnapchatYes, when Snapchat has a transcriptYesYesYes (highlights: img_index, all_videos)
Uploaded filesYesYes--

Transcript = fast extraction of the platform's own captions. Transcribe = speech-to-text by AI models, for when captions are unavailable. Watch = what the video shows, scene by scene, next to its transcript, via vn.watch().


Transcripts

Captions from any platform

getTranscript auto-detects the platform from the URL. Instagram has no captions, so use transcribe for it.

const { video_info, transcript } = await vn.getTranscript({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  language: 'en',
});

console.log(video_info.title);    // "Rick Astley - Never Gonna Give You Up"
console.log(video_info.channel);  // "Rick Astley"
console.log(video_info.duration); // 212

// Timed segments by default (a single string when transcript_text: true)
if (Array.isArray(transcript)) {
  for (const seg of transcript.slice(0, 3)) {
    console.log(`[${seg.start.toFixed(1)}s] ${seg.text}`);
  }
}
// [0.0s] We're no strangers to love
// [3.4s] You know the rules and so do I

Common options: video_url, language, metadata_only, fallback_to_metadata, transcript_text (full transcript as one string), include_usage.

getYouTubeTranscript() still works but is deprecated: it forwards to getTranscript() and logs a warning.

Speech-to-text

vn.transcribe() runs speech-to-text as a background job and resolves with the result, whatever the video length.

// Instagram Reel (speech-to-text only)
const { video_info, transcript } = await vn.transcribe('https://www.instagram.com/reel/C86ZvEaqRmo/');
console.log(video_info.title);
console.log(transcript);

// More options: pass an object instead of a URL
const result = await vn.transcribe(
  { video_url: 'https://www.tiktok.com/@user/video/1234567890', transcript_text: true },
  { include_usage: true }
);
console.log(result.usage?.total_credits);

For TikTok, X, Vimeo, Facebook, Dailymotion, Loom and Snapchat you can use either getTranscript (captions, fast) or transcribe (speech-to-text).

Instagram carousels

Select one video by index, or transcribe every video in the post:

// Transcribe the 2nd video in a carousel
const single = await vn.transcribe('https://www.instagram.com/p/ABC123/?img_index=2');
console.log(single.video_info.carousel_info);
// { total_items: 5, video_count: 3, image_count: 2, selected_index: 2 }

// Transcribe ALL videos in a carousel
const all = await vn.transcribe({
  video_url: 'https://www.instagram.com/p/ABC123/',
  all_videos: true,
});

if ('carousel_info' in all) {
  console.log(`${all.carousel_info.transcribed_count} of ${all.carousel_info.video_count} videos transcribed`);

  for (const video of all.videos) {
    if (video.status === 'success') {
      console.log(`Video #${video.index}: ${video.video_info?.title}`, video.transcript);
    } else {
      console.log(`Video #${video.index}: failed — ${video.message}`);
    }
  }
}

Watch

New in 2.4.0.

vn.watch() reads what a video shows, next to what it says. The result holds the transcript and a list of scenes: for each one, when it starts and ends, a description of the picture, and the text readable on screen. It works with every platform getTranscript and transcribe support, and runs as a background job.

const watched = await vn.watch('https://www.tiktok.com/@nasa/video/7300000000000000000');

for (const scene of watched.scenes) {
  console.log(`[${scene.start.toFixed(0)}s - ${scene.end.toFixed(0)}s] ${scene.description}`);
  if (scene.on_screen_text) console.log(`    on screen: ${scene.on_screen_text}`);
}
// [4s - 12s] A presenter stands in front of a world map and points at Europe.
//     on screen: BREAKING NEWS

if (Array.isArray(watched.transcript)) {
  for (const seg of watched.transcript) console.log(`[${seg.start.toFixed(1)}s] ${seg.text}`);
}

console.log(watched.frames_analyzed); // number of frames that were analyzed

The transcript comes from the platform's captions when it has them, and from speech-to-text otherwise. A video without speech is not an error: transcript is empty, transcript_error says why, and the scenes are returned. The same goes for a YouTube video without captions.

const watched = await vn.watch(url);
if (watched.transcript_error) {
  console.log(watched.transcript_error.error); // e.g. "transcript_not_available"
}
console.log(watched.scenes.length, 'scenes');

Pass an object instead of a URL for more options:

OptionTypeDescription
video_urlstringURL of the video (?img_index=N selects one video of an Instagram carousel or a Snapchat highlight)
detailstringHow closely the picture is followed: 'low', 'auto' (the default) or 'high'. The number of frames depends on the video at every level: few on a fixed shot, many on a fast-cut clip. A higher level analyzes more frames when the picture changes often
include_transcriptbooleanDefault true. false returns the scenes only (the result has no transcript)
transcript_textbooleanReturn the transcript as a single string instead of segments
webhook_urlstringOptional; see Webhooks

The waiting options (timeoutMs, include_usage, ...) go in the second argument, as for every background job. With include_usage: true the result has a usage block; the frames are its frame_analysis charge.

To start it without waiting, use the handle, as for any background job:

const job = await vn.watch.submit({ video_url: url, detail: 'high' }, { include_usage: true });
console.log(job.task_id);

const watched = await job.result();                                  // waits if needed
console.log(watched.usage?.charge_for('frame_analysis')?.quantity);  // the frames, as the frame_analysis charge

const later = vn.watch.resume(savedTaskId);                          // the same handle, later

vn.watchVideo({ video_url, detail, include_usage: true }) is the same call with include_usage in the payload, like transcribeVideo().

Errors worth handling: NotFoundError with error_code 'frames_not_available' (a live stream, or a clip of a few seconds, has no picture to read) and BadRequestError with error_code 'video_too_long' (videos longer than 2 hours are not accepted, except on YouTube).

See the Watching Videos guide and the Watch endpoint.


AI analysis

Get a summary, the people, places and key subjects, and a direct answer to a natural-language question. query is optional.

const { video_info, transcript_analysis } = await vn.analyzeVideo({
  video_url: 'https://www.youtube.com/watch?v=4czjS9h4Fpg',
  query: 'Where did the rover land?',
});

console.log(transcript_analysis.summary);
console.log(transcript_analysis.query_answer?.answer);            // direct answer to your question
console.log(transcript_analysis.query_answer?.relevant_segments); // supporting transcript excerpts
console.log(transcript_analysis.people);        // [{ name, context }, ...]
console.log(transcript_analysis.places);
console.log(transcript_analysis.key_subjects);  // [{ name, description, importance }, ...]

See the Analyzing Videos guide for billing details.

Use what the video shows

New in 2.5.0.

By default the analysis reads what is said. With include_scenes: true it also reads what the video shows: its scenes, with the text readable on screen. Ask for it when the answer may be on screen rather than spoken, or when the video has little or no speech.

const { transcript_analysis, scenes, frames_analyzed } = await vn.analyzeVideo({
  video_url: 'https://www.dailymotion.com/video/x84243e',
  query: 'What are the ingredients and their quantities?',
  include_scenes: true,
});

console.log(transcript_analysis.query_answer?.answer);
// "Shredded cooked chicken 500 g; mayonnaise 300 g; requeijão 250 g; ..."

console.log(frames_analyzed); // 30
for (const scene of scenes ?? []) {
  console.log(scene.start, scene.description, '| on screen:', scene.on_screen_text);
}

scenes holds the same scenes as vn.watch(). When the video has no transcript, or no picture to read, the analysis is made from the other source and transcript_error or scenes_error says why. The frames are charged on top of the analysis: 1 credit per 2,000 frames analyzed, with at least 667 frames per hour of video.

For a video longer than 10 minutes, run the same analysis as a background job with vn.analyze:

const result = await vn.analyze({ video_url: url, query: 'What is shown?', include_scenes: true }); // waits

const job = await vn.analyze.submit({ video_url: url, include_scenes: true });                     // or start it
const later = await job.result();                                                                 // and collect it

vn.analyzeFile({ file_id, include_scenes: true }) uses the scenes kept with an uploaded file: see Scenes of a file.


Structured extraction

Define a schema (a standard JSON Schema), or say in plain words what you need with what_to_extract, and get back structured data extracted from any video or file transcript. See the Data Extraction guide for schema design tips.

From an online video

const { data, video_info, usage } = await vn.extractVideoData({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  schema: {
    type: 'object',
    properties: {
      topic:      { type: 'string', description: 'Main topic of the video' },
      language:   { type: 'string', description: 'Primary spoken language (ISO 639-1)' },
      tone:       { type: 'string', description: 'Overall tone', enum: ['positive', 'negative', 'neutral', 'mixed'] },
      key_quotes: { type: 'array',  description: 'Top 3 memorable quotes', items: { type: 'string', description: 'A quote' } },
    },
  },
  what_to_extract: 'Determine the topic, language, tone, and notable quotes.',
  include_usage: true,
});

console.log(data);
// { topic: "A classic pop love song", language: "en", tone: "positive", key_quotes: [...] }

console.log(video_info?.title, video_info?.duration); // "Rick Astley - Never Gonna Give You Up" 212

console.log(usage?.analysis_tokens?.total_tokens); // 847
console.log(usage?.total_credits);                 // 2

extractVideoData() runs as a background job, so videos of any length work. With transcribe: true (the default), a video without captions is transcribed first. The result has the extracted data, the video's video_info (a VideoInfo), usage when requested, and schema when you passed none (Without a schema). vn.extractVideo() and job.result() on vn.extractVideo.submit() return the same shape.

video_info on extraction results requires 2.1.0. In 2.0.0 it is always undefined.

Fields read from the picture

With include_scenes: true (new in 2.5.0) the fields can also be filled from what the video shows — a price on screen, a product, a caption — not only from what is said. frames_analyzed is then the number of frames read, charged on top of the extraction.

const { data, frames_analyzed } = await vn.extractVideo({
  video_url: 'https://www.dailymotion.com/video/x84243e',
  schema: {
    type: 'object',
    properties: {
      dish: { type: 'string', description: 'Name of the dish' },
      ingredients: {
        type: 'array',
        description: 'Every ingredient, with its quantity',
        items: { type: 'string', description: 'One ingredient and its quantity' },
      },
    },
  },
  include_scenes: true,
});
console.log(data.ingredients); // read from the text on screen: this video only has music

vn.extractFileData({ file_id, schema, include_scenes: true }) does the same on an uploaded file, once its scenes have been analyzed: see Scenes of a file.

From an uploaded file

const { data } = await vn.extractFileData({
  file_id: 'your-file-id',
  schema: {
    type: 'object',
    properties: {
      action_items: { type: 'array',  description: 'Action items from the meeting', items: { type: 'string', description: 'An action item' } },
      next_meeting: { type: 'string', description: 'When is the next meeting scheduled?' },
      sentiment:    { type: 'string', description: 'Overall meeting mood', enum: ['productive', 'tense', 'casual', 'urgent'] },
    },
  },
});

Without a schema

Pass what_to_extract alone, in plain words (new in 2.6.0). The schema is written from it and comes back as a JSON Schema in schema; pass it as schema in later calls to get the same fields:

const { data, schema } = await vn.extractVideoData({
  video_url: 'https://www.tiktok.com/@user/video/1234567890',
  what_to_extract: 'Every product shown or mentioned, with its price and whether it is sponsored',
});
console.log(data);   // { products: [{ name: 'Wireless earbuds', price: 49.99, sponsored: true }] }
console.log(schema); // { type: 'object', properties: { products: {...} }, ... }

const next = await vn.extractVideoData({ video_url: otherUrl, schema });

The same text gives the same fields. extractFileData takes what_to_extract alone the same way. With a schema, what_to_extract only guides the extraction and no schema comes back.

From a schema file

For larger schemas, pass a JSON or YAML file. It is sent as multipart form-data.

const { data } = await vn.extractVideoData({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  schemaFilePath: './schemas/video-extraction.yaml',
});

Pass at most one of schema and schemaFilePath, or neither when what_to_extract is given.

From a Zod schema

A Zod schema converted to JSON Schema can be passed directly:

import { z } from 'zod';

const MeetingNotes = z.object({
  action_items: z.array(z.string().describe('An action item')).describe('Action items from the meeting'),
  sentiment: z.enum(['productive', 'tense', 'casual', 'urgent']).describe('Overall meeting mood'),
});

const { data } = await vn.extractFileData({
  file_id: 'your-file-id',
  schema: z.toJSONSchema(MeetingNotes), // Zod 4; with Zod 3, zodToJsonSchema(MeetingNotes) from zod-to-json-schema
});

Schema rules: schema is a standard JSON Schema whose root is an object (type: 'object' with properties). Each property has a type: string, number, integer, boolean, array (with items) or object (with properties, up to 10), and a description saying what to put in it. enum lists the allowed values of a field. At most 10 fields per level and 3 levels of nesting. required and additionalProperties change nothing: a field the video does not give is null. See Schema Format for the other keywords. An invalid schema is rejected with a BadRequestError before anything runs.


Tweet claim analysis

Pass a tweet ID (not the full URL). Attached media of any length is transcribed, so this also runs as a background job.

const statement = await vn.tweetStatement('1585841080431321088');

console.log(statement.final_statement);     // the core claim, in the author's voice
console.log(statement.detailed_analysis);   // claim, context, evidence and stance
console.log(statement.claim_type, statement.intent, statement.tone, statement.emotion, statement.authority);
console.log(statement.topics, statement.entities);
console.log(statement.tweet_media_summary); // summary of attached video/images, if any

See the Tweet Claim Analysis guide.


Background jobs

Transcription, watch, structured extraction, tweet analysis and TikTok scraping run as background jobs on VidNavigator. The SDK always uses the async endpoints, so video length is never a problem.

Each operation comes in two shapes:

OperationWait for the resultStart it and come back later
Transcriptionawait vn.transcribe(url)await vn.transcribe.submit(url)
Watch (scenes and transcript)await vn.watch(url)await vn.watch.submit(url)
Structured extractionawait vn.extractVideo({ video_url, schema })await vn.extractVideo.submit({ ... })
Tweet claim analysisawait vn.tweetStatement(tweetId)await vn.tweetStatement.submit(tweetId)
TikTok profile scrapeawait vn.tiktokProfile(profileUrl)await vn.tiktokProfile.submit(profileUrl)
TikTok keyword searchawait vn.tiktokSearch(query)await vn.tiktokSearch.submit(query)
TikTok LIVE searchawait vn.tiktokLiveSearch(query)await vn.tiktokLiveSearch.submit(query)

The 1.x methods transcribeVideo(), extractVideoData() and getTweetStatement() still work with the same arguments. They are now wrappers around the operations above.

Start many at once

.submit() returns a Job right away. Each job has a task_id, status() (checks once), result() (waits, then returns the result) and wait() (waits, then returns the final task without throwing on failure):

const urls = ['https://www.instagram.com/reel/A/', 'https://www.instagram.com/reel/B/', 'https://vimeo.com/123'];

const jobs = await Promise.all(urls.map((url) => vn.transcribe.submit(url)));
console.log(jobs.map((job) => job.task_id)); // store these if you may need to come back later

const results = await Promise.allSettled(jobs.map((job) => job.result()));
results.forEach((r, i) => console.log(urls[i], r.status === 'fulfilled' ? r.value : r.reason.message));
const job = await vn.extractVideo.submit({
  video_url: 'https://www.facebook.com/watch/?v=1234567890',
  schema: {
    type: 'object',
    properties: {
      speakers: { type: 'array',  description: 'Names of everyone who speaks', items: { type: 'string', description: 'A speaker name' } },
      verdict:  { type: 'string', description: 'The final conclusion of the video' },
    },
  },
});

console.log(await job.status()); // 'processing' | 'completed' | 'failed'
const { data } = await job.result();

Come back later

A job keeps running even if your process stops waiting, and its result stays available for 1 hour after it finishes. Keep the task_id and reattach with .resume():

const job = vn.transcribe.resume(savedTaskId);
const result = await job.result();

Timeouts

The one-liners and result() wait up to 30 minutes by default, then throw a TaskTimeoutError that carries the task_id. The job is not lost:

import { TaskTimeoutError } from 'vidnavigator';

try {
  const result = await vn.transcribe(url, { timeoutMs: 5 * 60 * 1000 });
} catch (err) {
  if (err instanceof TaskTimeoutError) {
    saveForLater(err.task_id); // later: await vn.transcribe.resume(err.task_id).result()
  } else {
    throw err;
  }
}

Failures

When a job fails, result() and the one-liners throw the same error class as any other API error (for example NotFoundError for a missing video), built from the job's error details and carrying the task_id. wait() returns the failed task instead, with task.error set.

When a job can't start, submitting throws right away and no job is created:

  • InsufficientCreditsError (402): not enough credits. A job can also run out of credits while it runs; result() then throws the same error, so handle it in both places.
  • TooManyActiveJobsError (429): too many of your jobs are already running. Wait for some to finish and retry.

Large batches

Your account can only run a limited number of jobs at once, so Promise.all over hundreds of URLs will hit TooManyActiveJobsError. Keep a fixed number in flight:

import { TooManyActiveJobsError } from 'vidnavigator';

async function transcribeAll(urls: string[], concurrency = 10) {
  const results = new Map<string, unknown>();
  const queue = [...urls];

  async function worker() {
    for (let url = queue.shift(); url; url = queue.shift()) {
      for (;;) {
        try {
          results.set(url, await vn.transcribe(url));
          break;
        } catch (err) {
          if (err instanceof TooManyActiveJobsError) {
            await new Promise((r) => setTimeout(r, 10_000)); // wait for running jobs to finish
            continue;
          }
          results.set(url, err); // record the failure and move on
          break;
        }
      }
    }
  }

  await Promise.all(Array.from({ length: concurrency }, worker));
  return results;
}

Progress and restarts

// Log every task snapshot while waiting
const started = Date.now();
const result = await vn.transcribe(url, {
  onPoll: (task) => console.log(`${task.task_id}: ${task.task_status} after ${Math.round((Date.now() - started) / 1000)}s`),
});

Save each task_id as soon as you submit, so a crash or deploy doesn't lose the work:

import { writeFileSync, readFileSync, existsSync } from 'fs';

const job = await vn.transcribe.submit(url);
writeFileSync('pending-jobs.json', JSON.stringify([...pending(), job.task_id]));

// After a restart: pick every job back up
for (const taskId of pending()) {
  const result = await vn.transcribe.resume(taskId).result();
  // ... store the result, then drop taskId from pending-jobs.json
}

function pending(): string[] {
  return existsSync('pending-jobs.json') ? JSON.parse(readFileSync('pending-jobs.json', 'utf8')) : [];
}

Webhooks

Pass webhook_url to any job operation (transcription, watch, extraction, tweet analysis, TikTok profile, keyword and LIVE search), or set an account-wide default in Studio → API. A per-job webhook_url overrides the default, and webhook_url: '' turns it off for one job. Webhooks are optional: waiting with result() works the same either way and remains the source of truth.

const job = await vn.transcribe.submit({
  video_url: 'https://www.instagram.com/reel/C86ZvEaqRmo/',
  webhook_url: 'https://example.com/hooks/vidnavigator',
});
console.log(job.webhook_url); // where the notification will be sent, or null

Verify each delivery with constructWebhookEvent(), passing the raw request body:

import express from 'express';
import { VidNavigatorClient, constructWebhookEvent, WebhookSignatureError, WEBHOOK_HEADERS } from 'vidnavigator';

const vn = new VidNavigatorClient({ apiKey: process.env.VIDNAVIGATOR_API_KEY! });
const app = express();

app.post('/hooks/vidnavigator', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = constructWebhookEvent(
      req.body,                               // raw Buffer, not parsed JSON
      req.headers[WEBHOOK_HEADERS.signature], // "t=<unix_ts>,v1=<hex>"
      process.env.VIDNAVIGATOR_WEBHOOK_SECRET!
    );
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.status(400).send('Invalid signature');
    throw err;
  }
  res.sendStatus(200); // acknowledge quickly; any 2xx counts

  // Deliveries can repeat: dedupe on req.headers[WEBHOOK_HEADERS.delivery].
  if (event.type === 'transcribe.completed') {
    const result = await vn.transcribe.resume(event.data.task_id).result();
    console.log(result);
  } else if (event.type === 'tiktok_profile.completed') {
    const task = await vn.tiktokProfile.resume(event.data.task_id).result(); // every video, all pages
    console.log(task.videos.length);
  } else if (event.type.endsWith('.failed')) {
    console.error(event.data.task_id, event.data.error); // { error, message, http_status }
  }
});
  • event.data.result holds the raw result for transcription, watch, extraction and tweet events, unless it was over 256 KB (result_truncated: true). For TikTok events it is only a summary. resume(task_id).result() always gets the full parsed result.
  • For extract_video.completed events, event.data.video_info holds the raw video metadata. It is sent even when the result was truncated.
  • verifyWebhookSignature(rawBody, signatureHeader, secret) returns true or false instead of throwing.
  • Deliveries older than 5 minutes are rejected by default. Change this with { toleranceSeconds }; 0 turns the check off.
  • (await job.refresh()).webhook shows the delivery status: { status, attempts, response_status, last_error, delivered_at }.

Event types are transcribe.*, watch.*, extract_video.*, tweet_statement.*, tiktok_profile.*, tiktok_search.* and tiktok_live_search.*, each .completed or .failed. See Webhooks for the full delivery contract.


TikTok

Profile scraping

vn.tiktokProfile() scrapes a public profile in the background and returns the finished task with every matching video (the SDK fetches all result pages for you):

const task = await vn.tiktokProfile({
  profile_url: 'https://www.tiktok.com/@tiktok',
  max_posts: 250,
  after_datetime: '2024-01-01',
});

console.log(`Matched ${task.videos.length} videos`, task.stats);
const videos = task.videos; // TikTokVideo[], published_at parsed as Date

Options: max_posts, after_datetime, before_datetime, min_likes, max_likes, webhook_url. Datetimes accept YYYY-MM-DD or full ISO strings with a timezone.

To read the results one page at a time, or grab them as a single JSON file, submit the job and use the page-level method:

const job = await vn.tiktokProfile.submit('https://www.tiktok.com/@tiktok');
await job.wait();

// Page by page
let cursor: string | undefined;
do {
  const page = await vn.getTikTokProfileScrape(job.task_id, { limit: 100, cursor });
  handle(page.videos);
  cursor = page.pagination?.next_cursor ?? undefined;
} while (cursor);

// Or the whole result as one JSON file (short-lived signed URL)
const { download_url } = await vn.getTikTokProfileScrape(job.task_id, { limit: 1 });
if (download_url) {
  const fullProfile = await (await fetch(download_url)).json();
  console.log(fullProfile.videos.length);
}

Then feed each video into the transcript or extraction APIs:

for (const video of videos) {
  if (!video.url) continue;

  const { transcript } = await vn.getTranscript({
    video_url: video.url,
    transcript_text: true,
    fallback_to_metadata: true,
  });
  console.log(video.published_at?.toISOString(), video.title, transcript);
}

For large profiles, process videos sequentially or with a small concurrency limit so you do not exhaust credits or hit rate limits.

vn.tiktokSearch() works the same way and returns the finished task with every result:

const task = await vn.tiktokSearch({
  query: 'ai tools',
  max_results: 100,
  sort_by: 'most_liked',          // 'relevance' | 'most_liked' | 'newest'
  published_within: 'this_month', // 'all' | 'past_24_hours' | 'this_week' | 'this_month' | 'last_3_months' | 'last_6_months'
  min_views: 10000,
});

console.log(task.stats?.sort_by, task.stats?.published_within); // what the search actually ran with
for (const result of task.results) {
  console.log(result.published_at?.toISOString(), result.url, result.stats?.views);
}
  • Without sort_by, results come back newest first. Without published_within, an after_datetime more than 24 hours ago picks the smallest window that covers it.
  • parallel_search_slices (2 to 4) runs several search chains in parallel to go past TikTok's single-chain limit (about 115 to 140 items). Billing grows with the number of slices.
  • country picks whose TikTok results you get ('fr', 'de', 'jp', ..., default 'gb'; 'us' is refused). Billing: 1 residential_request per 30 results returned (task.stats.results_count), minimum 1 per search and 1 per 5 pages read.
  • Other filters: after_datetime, before_datetime, min_likes, max_likes, min_views, max_views, webhook_url. Page through results with getTikTokSearch(task_id, { cursor, limit }).

See the Searching TikTok guide.

New in 2.2.0.

vn.tiktokLiveSearch() finds TikTok LIVE rooms broadcasting right now for a keyword, and returns the finished task with every room and its stream URLs:

const task = await vn.tiktokLiveSearch({ query: 'gaming', country: 'us' });

for (const room of task.results) {
  console.log(room.title, room.author?.unique_id, room.stats?.viewers, room.category, room.hashtags);
  const urls = room.stream_urls;
  if (urls) {
    const q = urls.default_quality ?? 'hd';
    console.log('FLV:', urls.flv[q], 'HLS:', urls.hls[q], 'audio only:', urls.audio_only);
  }
}
  • Each room (TikTokLiveRoom) has id, url, author and stats like a keyword result, plus started_at (a Date), stats.viewers / stats.total_viewers, hashtags (the title's #tags), category (e.g. 'Gaming') and game_tags.
  • stream_urls holds flv and hls URLs keyed by quality (origin, uhd, hd, sd, ld), default_quality, audio_only and expires_at. The URLs play while the LIVE is on. They are returned by default; include_stream_urls: false leaves them out. Not every LIVE offers HLS.
  • country defaults to 'us'; max_results caps the rooms (TikTok serves about 50 per keyword). Billing: 1 residential_request per 30 rooms returned (task.stats.results_count), minimum 1.
  • Lower level: submitTikTokLiveSearch(payload) and getTikTokLiveSearch(task_id, { cursor, limit, include_usage }). See TikTok LIVE Search.

LIVE room

New in 2.3.0.

vn.getTikTokLiveRoom() returns one LIVE room right away, no job: by room_id, username or url (exactly one):

const { room, comments } = await vn.getTikTokLiveRoom({ username: 'creator', include_comments: true });

console.log(room.status, room.title, room.stats?.viewers, room.stats?.new_followers);
if (room.isLive) {
  for (const c of comments ?? []) console.log(c.created_at, c.author?.unique_id, c.text);
} else {
  console.log('ended at', room.ended_at);
}
  • room_id is a string (room ids have more digits than a JavaScript number holds); username is the streamer, with or without @ (their current LIVE, or their last one when offline); url is https://www.tiktok.com/@username/live, the profile URL, or a room's share_url. Options: include_comments (default false), comments_limit (1-50), include_stream_urls (default true), include_usage.
  • The room (TikTokLiveRoomDetail) has the LIVE search room fields plus status ('live' / 'ended', also room.isLive), ended_at, stats.new_followers, author.bio, author.following, share_url, chat_enabled, subscribers_only, age_restricted and products. No likes, comment count or share count: LIVE search returns those.
  • With include_comments: true the result also has comments (newest first; TikTok keeps only about the last 50), pinned_comment, intro and top_viewers.
  • A room or account that does not exist throws NotFoundError (error_code 'live_not_found'). A shorter axiosConfig.timeout is raised to two minutes for this call. Billing: 1 residential_request, 2 with include_comments (1 when the room has ended); not billed when the room is not found. See TikTok LIVE Room.

Search YouTube

const videoResults = await vn.searchYouTube({
  query: 'how to deploy a Node.js app',
  focus: 'relevance',   // 'relevance' (default) | 'recency' | 'popularity' | 'brevity'
  max_results: 5,       // caps how many candidates are analysed (and the cost)
  include_usage: true,
});

console.log(`Found ${videoResults.total_found} results`);
for (const r of videoResults.results) {
  console.log(`${r.title} — score: ${r.relevance_score}`);
  console.log(`  ${r.transcript_summary}`);
}

// If credits run out mid-search, a partial result is returned instead of throwing
if (videoResults.status === 'partial') {
  console.log('Partial results:', videoResults.error_code); // "insufficient_credits_video_search"
}

focus decides what comes first among the videos that match: the best matches ('relevance'), the most recent ('recency'), the most viewed ('popularity') or the shortest ('brevity').

Other options: use_enhanced_search (default true), start_year and end_year (only videos published in or after / in or before that year), duration (maximum length in seconds; longer videos are left out).

searchVideos() still works but is deprecated: it forwards to searchYouTube() and logs a warning.

Search your uploaded files

const fileResults = await vn.searchFiles({
  query: 'quarterly revenue discussion',
  namespace_ids: ['ns_finance'], // optional: scope to namespaces
});

for (const r of fileResults.results) {
  console.log(`${r.name} (score: ${r.relevance_score})`);
  console.log(`  Answer: ${r.query_answer}`);
  console.log(`  Namespaces: ${r.namespaces?.map((n) => n.name).join(', ')}`);
}

Files

Supported formats: mp4, webm, mov, avi, wmv, flv, mkv, m4a, mp3, mpeg, mpga, wav.

Upload and analyze

const upload = await vn.uploadFile({
  filePath: './meeting-recording.mp4',
  wait_for_completion: true,
  namespace_ids: ['ns_meetings'], // optional
});

console.log(upload.file_id);                  // "64a1b2c3d4e5f6789..."
console.log(upload.file_info?.namespace_ids); // ["ns_meetings"]

const { transcript_analysis } = await vn.analyzeFile({
  file_id: upload.file_id,
  query: 'What action items were discussed?',
});
console.log(transcript_analysis.query_answer?.answer);

Upload without waiting

Without wait_for_completion, the upload returns right away (status: 'accepted') while the file is processed. Check on it with getFile():

const { file_id } = await vn.uploadFile({ filePath: './interview.mp3' });

let { file_info } = await vn.getFile(file_id);
while (file_info.status === 'processing') {
  await new Promise((r) => setTimeout(r, 5000));
  ({ file_info } = await vn.getFile(file_id));
}

if (file_info.status === 'failed') {
  await vn.retryFileProcessing(file_id); // or cancelFileUpload(file_id) while it is still processing
}

Scenes of a file

New in 2.5.0.

What a video file shows is analyzed once and kept with the file. Ask for it at upload, or later for a file that is already there:

const { file_id } = await vn.uploadFile({ filePath: './recipe.mp4', include_scenes: true }); // at upload
// or, for an existing file:
await vn.analyzeFileScenes(file_id);

let file = await vn.getFile(file_id);
while (file.file_info.status === 'processing' || file.file_info.scenes_status === 'processing') {
  await new Promise((r) => setTimeout(r, 3000));
  file = await vn.getFile(file_id);
}

for (const scene of file.scenes ?? []) {
  console.log(scene.start, scene.description, '| on screen:', scene.on_screen_text);
}

file_info.scenes_status is 'none' (never asked for), 'processing', 'completed' or 'failed'; when it failed, file_info.scenes_error says why (an audio file has no picture: frames_not_available).

Once the scenes are there, analyzeFile and extractFileData use them with include_scenes: true. Asked on a file that has none, they throw ScenesNotAvailableError:

import { ScenesNotAvailableError } from 'vidnavigator';

try {
  await vn.analyzeFile({ file_id, query: 'What is on the label?', include_scenes: true });
} catch (error) {
  if (error instanceof ScenesNotAvailableError && error.scenes_status === 'none') {
    await vn.analyzeFileScenes(file_id); // start them, then call again once completed
  } else {
    throw error;
  }
}

The frames of a file are charged once, when its scenes are analyzed (1 credit per 2,000 frames analyzed, with at least 667 frames per hour of video). Using them afterwards adds no frame charge.

Manage files

const { transcript } = await vn.getFile(file_id, { transcript_text: true }); // full text
const { file_url } = await vn.getFileUrl(file_id);                           // signed URL to view or download
const { files, has_more } = await vn.getFiles({ status: 'completed', limit: 20, offset: 0 });
await vn.deleteFile(file_id);

Namespaces

const ns = await vn.createNamespace({ name: 'Client Calls' });

const updated = await vn.updateFileNamespaces(fileId, { namespace_ids: [ns.id!] });
console.log(updated.namespaces); // [{ id: "...", name: "Client Calls" }]

const files = await vn.getFiles({ namespace_id: ns.id! });
const all = await vn.getNamespaces();

await vn.updateNamespace(ns.id!, { name: 'Sales Calls' });
await vn.deleteNamespace(ns.id!);

Usage and billing

Per-call usage

Pass include_usage: true to getTranscript, watchVideo, analyzeVideo, analyzeFile, extractVideoData, extractFileData, searchYouTube or searchFiles to receive a usage block describing what the request cost. For background jobs, pass it in the options: vn.transcribe(url, { include_usage: true }). A failed job has all its charges reverted.

const { usage } = await vn.getTranscript({
  video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
  include_usage: true,
});

if (usage) {
  console.log(usage.total_credits);           // net credits deducted by this request
  console.log(usage.credits_remaining_after); // balance after the request (when provided)

  for (const charge of usage.charges) {
    console.log(charge.service_type, charge.quantity, charge.credits, charge.waived);
  }

  const residential = usage.charge_for('residential_request'); // matching charge or undefined
  console.log(usage.analysis_tokens?.total_tokens);            // LLM tokens (analyze / extract / search)
}

Meters: standard_request, residential_request, transcription_hour, frame_analysis, analysis_request, search_request, scene_analysis_hour. See Usage & Costs.

Account usage

const usage = await vn.getUsage();

console.log(`Credits remaining: ${usage.credits.monthly_remaining}`);
console.log(`Transcription hours used: ${usage.usage.transcriptionHour?.used}`);
console.log(`Storage: ${usage.storage.usedFormatted} / ${usage.storage.limitFormatted}`);

vn.healthCheck() returns the API status and needs no authentication.


Error handling

Every API error is mapped to a specific class, all extending VidNavigatorError:

import { AuthenticationError, NotFoundError, RateLimitExceededError, VidNavigatorError } from 'vidnavigator';

try {
  await vn.getFile('nonexistent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(error.status_code);   // 404
    console.log(error.error_message); // "File not found"
  } else if (error instanceof RateLimitExceededError) {
    console.log('Slow down! Rate limited.');
  } else if (error instanceof VidNavigatorError) {
    console.log(error.error_code, error.message);
  } else {
    throw error;
  }
}
Error classHTTPWhen
BadRequestError400Invalid parameters
AuthenticationError401Invalid or missing API key
PaymentRequiredError402Credit limit reached
InsufficientCreditsError402A job could not start: not enough credits. Extends PaymentRequiredError
AccessDeniedError403Insufficient permissions
NotFoundError404Resource does not exist, or a job's task_id is unknown or expired
StorageQuotaExceededError413Storage quota exceeded
RateLimitExceededError429Too many requests
TooManyActiveJobsError429A job could not start: too many jobs already running. Extends RateLimitExceededError
GeoRestrictedError451Content unavailable in your region
ServerError5xxUnexpected server error
SystemOverloadError503Temporary overload (has retry_after_seconds)
TaskTimeoutError-Waiting for a job took longer than timeoutMs. Has task_id; the job keeps running
WebhookSignatureError-constructWebhookEvent() got a missing, invalid or expired signature

Every error exposes status_code, error_code, error_message and details, and errors raised while waiting for a job also have task_id. See Errors for every API error code.


TypeScript models

All API responses are parsed into typed classes with static fromJSON() constructors.


What's new in 2.5.0

  • Scenes in analysis and extraction: include_scenes: true on analyzeVideo, extractVideo, analyzeFile and extractFileData uses what the video or file shows (its scenes, with the text on screen) together with the transcript. The results carry scenes and frames_analyzed.
  • Analysis as a background job: vn.analyze(), with .submit() and .resume(), for long videos.
  • Scenes of a file: uploadFile({ include_scenes: true }), analyzeFileScenes(file_id), file_info.scenes_status, and the scenes in getFile. ScenesNotAvailableError when they are asked for and not there yet.

No other changes are needed to upgrade from 2.4.0.


What's new in 2.4.0

  • Watch: vn.watch() reads what a video shows, next to what it says: a list of scenes (start, end, description, on_screen_text) and the transcript, in one result. detail sets how closely the picture is followed, include_transcript: false returns the scenes only. Runs as a background job like vn.transcribe(), with vn.watch.submit(), vn.watch.resume(task_id), watchVideo() and the watch.completed / watch.failed webhook events.

No other changes are needed to upgrade from 2.3.1.


What's new in 2.3.1

  • YouTube search: focus: 'recency' puts the most recent videos first, next to 'relevance', 'popularity' and 'brevity'. start_year and end_year bound the publication year, and duration is a maximum length in seconds.

No other changes are needed to upgrade from 2.3.0.


What's new in 2.3.0

  • TikTok LIVE room: vn.getTikTokLiveRoom() returns one room right away, by room id, streamer or LIVE URL: live or ended, viewers, new followers, the streamer's bio, and with include_comments: true its latest comments, pinned comment, intro and top viewers. Typed as TikTokLiveRoomResult / TikTokLiveRoomDetail.

No other changes are needed to upgrade from 2.2.0.

What's new in 2.2.0

  • TikTok LIVE search: vn.tiktokLiveSearch (with .submit() and .resume()), submitTikTokLiveSearch and getTikTokLiveSearch, with typed rooms (TikTokLiveRoom) and their FLV / HLS / audio-only stream URLs. Webhook events tiktok_live_search.completed / .failed.
  • country on TikTok keyword search, echoed on the task and its stats, with stats.videos_fetched (the billed count) and the items_* filter counters.

No other changes are needed to upgrade from 2.1.0.

What's new in 2.1.0

  • video_info on extraction: extractVideoData(), vn.extractVideo() and job.result() on vn.extractVideo.submit() now return the video's metadata as video_info. The task snapshot from job.refresh() / job.wait() has it too, and extract_video.completed webhook events carry it in event.data.video_info.

No other changes are needed to upgrade from 2.0.0.

Upgrading from 1.x

Transcription, structured extraction and tweet analysis now always run as background jobs, so they work on videos of any length. Existing calls keep working with the same arguments, with these differences:

  • getTweetStatement() no longer returns statement_query, which was never part of the documented API.
  • searchVideos() and getYouTubeTranscript() are deprecated in favor of searchYouTube() and getTranscript().

New in 2.0: vn.transcribe, vn.extractVideo, vn.tweetStatement, vn.tiktokProfile and vn.tiktokSearch, each with .submit() and .resume(), plus the webhook signature helpers and the InsufficientCreditsError, TooManyActiveJobsError and TaskTimeoutError classes.


Resources

npm

Package page and release history.

GitHub

Source code and issue tracker.

Python SDK

The same API for Python.

API Reference

Every endpoint, parameter and response field.

On this page