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 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.0Requirements: 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
| Option | Default | Description |
|---|---|---|
apiKey | (required) | Your VidNavigator API key |
baseURL | https://api.vidnavigator.com/v1 | API base URL |
axiosConfig | Passed 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
| Platform | Transcript (captions) | Transcribe (speech-to-text) | Watch (scenes) | Carousel |
|---|---|---|---|---|
| YouTube | Yes | - | Yes | - |
| Instagram Reels | - | Yes | Yes | Yes |
| Instagram Posts | - | Yes | Yes | Yes (all_videos) |
| TikTok | Yes | Yes | Yes | - |
| X / Twitter | Yes | Yes | Yes | - |
| Vimeo | Yes | Yes | Yes | - |
| Yes | Yes | Yes | - | |
| Dailymotion | Yes | Yes | Yes | - |
| Loom | Yes | Yes | Yes | - |
| Snapchat | Yes, when Snapchat has a transcript | Yes | Yes | Yes (highlights: img_index, all_videos) |
| Uploaded files | Yes | Yes | - | - |
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 ICommon 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 analyzedThe 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:
| Option | Type | Description |
|---|---|---|
video_url | string | URL of the video (?img_index=N selects one video of an Instagram carousel or a Snapchat highlight) |
detail | string | How 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_transcript | boolean | Default true. false returns the scenes only (the result has no transcript) |
transcript_text | boolean | Return the transcript as a single string instead of segments |
webhook_url | string | Optional; 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, latervn.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 itvn.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); // 2extractVideoData() 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 musicvn.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 anySee 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:
| Operation | Wait for the result | Start it and come back later |
|---|---|---|
| Transcription | await vn.transcribe(url) | await vn.transcribe.submit(url) |
| Watch (scenes and transcript) | await vn.watch(url) | await vn.watch.submit(url) |
| Structured extraction | await vn.extractVideo({ video_url, schema }) | await vn.extractVideo.submit({ ... }) |
| Tweet claim analysis | await vn.tweetStatement(tweetId) | await vn.tweetStatement.submit(tweetId) |
| TikTok profile scrape | await vn.tiktokProfile(profileUrl) | await vn.tiktokProfile.submit(profileUrl) |
| TikTok keyword search | await vn.tiktokSearch(query) | await vn.tiktokSearch.submit(query) |
| TikTok LIVE search | await 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;
}
}Pass these to the one-liner or to result() / wait():
| Option | Default | Description |
|---|---|---|
timeoutMs | 30 minutes | Stop waiting and throw TaskTimeoutError (with task_id). 0 waits forever |
intervalMs | 3000 | Time between checks. Checking costs no credits and is not rate-limited |
fastStart | true | Check every second for the first 10 seconds, so short clips return quickly |
signal | An AbortSignal to stop waiting early (the job keeps running) | |
onPoll | Called with each task snapshot, e.g. for progress logs | |
include_usage | false | Attach a usage block to the result (one-liner, .submit() and .resume() options) |
| Member | Description |
|---|---|
.submit(input, { include_usage? }) | Start the job and return a Job immediately |
.resume(task_id, { include_usage? }) | Get a Job for a job you already started (no request is made) |
job.task_id, job.job_type, job.check_status_url, job.webhook_url | Job details from the submit response |
job.status() | Check once; returns 'processing', 'completed' or 'failed' |
job.refresh() | Check once; returns the full task (error, webhook, timestamps, ...) |
job.result(options?) | Wait until finished and return the result. Throws on failure or timeout; every error carries task_id |
job.wait(options?) | Wait until finished and return the final task, without throwing on failure |
transcribe → same shape as transcribeVideo(); watch → WatchResult (video_info, transcript, scenes, frames_analyzed, usage?); extractVideo → { data, video_info, usage?, schema? }; tweetStatement → TweetStatement; tiktokProfile / tiktokSearch / tiktokLiveSearch → the completed task with every page of videos / results.
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 nullVerify 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.resultholds 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.completedevents,event.data.video_infoholds the raw video metadata. It is sent even when the result was truncated. verifyWebhookSignature(rawBody, signatureHeader, secret)returnstrueorfalseinstead of throwing.- Deliveries older than 5 minutes are rejected by default. Change this with
{ toleranceSeconds };0turns the check off. (await job.refresh()).webhookshows 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 DateOptions: 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.
Keyword search
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. Withoutpublished_within, anafter_datetimemore than 24 hours ago picks the smallest window that covers it. parallel_search_slices(2to4) 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.countrypicks whose TikTok results you get ('fr','de','jp', ..., default'gb';'us'is refused). Billing: 1residential_requestper 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 withgetTikTokSearch(task_id, { cursor, limit }).
See the Searching TikTok guide.
LIVE search
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) hasid,url,authorandstatslike a keyword result, plusstarted_at(aDate),stats.viewers/stats.total_viewers,hashtags(the title's#tags),category(e.g.'Gaming') andgame_tags. stream_urlsholdsflvandhlsURLs keyed by quality (origin,uhd,hd,sd,ld),default_quality,audio_onlyandexpires_at. The URLs play while the LIVE is on. They are returned by default;include_stream_urls: falseleaves them out. Not every LIVE offers HLS.countrydefaults to'us';max_resultscaps the rooms (TikTok serves about 50 per keyword). Billing: 1residential_requestper 30 rooms returned (task.stats.results_count), minimum 1.- Lower level:
submitTikTokLiveSearch(payload)andgetTikTokLiveSearch(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_idis a string (room ids have more digits than a JavaScript number holds);usernameis the streamer, with or without@(their current LIVE, or their last one when offline);urlishttps://www.tiktok.com/@username/live, the profile URL, or a room'sshare_url. Options:include_comments(defaultfalse),comments_limit(1-50),include_stream_urls(defaulttrue),include_usage.- The room (
TikTokLiveRoomDetail) has the LIVE search room fields plusstatus('live'/'ended', alsoroom.isLive),ended_at,stats.new_followers,author.bio,author.following,share_url,chat_enabled,subscribers_only,age_restrictedandproducts. No likes, comment count or share count: LIVE search returns those. - With
include_comments: truethe result also hascomments(newest first; TikTok keeps only about the last 50),pinned_comment,introandtop_viewers. - A room or account that does not exist throws
NotFoundError(error_code'live_not_found'). A shorteraxiosConfig.timeoutis raised to two minutes for this call. Billing: 1residential_request, 2 withinclude_comments(1 when the room has ended); not billed when the room is not found. See TikTok LIVE Room.
Search
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 class | HTTP | When |
|---|---|---|
BadRequestError | 400 | Invalid parameters |
AuthenticationError | 401 | Invalid or missing API key |
PaymentRequiredError | 402 | Credit limit reached |
InsufficientCreditsError | 402 | A job could not start: not enough credits. Extends PaymentRequiredError |
AccessDeniedError | 403 | Insufficient permissions |
NotFoundError | 404 | Resource does not exist, or a job's task_id is unknown or expired |
StorageQuotaExceededError | 413 | Storage quota exceeded |
RateLimitExceededError | 429 | Too many requests |
TooManyActiveJobsError | 429 | A job could not start: too many jobs already running. Extends RateLimitExceededError |
GeoRestrictedError | 451 | Content unavailable in your region |
ServerError | 5xx | Unexpected server error |
SystemOverloadError | 503 | Temporary 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.
| Class | Description |
|---|---|
VideoInfo | Video metadata: title, channel, duration, views, likes, published date, keywords, carousel info |
FileInfo | Uploaded file: name, size, type, duration, status, namespace_ids, namespaces |
TranscriptSegment | Timed segment: text, start, end (seconds) |
AnalysisResult | AI analysis: summary, people, places, key subjects, query answer |
CarouselInfo | Carousel summary: total items, video/image count, transcribed count, total duration |
CarouselVideoResult | Per-video result in a carousel: index, status, video info, transcript |
WatchResult | A watched video, from watch(): video_info, transcript (left out with include_transcript: false), transcript_error, scenes, frames_analyzed, usage |
VideoScene | What a video shows between start and end (seconds): description, on_screen_text |
TweetStatement | Structured X/Twitter claim analysis, topics, entities, tone, intent and source text |
| Class | Description |
|---|---|
VideoSearchResult | Extends VideoInfo with relevance_score, transcript_summary and search metadata |
FileSearchResult | Extends FileInfo with relevance_score, query_answer, timestamps and a signed URL |
Namespace | Full namespace: id, name, created/updated timestamps |
NamespaceRef | Lightweight { id, name } reference embedded in file and search responses |
| Class | Description |
|---|---|
Job | Handle returned by .submit() / .resume(): task_id, status(), refresh(), result(), wait() |
AsyncJob<T> | Task snapshot of a transcription, watch, extraction or tweet job: task_status, result, video_info (extraction jobs), error, webhook, request, timestamps |
TikTokProfileTask | Profile scrape task: status, profile metadata, videos, pagination, download_url, error, webhook |
TikTokVideo | Public TikTok video metadata, with published_at as a Date and integer counters |
TikTokSearchTask | Keyword search task: status, results, pagination, download_url; stats shows the sort_by / published_within used |
TikTokSearchResult | Normalized keyword result, with published_at as a Date and integer counters |
TikTokLiveSearchTask | LIVE search task: status, rooms, pagination, download_url, error, webhook; stats.results_count is what is billed |
TikTokLiveRoom | A LIVE room: author, stats.viewers, hashtags, category, game_tags, started_at as a Date, stream_urls (FLV / HLS by quality, audio only) |
| Class | Description |
|---|---|
UsageData | Account usage from getUsage(): credits, per-service activity, storage, subscription |
UsageBlock | Per-call usage: charges[], total_credits, credits_remaining_after, waived, plus charge_for() and analysis_tokens |
UsageCharge | One meter charge: service_type, quantity, credits, waived, credits_saved, and tokens on analysis_request |
What's new in 2.5.0
- Scenes in analysis and extraction:
include_scenes: trueonanalyzeVideo,extractVideo,analyzeFileandextractFileDatauses what the video or file shows (its scenes, with the text on screen) together with the transcript. The results carryscenesandframes_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 ingetFile.ScenesNotAvailableErrorwhen 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.detailsets how closely the picture is followed,include_transcript: falsereturns the scenes only. Runs as a background job likevn.transcribe(), withvn.watch.submit(),vn.watch.resume(task_id),watchVideo()and thewatch.completed/watch.failedwebhook 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_yearandend_yearbound the publication year, anddurationis 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 withinclude_comments: trueits latest comments, pinned comment, intro and top viewers. Typed asTikTokLiveRoomResult/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()),submitTikTokLiveSearchandgetTikTokLiveSearch, with typed rooms (TikTokLiveRoom) and their FLV / HLS / audio-only stream URLs. Webhook eventstiktok_live_search.completed/.failed. countryon TikTok keyword search, echoed on the task and itsstats, withstats.videos_fetched(the billed count) and theitems_*filter counters.
No other changes are needed to upgrade from 2.1.0.
What's new in 2.1.0
video_infoon extraction:extractVideoData(),vn.extractVideo()andjob.result()onvn.extractVideo.submit()now return the video's metadata asvideo_info. The task snapshot fromjob.refresh()/job.wait()has it too, andextract_video.completedwebhook events carry it inevent.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 returnsstatement_query, which was never part of the documented API.searchVideos()andgetYouTubeTranscript()are deprecated in favor ofsearchYouTube()andgetTranscript().
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.