Skip to main content
All CollectionsPlatform Features
The Videolinq API
The Videolinq API

Add real-time captions or streaming to your platform - save time, cut costs, customize easily, and track usage for accurate billing.

Updated this week

Introduction

The Videolinq API version 4.0 (Beta) is exclusively available to Enterprise plan subscribers, providing a robust programmatic interface for seamless remote management of Videolinq accounts. With this API, developers can:

  • Manage their Videolinq account.

  • Create and manage sub-users.

  • Create and manage channels.

  • Create video sources and target destinations.

  • Add captions or subtitles to live streams or recorded media.

  • Schedule content, manage playlists, and customize players.

  • Create and manage Studio projects.

  • Retrieve usage data and statistics.

The API operates on JSON POST requests and responds with JSON-formatted data.

API Compatibility

The Videolinq API is designed to be language agnostic, making it compatible with any programming language that can send HTTP POST requests and parse JSON data. This document is a comprehensive reference guide for API developers, outlining the available operations and how to implement them.

Resource Management

Videolinq accounts with API access have a shared "bucket" of resources, which includes:

  • Media channels

  • Video sources

  • Target destinations

  • Output hours

  • Data transfer

  • Storage space

  • Media Players and Studio Projects

Accounts with API access can create sub-users, sources, channels, destinations, schedulers, players, and studio projects according to the volume allocated to their account "bucket." The API enables account administrators and their sub-users to choose a specific region or country for deploying media servers, GenAI captioning, and data storage, ensuring compliance with emerging country-specific AI sovereignty regulations. Human-generated closed captioning is offered as a complimentary pass-through service. However, usage-based billing applies for output hours, data transfer, and storage space, while automated captioning is billed at an hourly rate. Refer to the rate sheet attached to your account agreement for detailed pricing.

When assigning channels and destinations to sub-users, these resources are deducted from the master account's pool. Developers use the API to allocate and limit channels, destinations, hours, and data for each sub-user, who operates within their own "plan." Developers are responsible for charges from sub-users who use automated captions, tracked via a sub-user ID for billing. Videolinq works directly with the developer as they manage the billing of their sub-users.

Example of a sub-user usage query:

{
  "publicId": "string",
  "asrBillableHours": 0,
  "billableHours": 0,
  "bytesTransfer": 0,
  "liveAsrBillableHours": 0,
  "reachedAsrBillableHoursLimit": true,
  "reachedBillableHoursLimit": true,
  "reachedBytesTransferLimit": true,
  "vodAsrBillableHours": 0
}

What The API Does

The following features are managed by the Videolinq API and apply to both the Account/Sub-user:

  1. User (Enterprise account administrator)/Login to the media dashboard.

  2. User/Create, edit, or delete a new sub-user.

  3. User/See list of sub-users and control status (active, suspended, delete).

  4. User/See a list of sub-User active streams and allow embed (iFrame) monitor players.

  5. Source/Create, edit, and delete a video source (webcam/RTMP/RTMP or SRT streams/file).

  6. Source/Select target region (access to the Enterprise regional selection lists).

  7. Source/Upload, rename, edit or delete a video file.

  8. Source/Create, Edit, manage, and delete playlists.

  9. Source/Captions: Create caption/translation job(s) and see task progress alerts.

  10. Source/Captions: Open EDIT and manage UI features.

  11. Source/Captions: Access saved caption jobs, including UI features (edit/delete records).

  12. Channel/Create, edit or delete a Channel.

  13. Channel/Add Source, add destinations, add Scheduler, see Stats, create player, enable ABR. Add caption options 1-4, add stream security options, and see Encoder credentials.

  14. Channel/Use the Channel credentials to send closed captioning data.

  15. Channel/Monitor live stream embed code.

  16. Channel/Pull all channel activity statistics (output hours and data transfer

  17. Scheduler/Create, edit, or delete a Schedule.

  18. Destination/Create, edit or delete a destination.

  19. Player/Create, edit or delete a player (metered).

  20. Studio/Create, edit or delete Studio projects.

  21. Studio/Create, edit or delete Studio project team members.

  22. Studio/Manage Studio projects (all features).

  23. Statistics/See sources/destinations/channels available per Account/Sub-user/Stream.

  24. Statistics/See players available and used per Account/Sub-user.

  25. Statistics/See Studio projects available and used per Account/Sub-user.

  26. Statistics/See output hours available and used per Account/Sub-user/Stream.

  27. Statistics/See data transferred available and used per Account/Sub-user/Stream.

  28. Statistics/See storage available and used per Account/Sub-user.

  29. Statistics/See VOD ASR billing used per Account/Sub-user/Stream.

  30. Statistics/See Live ASR billing used per Account/Sub-user/Stream.

To use the API, you need an active service account to handle API calls, a unique key to identify your account, and a username and password. Contact the sales department to request an API-compatible service account.

API Best Practices

Videolinq offers an affordable and efficient way to create captions, translations, and transcripts for live broadcasts. The platform provides real-time multi-lingual closed captioning for various video sources, multi-stream distribution to social media and other video platforms, stream protection, a no-code player, monetization tools integrated with third-party advertising services, and a centralized workspace for teams to engage social media audiences with a moderated chat, graphic insertions, e-commerce offerings, and monitoring and measurement tools. This guide outlines best practices for optimizing remote access and managing Videolinq services.

Videolinq Workflow

To use Videolinq, customers must create a live stream in this order:

  • Create a “Sub-user” with access permissions.

  • Create a "Channel". Channels include a video source, target destinations to publish the live stream to, an HLS path for playback, ABR (which affects the HLS path), the ability to create a player, human or automated caption insertion, stream security, and an RTMP path for media encoders (when RTMP is selected as the video source).

  • Create a “Video source” and assign a publishing region (regional media server).

  • Create "Destinations". Enable oath authentication (Facebook, YouTube, Twitch, LinkedIn) or RTMP with/without credentials for all others.

  • Create a "Player". The Videolinq Player can be used to play live and video-on-demand streams. It can stream video from a Videolinq Channel or point to third-party streaming services. The Videolinq Player requires the HLS path to play across all browsers.

  • Create a "Scheduler" to autostart a channel when RTMP is the video source. A Scheduler can also pull RTMP/RTSP source stream or pull files or a playlist and assign them to a Channel. Schedules can operate 24/7, repeat simultaneously every day, or be assigned to run on a specific day/time.

  • Add closed captioning to live streams using one of four methods: (a) no captions in the video is the default mode, (b) closed captioning is embedded on the SDI signal by a compatible hardware encoder, (c) closed captioning is added by a human operator and credentials provided, (d) captions are created automatically.

  • Insert advertising to live or archived video: Videolinq supports the VAST type of ads insertion for live or archived streams via the Videolinq Payer. This is part of the Player configuration.

Input bandwidth

To ensure the best user experience for viewers, it's essential to provide a high-quality, stable input stream. The ideal input stream delivers optimal video quality at the highest consistent bandwidth available from a given location.

Minimum input bandwidth: 1 Mbps

Maximum input bandwidth: 8 Mbps

We recommend using the following bitrates for each screen resolution size:

360p – 1 MBps

720p – 1500-2500 KBps

1080p – 3-4 MBps

1080i – 5-6 MBps

Using Files

Use recorded media to create a video source for streaming content in a channel. See the recommended file type and size the API accepts. There is a 4 GB file size limit per file.

To speed up the process of creating closed captioning files from uploaded media, follow these steps, executing one command per file/action:

  • Prepare a low-resolution version of your master file (MP4 encoded at 640x360 pix resolution 768 KBps video, 128 KBps audio).

  • Upload the file. Wait for confirmation.

  • Select the required original language and translation option. Wait for confirmation of task completion.

  • Preview the generated caption output and make changes when needed.

  • Download the proper file format (SRT/VTT/SCC/PDF).

  • Delete the file when the job is done to conserve storage space.

Supported Encoders

The Videolinq platform ingests Real-Time Media Protocol (RTMP/SRT) video using a “push“ method. The platform can also “pull” a live video source using the RTMP/RTSP/SRT paths. Files can be uploaded to the platform for live stream simulation, but they must use the H.264 video and AAC audio codecs for proper playback. Other file formats are not accepted.

Supported Platforms and CDNs

The Videolinq platform can publish live streams to social media sites (e.g., YouTube, Facebook, or LinkedIn) or streaming video service providers (e.g., Vimeo or Wowza Video).

Stream Connection - Retries

We recommend configuring the ingested streams to retry connecting on failure. Many retry attempts with 5-10-second intervals will mitigate intermittent connectivity issues between the encoder and the entry point. Extend the timeout settings accordingly. Set a maximum 20 attempt connection to retry threshold, then stop trying. When the encoder is refused after the 20th attempt, display an error message to alert the User.

Concurrent Channels & Destinations

The number of “Channels” and “Destinations” is determined by the Enterprise plan limit ordered. The account will share "one bucket" with a set amount of Channels, Destinations, Storage, and output data allowed when using the API features and operating query calls. All sub-users the account creates via the API will share the limits allowed. An unlimited number of “Users”, “Schedulers”, and “Players” can be made with the API. Metered features include output hours, data transfer, file storage, Studio projects, and player loads.

Channel settings

Recommended input requirements for hardware or software encoders:

Protocol: RTMP

Video format: H.264

Audio format: AAC

Max audio sampling: 48000 Hz

Resolution: Up to 1080p

Bitrate: from 1 Mbps to 8 Mbps (streams over 8 Mbps are blocked)

Frame rate: 30 frames-per-second with keyframe interval every 60 frames or 2 seconds

Connectivity

Once a region is selected and a session is connected to the API, that region cannot be changed during the active session. To switch to a different region, the current session must end, and a new session pointing to the desired region must be established. This requirement ensures compliance with data storage regulations, as it keeps all data generated during a session within the initially chosen regional data center, thereby adhering to local storage rules and minimizing cross-border data transfers.

Name Definitions

The Videolinq API uses specific terminology to describe the platform's features and functionality. Below are the key terms referenced in this document:

  • Videolinq account: A subscription plan allowing access to the Videolinq platform.

  • Master Administrator: The owner of the Videolinq Enterprise plan. The Master Administrator creates sub-users and assigns them resource limits.

  • Sub-users Are the Videolinq Enterprise plan customer clients. The customer purchases the Videolinq account and, through programmatic API calls, creates dynamic sub-users with remote access to the Videolinq platform and features.

  • Source: A video signal from a webcam, a live stream using the RTMP/RTSP/SRT protocols, or recorded media played as individual files or in a playlist.

  • Destination: A target media server or video platform live stream from a Channel can be sent to.

  • Channel: A live video signal created from a video source. The video output of a channel can be viewed by a “video player” or sent to “destinations.”

  • Scheduler: An optional feature to automate the activation of a channel.

  • Player: A dynamic, no-code Videolinq HTML5 player that can play live or recorded media hosted by Videolinq or third-party video services.

  • Stream protection: Playback restrictions imposed on a channel output or the Videolinq player. Playback restrictions apply to domains, geographical regions, or sets of IP’s. When playback is requested (for live or recorded media), the stream can only play if it complies with the rules set in the stream protection settings of the channel or the player wizard.

  • Studio: Videolinq cloud-based team collaboration solution for creating interactive live broadcasts distributed to social media platforms.

  • Closed captioning: Captions of data inserted into live streams by human operators or an automated captioning service.

Important note:

When a Videolinq account is suspended or cancelled, all associated API records and media links stop working.

In summary, the Videolinq API allows developers to manage live streaming, captions, and other video-related features seamlessly. By utilizing specific resources, you can allocate channels, destinations, and more for your sub-users while tracking usage and billing efficiently.

If you have any questions or would like to open an API account, feel free to contact us for assistance.

Did this answer your question?