Getting started with hyperserve

Welcome to Hyperserve! We're excited to help you easily serve video to your users.

Step 1: Obtain your api key

To use our API, you first need an API key. You can get one by signing up to our dashboard and creating a new API key.

warning

We will only show you your API key one time just after creating it, make sure you save it privately and do not store it in version control.

Step 2: Install the SDK

npm install hyperserve-sdk

Then initialize the client on your server (never expose your API key to the browser):

import { HyperserveClient } from 'hyperserve-sdk';

const client = new HyperserveClient({ apiKey: process.env.HYPERSERVE_API_KEY });

Step 3: Upload your first video

Uploading a video is a three-step process: create the video record on the backend, upload the file directly to storage from the client, then confirm the upload is complete from the backend.

Step 3a: Create the video record

Call createVideo() on your server. It returns a presigned upload URL so the client can upload directly to storage without ever seeing your API key.

SDK

// On your server
const { id, uploadUrl, contentType } = await client.createVideo({
  filename: 'my-video.mp4',
  fileSizeBytes: videoFile.size,
  resolutions: ['480p', '1080p'],
  isPublic: true,
});

Raw HTTP

const createResponse = await fetch(`https://dev.api.hyperserve.io/api/video`, {
method: 'POST',
headers: {
  'X-API-KEY': YOUR_HYPERSERVE_API_KEY,
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  filename: 'my-video.mp4',
  fileSizeBytes: videoFile.size,
  resolutions: ['480p', '1080p'],
  isPublic: true,
}),
});

const { id, uploadUrl, contentType } = await createResponse.json();

tip

See the Create Video API for more detailed information

Step 3b: Upload the file directly to storage

The client uploads the file directly to storage using the presigned URL. No API key is needed — it never touches your server.

SDK

// In the browser
import { putVideoToStorage } from 'hyperserve-sdk/browser';

await putVideoToStorage({
  uploadUrl,
  contentType,
  file: videoFile,
  onProgress: (percent) => console.log(`${percent}% uploaded`),
});

Raw HTTP

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': contentType },
  body: videoFile,
});

Step 3c: Confirm the upload

Once the file is uploaded, notify the API from your server so it can verify the file and start transcoding.

SDK

// On your server
await client.completeUpload(id);

Raw HTTP

await fetch(`https://dev.api.hyperserve.io/api/video/${id}/complete-upload`, {
method: 'POST',
headers: { 'X-API-KEY': YOUR_HYPERSERVE_API_KEY },
});

tip

See the Complete Upload API for more detailed information

Step 4: Wait for processing to complete

Videos usually take seconds to process, but larger videos can take some time. You'll have to wait for the video to complete processing before you can access the urls to view the hosted videos. You can check if the video is ready by viewing the status on the GET public/private video api responses. We can also notify your application automatically with webhooks, see our webhook guide for more information.

Step 5: Retrieve your video at runtime

After your video has been uploaded and you've confirmed video processing is complete, you can retrieve the video at runtime using another API call:

Public video

info

If you setup webhooks, you can save your public video url(s) when receiving the processing complete webhook, and you could skip this step.

SDK

const video = await client.getVideo(YOUR_HYPERSERVE_VIDEO_ID);
const videoUrl = video.resolutions['480p']?.videoUrl;

Raw HTTP

const response = await fetch(`https://dev.api.hyperserve.io/api/video/${YOUR_HYPERSERVE_VIDEO_ID}/public`, {
method: 'GET',
headers: { 'X-API-KEY': YOUR_HYPERSERVE_API_KEY },
});
const data = await response.json();
const videoUrl = data.resolutions['480p']?.video_url;

tip

See the Get Public Video API for more detailed information

Private video

info

Private video requires retrieving signed url(s) at runtime with a specific expiration time

SDK

const video = await client.getVideo(YOUR_HYPERSERVE_VIDEO_ID, {
  private: true,
  expirationSeconds: 3600,
});
const videoUrl = video.resolutions['480p']?.videoUrl;

Raw HTTP

const EXPIRATION_SECONDS = 3600;
const response = await fetch(`https://dev.api.hyperserve.io/api/video/${YOUR_HYPERSERVE_VIDEO_ID}/private/${EXPIRATION_SECONDS}`, {
method: 'GET',
headers: { 'X-API-KEY': YOUR_HYPERSERVE_API_KEY },
});
const data = await response.json();
const videoUrl = data.resolutions['480p']?.video_url;

tip

See the Get Private Video API for more detailed information

That's it! You're now ready to start using our Hyperserve. If you have any questions, feel free to reach out to our support team.