Video API & Player

Host your videos on BharatCall and play them on your own websites, with your colours and none of the clutter. Upload from your own code, control the player with JavaScript, and see which websites your plays come from.

Base URL for every API call: https:/api/v1. All requests and responses are JSON.

Quickstart

1. Open Studio › Developer and press Create API key. Pick what it may do and copy the key (it starts with bcv_ and is only shown once).
2. Check it works:

curl https:/api/v1/me \
  -H "Authorization: Bearer bcv_YOUR_KEY"

3. Add a video to your channel from a public file link:

curl -X POST https:/api/v1/videos \
  -H "Authorization: Bearer bcv_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Our new collection", "privacy": "unlisted",
       "upload": {"approach": "pull", "link": "https://example.com/video.mp4"}}'

4. Put it on your website (use the id from the answer):

<div style="position:relative;padding-top:56.25%">
  <iframe src="https:/embed/VIDEO_ID?color=e8590c" style="position:absolute;inset:0;width:100%;height:100%;border:0"
          allow="autoplay; fullscreen; picture-in-picture; encrypted-media" allowfullscreen title="Video"></iframe>
</div>

Authentication

Send your key in the Authorization header of every request: Authorization: Bearer bcv_…. Keys act as your account, so keep them on your server (never in website JavaScript or an app anyone can download). Revoke a key any time in Studio › Developer; it stops working at once.

Each key has permissions (scopes). Ask only for what your code needs:

Rate limits & errors

Each key can make 1000 requests an hour. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; after the limit you get 429 with a Retry-After header (seconds).

Errors look the same everywhere:

{ "error": "Video not found.", "error_code": 404, "documentation": "https:/developers/video-api" }

Embed a video

Every video has a player at https:/embed/VIDEO_ID. Get the code from the Share › Embed button on a video, from Studio, or from the API. The responsive version fills the width of its box:

<div style="position:relative;padding-top:56.25%">
  <iframe src="https:/embed/VIDEO_ID" style="position:absolute;inset:0;width:100%;height:100%;border:0"
          allow="autoplay; fullscreen; picture-in-picture; encrypted-media" allowfullscreen title="Video"></iframe>
</div>

Or let the Player API script build it for you:

<div data-bharat-id="VIDEO_ID" data-bharat-color="e8590c"></div>
<script src="https:/player/api.js"></script>

Player options

Add them to the embed link, e.g. /embed/VIDEO_ID?autoplay=1&muted=1&color=0f766e&t=1m30s. Use 1/0 for on/off.

Privacy & where it plays

Set these in Studio (Edit details › Privacy & embedding) or with PATCH:

oEmbed

Paste a BharatCall link into WordPress, Ghost, Notion and other oEmbed tools and they turn it into a player. To ask yourself:

GET https:/oembed?url=https:/watch/VIDEO_ID&maxwidth=800

{ "type": "video", "provider_name": "BharatCall", "title": "…", "author_name": "…",
  "width": 800, "height": 450, "duration": 120, "thumbnail_url": "…", "html": "<iframe …>" }

Options in the link (autoplay, loop, muted, color, t) are carried into the player.

Player JavaScript API

Control an embedded player from your page, and react to what viewers do. Add the script once:

<iframe id="promo" src="https:/embed/VIDEO_ID" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>
<script src="https:/player/api.js"></script>
<script>
  const player = new BharatPlayer('promo');
  player.on('play', (d) => console.log('Playing from', d.seconds));
  player.on('ended', () => showSignupForm());
  document.querySelector('#jump').onclick = () => player.setCurrentTime(95).then(() => player.play());
</script>

Or create the player in a box: new BharatPlayer('box', { id: 'VIDEO_ID', color: 'e8590c', autoplay: true, muted: true }) (any option works; responsive: false with width/height for a fixed size). Every method returns a Promise. player.ready() resolves once the player is listening.

Methods

Events

Without the script: post {method: 'play'} to the iframe's contentWindow; answers come back as {method, value, id} and events as {event, data, player_id} (send {method: 'addEventListener', value: 'timeupdate'} first).

What the player does

Your account

{ "id": "…", "name": "Upasana Jewels", "username": "upasanajewels", "link": "https:/@upasanajewels",
  "subscribers": 1200, "scopes": ["read", "upload", "edit"], "upload_quota": { "max_file_mb": 2048 } }

List your videos

{ "total": 42, "page": 1, "per_page": 25,
  "paging": { "next": "/api/v1/videos?page=2&per_page=25", "previous": null, "first": "…", "last": "…" },
  "data": [ /* video objects */ ] }

Upload a video

The video goes on the channel of the key's account. Three ways in, chosen with upload.approach:

Also accepted: name (required), description (#hashtags work), privacy, password, embed_policy, embed_domains, chapters, cta, allow_download (see Edit). New videos answer 201 with the video object; status is uploading → processing → available (or failed with upload_error).

Direct upload (approach "post")

Three steps: create the video, send the file to upload.upload_link as a form with every upload.form_fields entry plus the file in the field named file, then call complete.

import os, requests
API, KEY = "https:/api/v1", "bcv_YOUR_KEY"
H = {"Authorization": f"Bearer {KEY}"}
path = "launch.mp4"
v = requests.post(f"{API}/videos", headers=H, json={
    "name": "Launch film", "privacy": "hidden", "embed_policy": "domains", "embed_domains": ["mysite.com"],
    "upload": {"approach": "post", "size": os.path.getsize(path), "type": "video/mp4", "filename": path}}).json()
up = v["upload"]
with open(path, "rb") as f:
    requests.post(up["upload_link"], data=up["form_fields"], files={"file": f}).raise_for_status()
done = requests.post(f"{API}/videos/{v['id']}/complete", headers=H).json()
print(done["status"], done["player_embed_url"])

import fs from 'node:fs';
const API = 'https:/api/v1', H = { Authorization: 'Bearer bcv_YOUR_KEY', 'Content-Type': 'application/json' };
const file = fs.readFileSync('launch.mp4');
const v = await (await fetch(`${API}/videos`, { method: 'POST', headers: H, body: JSON.stringify({
  name: 'Launch film', upload: { approach: 'post', size: file.length, type: 'video/mp4', filename: 'launch.mp4' } }) })).json();
const form = new FormData();
Object.entries(v.upload.form_fields).forEach(([k, val]) => form.append(k, val));
form.append('file', new Blob([file], { type: 'video/mp4' }), 'launch.mp4');
await fetch(v.upload.upload_link, { method: 'POST', body: form });
const done = await (await fetch(`${API}/videos/${v.id}/complete`, { method: 'POST', headers: H })).json();
console.log(done.status, done.player_embed_url);

# 1. create (the answer has upload.upload_link and upload.form_fields)
curl -X POST https:/api/v1/videos -H "Authorization: Bearer bcv_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Launch film","upload":{"approach":"post","size":5242880,"type":"video/mp4","filename":"launch.mp4"}}'
# 2. send the file: one -F per form_fields entry, then the file last
curl -X POST "UPLOAD_LINK" -F "key=…" -F "Content-Type=video/mp4" -F "policy=…" … -F "[email protected]"
# 3. finish
curl -X POST https:/api/v1/videos/VIDEO_ID/complete -H "Authorization: Bearer bcv_YOUR_KEY"

Call after the file is sent. Optional body: {"duration": 125.4} (seconds; we also work it out ourselves). The video becomes available; quality versions, seek previews and subscriber notifications (public videos only) follow by themselves.

From a link (approach "pull" or "link")

{ "name": "Showroom tour", "upload": { "approach": "pull", "link": "https://player.vimeo.com/progressive_redirect/…/file.mp4" } }
{ "name": "Our YouTube trailer", "upload": { "approach": "link", "link": "https://youtu.be/VIDEO" } }

Poll GET /videos/{id} until status is available. Pull links must be public http(s) addresses that answer with a video file.

Get a video

The full video object, including download links for each quality, subtitles, chapters and the embed code.

Edit a video

Send only what changes:

curl -X PATCH https:/api/v1/videos/VIDEO_ID -H "Authorization: Bearer bcv_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"privacy":"hidden","embed_policy":"domains","embed_domains":["mysite.com"],"cta":{"text":"Shop now","url":"https://mysite.com/shop","at":20}}'

Delete a video

Answers 204. The video, its quality versions and subtitles are removed; embeds show "Video not available".

Stats

{ "plays": 1820, "likes": 64, "comments": 9, "saves": 12, "watch_time_minutes": 2150.5, "average_watch_seconds": 71.2,
  "embeds": [ { "domain": "mysite.com", "plays": 1210 }, { "domain": "direct", "plays": 33 } ] }

embeds covers the last 90 days.

Subtitles

Body: {"language": "hi", "text": "<the .srt or .vtt file's text>", "name": "Hindi"} (name is optional). Adding a language that exists replaces it.

Embed code

Any player option in the query is built into the code. Answers {"url", "html", "html_fixed"} (responsive and 640×360).

The video object

Moving from Vimeo

1. In Vimeo, open each video's download options (or use Vimeo's API files / download links) to get a direct file link.
2. Create the video here with "upload": {"approach": "pull", "link": "…"}, keeping your privacy: Vimeo "Hide from Vimeo" = hidden, "Unlisted" = unlisted, "Only sites I choose" = embed_policy: "domains".
3. Replace https://player.vimeo.com/video/ID in your website with https:/embed/NEW_ID. Most Vimeo options use the same names here: autoplay, muted, loop, background, controls, color, title, byline, portrait, dnt, speed, texttrack, quality, autopause, keyboard, pip, #t= → t=.
4. Replace Vimeo's player.js with https:/player/api.js and new Vimeo.Player(el) with new BharatPlayer(el). Method and event names match Vimeo's where they exist (play, getCurrentTime, on('timeupdate')…).

Subtitle & audio languages

Questions or a feature you need? Contact support. This is version 1 of the API; we only add to it, so your code keeps working.