Skip to main content

Node.js SDK

The official Vidiking Node.js SDK provides a typed client for all API endpoints.

Installation​

npm install @vidiai/sdk

Setup​

import Vidiai from '@vidiai/sdk';

const client = new Vidiai({
  apiKey: process.env.VIDIKING_API_KEY,
  sandbox: false, // Set to true for sandbox mode
});

Video Rendering​

Render​

const { jobId } = await client.render({
  timeline: {
    background: '#000000',
    tracks: [
      {
        clips: [
          {
            asset: { type: 'title', text: 'Hello World', style: 'minimal', size: 'large' },
            start: 0,
            length: 5,
          },
        ],
      },
    ],
  },
  output: { format: 'mp4', resolution: 'hd' },
});

Get Render Status​

const job = await client.getRender(jobId);
console.log(job.status); // QUEUED | PROCESSING | COMPLETE | FAILED
console.log(job.url);    // Available when COMPLETE

Poll Until Complete​

const job = await client.pollJob(jobId, {
  interval: 3000,  // Check every 3 seconds (default)
  timeout: 300000, // Timeout after 5 minutes (default)
});

console.log('Output:', job.url);

List Renders​

const renders = await client.listRenders({
  limit: 20,
  status: 'COMPLETE',
  offset: 0,
});

Stitch​

const { jobId } = await client.stitch({
  clips: [
    { src: 'https://example.com/intro.mp4' },
    { src: 'https://example.com/main.mp4', trim: 5, length: 30 },
    { src: 'https://example.com/outro.mp4' },
  ],
  output: { format: 'mp4', resolution: 'hd' },
});

Trim​

const { jobId } = await client.trim({
  src: 'https://example.com/video.mp4',
  start: 10,
  length: 20,
  output: { format: 'mp4', resolution: 'hd' },
});

Upscale​

const { jobId } = await client.upscale({
  src: 'https://cdn.vidiking.com/renders/job_abc123.mp4',
  output: { format: 'mp4', quality: 'high' },
});

AI Features​

Image Generation​

const image = await client.ai.generateImage({
  prompt: 'A mountain landscape at sunset',
  model: 'flux',        // flux | dall-e-3 | stable-diffusion
  width: 1920,
  height: 1080,
});

console.log(image.url);

Video Generation​

const result = await client.ai.generateVideo({
  prompt: 'Aerial shot of ocean waves crashing on rocks',
  model: 'runway-gen4-turbo',
  duration: 5,
  aspectRatio: '16:9',
});

const job = await client.pollJob(result.jobId);
console.log(job.url);

Voiceover​

const voiceover = await client.ai.generateVoiceover({
  text: 'Welcome to our product tour.',
  model: 'elevenlabs-flash',
  voice: 'rachel',
  language: 'en',
  speed: 1.0,
});

console.log(voiceover.url, voiceover.duration);

Subtitles​

const result = await client.ai.generateSubtitles({
  src: 'https://example.com/video.mp4',
  language: 'en',
  burnIn: true,
  style: { fontSize: 36, color: '#ffffff', background: 'rgba(0,0,0,0.7)' },
});

const job = await client.pollJob(result.jobId);
console.log(job.url); // Video with burned-in subtitles

Script Generation​

const script = await client.ai.generateScript({
  topic: 'Product launch announcement',
  tone: 'energetic',
  format: 'ad',
  duration: 30,
});

console.log(script.text);

Templates​

List Templates​

const templates = await client.templates.list({
  category: 'marketing',
});

Render Template​

const { jobId } = await client.templates.render('tpl_promo_001', {
  mergeFields: {
    headline: 'Big Sale',
    product_image: 'https://example.com/product.png',
  },
  output: { format: 'mp4', resolution: 'hd' },
});

Create Template​

const template = await client.templates.create({
  name: 'My Template',
  mergeFields: [
    { name: 'title', type: 'text', default: 'Hello' },
    { name: 'image', type: 'image_url', required: true },
  ],
  timeline: { /* ... */ },
  visibility: 'private',
});

Wallet​

const wallet = await client.getWallet();
console.log(`Balance: ${wallet.balance}, Available: ${wallet.available}`);

const transactions = await client.getTransactions({ limit: 10 });

Error Handling​

import { VidikingError, InsufficientFundsError, RateLimitError } from '@vidiai/sdk';

try {
  await client.render({ /* ... */ });
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.error('Not enough balance:', error.balance);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
  } else if (error instanceof VidikingError) {
    console.error('API error:', error.code, error.message);
  }
}

TypeScript Support​

The SDK is written in TypeScript and includes full type definitions. All request and response types are exported.

import Vidiai, {
  RenderRequest,
  RenderResponse,
  TimelineTrack,
  OutputOptions,
} from '@vidiai/sdk';

const timeline: RenderRequest = {
  timeline: {
    tracks: [] as TimelineTrack[],
  },
  output: { format: 'mp4', resolution: 'hd' } as OutputOptions,
};

Configuration Options​

const client = new Vidiai({
  apiKey: 'your_api_key',     // Required
  sandbox: false,              // Use sandbox mode (default: false)
  baseUrl: 'https://api.vidiking.com', // Custom base URL
  timeout: 30000,             // Request timeout in ms (default: 30000)
  retries: 3,                 // Auto-retry on 5xx errors (default: 3)
});