Concepts

This page defines the handful of ideas that everything in Videohati is built on. Each one is explained in plain words first, followed by a short note on where it shows up in the API. You can read it top to bottom, or jump to the term you need.

Account

An account is your organization's identity on Videohati. It is what you sign in to, and it owns your billing and your projects. One account can hold many projects — for example, one per website or app you run.

In the dashboard: you sign in to your account at app.videohati.com, which owns your projects and billing.

Project

A project is a workspace inside your account that holds a group of videos along with its own API keys and settings. Keeping videos in separate projects keeps their keys, usage, and access separate too. Most teams use one project per site or app.

In the dashboard: create and manage projects at app.videohati.com. Every video and key belongs to exactly one project.

API key

An API key is the secret your code uses to prove it may act on a project. Because it is a secret, it belongs only on your server, never in a browser or a mobile app.

Keys come in two modes and can carry different permissions:

• Test keys start with vh_test_ and act on test data, kept separate from your real content. Live keys start with vh_live_ and act on your real content. The prefix alone decides the mode.
• A key carries read access, write access, or both. Give each key only the access it needs.
• A key's full value is shown only once, when you create it. Copy it then and store it safely.
• If a key is ever exposed, rotate it: rotating issues a new secret and retires the old one, so the leaked value stops working.

In the dashboard: create, rotate, and revoke keys at app.videohati.com.

Video and its states

A video is a single piece of content you have uploaded. From upload to playable, a video moves through a series of states. In these docs we use processing as the friendly umbrella for the work that happens between a finished upload and a ready video, but the API reports finer-grained states so your app can react precisely.

The states the API can report are:

The path most videos follow is uploading → uploaded → encoding → ready. A video that cannot be processed ends at failed instead, with a reason attached.

In the API: read a video's state with videos.get, or wait for it to reach ready with videos.waitForState. See the Node SDK.

Playback session

A playback session is a short-lived permission slip that lets one viewer watch one video. Your server creates a session when a viewer is about to watch, and it hands the viewer a session token and a temporary link — never the API key.

Sessions are short-lived on purpose. The link a viewer receives expires after a short window, so it cannot be copied and reused later or passed around to people who should not have access. When it expires, your app simply creates a new one.

In the API: create a session with playback.createSession on your server; the player keeps it alive while the viewer watches.

Webhook

A webhook is a message Videohati sends to your server when something happens — for example, when a video finishes processing. Instead of your app repeatedly asking "is it ready yet?", Videohati tells you the moment it is. You register a URL, and Videohati posts a signed message to it for each event.

The eight event types are:

Every delivery is signed, so your server can confirm it genuinely came from Videohati before acting on it.

In the API: register endpoints with webhooks.register, and confirm each message with webhooks.verify (or verifyWebhookSignature). See the Node SDK and Laravel SDK.

Watermark and viewer text

A watermark overlays a viewer's identity — their email or an ID you choose — on top of the video while it plays. It does not stop someone from recording the screen, but it makes any leaked copy traceable back to the account it came from. This is a deterrent, not a lock.

In the API: set the overlay text when you create a session, with the viewerDisplayText option on playback.createSession.