SDKs

The SDKs wrap the server API: they set the AccessKey header, retry rate-limited and failed requests, raise typed errors, and verify webhook signatures. Everything they do is also possible with plain HTTP.

InstallCopy Anchor Link

npm install @octavideo/node

Create a clientCopy Anchor Link

Create one client per library, with that library's private key from your server's environment:

import { OctaVideo } from '@octavideo/node';

const octa = new OctaVideo({ accessKey: process.env.OCTAVIDEO_KEY });

Issue a playback OTPCopy Anchor Link

The most common call: one OTP for each viewer on each page view. See Secure playback.

const { otp, embedUrl } = await octa.playback.createOtp({
  videoId: '6f1c2b9e-4a7d-4f3e-9b8a-2d5c7e1f0a34',
  userId: user.id,
  ttlSeconds: 300,
});

Upload and manage videosCopy Anchor Link

import { openAsBlob } from 'node:fs';

const video = await octa.videos.upload({
  title: 'Lesson 1: Introduction',
  file: await openAsBlob('lesson-01.mp4'),
});

const page = await octa.videos.list({ perPage: 100 });
for await (const v of octa.videos.listAll()) console.log(v.id, v.encodingStatus);

Every endpoint in the API reference has a matching method: videos.import, videos.get, videos.updateDetails, videos.setChapters, videos.transcribe, videos.thumbnails, collections.create and collections.addVideos (in PHP and Python, the same names in snake_case).

ErrorsCopy Anchor Link

A failed call throws (Node.js, PHP) or raises (Python) an OctaVideoError with the API's code (errorCode in PHP, where code is taken by Exception), the HTTP status and the requestId. See Errors.

import { OctaVideoError } from '@octavideo/node';

try {
  await octa.playback.createOtp({ videoId });
} catch (err) {
  if (err instanceof OctaVideoError && err.code === 'video_not_ready') {
    // Show "processing" to the viewer and try again later.
  } else {
    throw err;
  }
}

The SDKs retry 429 (after Retry-After) and 5xx responses up to 3 times by default. Set maxRetries (max_retries in PHP and Python) when you create the client to change it.

Verify webhooksCopy Anchor Link

const event = octa.webhooks.verify(rawBody, req.get('OctaVideo-Signature'), process.env.OCTAVIDEO_WEBHOOK_SECRET);

verify checks the signature and the timestamp, and returns the parsed event, or throws when either check fails. See Webhooks.