Quickstart

This guide takes you from nothing to a video playing on your own page. Every step runs in test mode, so you can follow along safely without touching real content. It should take about ten minutes.

Prerequisites

• A Videohati account. Sign up at the dashboard and confirm your email. New accounts go through a short review before they are approved.
• One of the following to make requests:
  • Node.js 18 or newer, if you want to use the official SDK, or
  • curl, if you prefer to call the API directly from a terminal.

1. Create a project

A project is a workspace that holds a group of videos and its own API keys. Most teams use one project per site or app.

In the dashboard, create your first project — for example, Course videos. You will point your keys and uploads at this project from here on.

Get an API key

An API key is the secret your code uses to prove it may act on your project. Create one before you make any request.

In your project, open API keys and create a key in test mode. The full key is shown only once, so copy it immediately and store it as a secret.

• A test key looks like vh_test_... and works on test data — the same API, kept separate from your live content.
• A live key looks like vh_live_... and acts on your real content. Use live keys only later, once you are ready.

Export your test key so the examples below can read it:

export VIDEOHATI_API_KEY="vh_test_your_key_here"

2. Make your first request

The quickest way to confirm your key works is to list the videos in your project. A brand-new project returns an empty list — that empty result is the success you are looking for.

Every endpoint lives under https://api.videohati.com/v1 and authenticates with your key sent as a bearer token.

curl https://api.videohati.com/v1/videos \
  -H "Authorization: Bearer $VIDEOHATI_API_KEY"

{
  "data": [],
  "nextCursor": null
}

npm install @videohati/node

import { Videohati } from "@videohati/node";

const client = new Videohati({ apiKey: process.env.VIDEOHATI_API_KEY });

const { data } = await client.videos.list();
console.log(`This project has ${data.length} video(s).`);

3. Upload your first video

Uploading a video is a single call. videos.upload() creates the video, sends the file in small parts to the upload endpoint, and finishes the upload for you. The onProgress callback lets you follow along.

const video = await client.videos.upload("./lecture-01.mp4", {
  onProgress: ({ partsCompleted, totalParts }) => {
    console.log(`Uploaded part ${partsCompleted}/${totalParts}`);
  },
});

console.log(video.videoId); // 01JZ9WV3N8GQ5T2M7K4C6XBARH

After the upload, Videohati processes the file into several quality levels. Wait until it is ready before you try to play it:

const ready = await client.videos.waitForState(video.videoId, {
  targetStates: ["ready", "failed"],
});

if (ready.state === "failed") {
  throw new Error("This video could not be processed.");
}

console.log("Video is ready to play.");

4. Play it

To show a video, your server first creates a playback session — a short-lived permission slip for one viewer to watch one video. Create it on the server and hand only the session token (never your API key) to the page.

const session = await client.playback.createSession({
  videoId: ready.id,
  viewerDisplayText: "[email protected]", // optional: shown over the video
});

console.log(session.sessionToken); // pass this to the player

Then embed the player on your page. The framework-free player reads what it needs from data- attributes:

<script src="https://cdn.videohati.com/player.js" async></script>
<div
  data-videohati-video-id="01JZ9WV3N8GQ5T2M7K4C6XBARH"
  data-videohati-project-id="01JZ9WV3N8GQ5T2M7K4C6XBARP"
  data-videohati-session-token="01JZ9WV3N8GQ5T2M7K4C6XBARK.1781485200.bXktbWFj"
></div>

That is the whole loop: upload, wait for ready, create a session, embed the player. Your first video is now playing.

Where next