Convertly Video Streaming API

Convertly Video Streams turn a stored video file into production-ready HLS or DASH/CMAF playback. The API creates a video asset, queues background encoding, generates manifests, bitrate renditions, captions, poster art, and returns playback URLs when the stream is ready. Convertly prepares streams asynchronously. Some paid workspaces can use faster managed encoding, and existing assets keep the delivery behavior they were created with. Use Video Streams when your product needs browser/mobile playback instead of a single downloadable MP4: course videos, user-generated video, webinars, previews, clipping workflows, internal media libraries, and AI-generated highlight reels.

Capabilities

Capability	Details
HLS VOD	Generates a master playlist, rendition playlists, and segments.
DASH/CMAF	Add `"dash"` to `packageFormats` to generate an MPEG-DASH manifest and CMAF segments.
Adaptive bitrate	Choose `basic`, `standard`, `hd`, `source_max`, or a custom ladder.
Codecs	Choose `h264` for maximum compatibility or `av1` for lower bitrate delivery on modern clients.
Captions	Attach WebVTT `subtitles` or `captions` tracks at asset creation.
Clipping	Create streamable clips with `start`, `end`, `duration`, and `accurate` or `fast` mode.
Signed playback	Use expiring playback URLs, token TTLs, and optional allowed playback domains.
Playback analytics	The JS SDK can send play, pause, progress, seek, ended, and error events.
Poster frame	Generates `poster.jpg` beside the stream.
Webhooks	Emits `video.stream.started`, `video.stream.ready`, and `video.stream.failed`.

Create a stream

Upload a source video to Convertly Storage first, then create a stream from the stored file ID.

curl -X POST "https://convertly.sh/api/video/streams" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceFileId": "5e8b2c74-19d3-4a6f-b082-c7e5419d36af",
    "profile": "hd",
    "packageFormats": ["hls", "dash"],
    "videoCodec": "h264",
    "access": "signed",
    "tokenTtlSeconds": 3600,
    "allowedDomains": ["app.example.com"],
    "segmentDuration": 6,
    "captions": [
      {
        "label": "English",
        "language": "en",
        "kind": "subtitles",
        "content": "WEBVTT\n\n00:00:00.000 --> 00:00:03.000\nWelcome."
      }
    ],
    "clip": {
      "start": 80,
      "end": 125,
      "mode": "accurate"
    }
  }'

The response is accepted immediately while the worker processes the stream:

{
  "stream": {
    "assetId": "vid_...",
    "playbackId": "pb_...",
    "status": "pending",
    "manifestUrl": null
  }
}

Poll GET /api/video/streams/{id} or subscribe to video.stream.ready.

Profiles

Profile	Renditions
`basic`	360p, 720p
`standard`	360p, 480p, 720p
`hd`	360p, 480p, 720p, 1080p
`source_max`	Up to 2160p when the source allows it
`custom`	Your supplied rendition ladder

Convertly only generates renditions at or below the source height.

Video codecs

videoCodec is optional and defaults to h264.

Codec	Use when	Notes
`h264`	You need the safest browser, mobile, smart TV, and embed compatibility.	Uses H.264 High Profile with AAC audio. HLS uses MPEG-TS segments for SDR renditions and fMP4 for HDR10.
`av1`	You want smaller streams for modern browsers and devices and can tolerate slower encoding.	Uses AV1 video with AAC audio in fMP4/CMAF segments. Test playback in your target players before making AV1 the only rendition set.

AV1 availability depends on the selected profile and source. Existing assets keep the codec selected when they were created. Plan limits cap monthly processing, active stored video, and delivery. Source minutes count the input duration once, regardless of the number of renditions generated. Active stored minutes count the source-video duration retained in Convertly; deleting a stream frees that capacity. Delivery minutes count viewer watch time. A 10 minute video watched fully by 100 viewers uses 1,000 delivery minutes.

Plan	Source minutes / month	Active stored minutes	Delivery minutes / month
Free	10	10	100
Starter	200	200	1,000
Pro	750	750	4,000
Business	3,000	3,000	15,000
Enterprise	250,000	250,000	500,000

All plans can generate the complete seven-rendition ladder through 2160p when the source contains those pixels. Convertly does not upscale a lower-resolution source into fake 4K. Pro and Business can use optional metered overage when it is enabled in billing settings. See Limits for source and delivery minute allowances.

Custom ladders

{
  "sourceFileId": "5e8b2c74-19d3-4a6f-b082-c7e5419d36af",
  "profile": "custom",
  "renditions": [
    { "height": 360, "bitrate": 700000, "audioBitrate": 96000 },
    { "height": 720, "bitrate": 2800000, "audioBitrate": 128000 },
    { "height": 1080, "bitrate": 5000000, "audioBitrate": 192000 }
  ]
}

Playback

When status becomes ready, the stream includes:

{
  "manifestUrl": "https://cdn.convertly.sh/video/v1/pb_.../master.m3u8?expires=...&token=...",
  "hlsManifestUrl": "https://cdn.convertly.sh/video/v1/pb_.../master.m3u8?expires=...&token=...",
  "dashManifestUrl": "https://cdn.convertly.sh/video/v1/pb_.../manifest.mpd?expires=...&token=...",
  "posterUrl": "https://cdn.convertly.sh/video/v1/pb_.../poster.jpg?expires=...&token=..."
}

Convertly applies signed playback authorization to the manifest and its related renditions and segments. Public streams omit the token. Some paid workspaces use managed encoding for faster transcoding. Convertly returns the correct HLS/DASH URLs and mints signed playback tokens for you; no video-provider credentials or signing keys are required in your application. When a signed URL expires, create a new playback session from the stream API.

JS player

Use @convertly-sh/player for a full HLS player with controls and analytics. See the Video player docs for install steps and an interactive embed. For a minimal integration (your own UI + analytics only):

import { bindPlaybackAnalytics } from "@convertly-sh/player";

bindPlaybackAnalytics({
  video: document.querySelector("video")!,
  playbackId: "pb_...",
});

The legacy @convertly-sh/sdk ConvertlyPlayer class still attaches captions and analytics to a raw <video> element, but does not include hls.js or custom controls — prefer @convertly-sh/player for new projects.

Webhook payloads

video.stream.ready includes the asset ID, playback ID, duration, and generated renditions. video.stream.failed includes the error message.

{
  "type": "video.stream.ready",
  "data": {
    "assetId": "9a6d4f21-3c87-4e5b-b190-62f8d7a34ce5",
    "playbackId": "pb_...",
    "duration": 45,
    "renditions": [
      { "height": 360, "bitrate": 700000 },
      { "height": 720, "bitrate": 2800000 }
    ]
  }
}

Behavior and limits

HLS and DASH packaging runs asynchronously after you create a stream. Poll the stream status or listen for webhooks until the asset is ready.
Source files must already exist in Convertly Storage.
Packaged manifests, posters, captions, and renditions count toward the same storage allowance as source files when Convertly stores those outputs.
Delivery minutes count toward your plan regardless of the encoding path used for the asset.
Deleting a stream removes its associated packaged playback outputs.
Segment duration defaults to 6 seconds and may be set from 2 to 12.
Signed playback URLs expire after tokenTtlSeconds. Create a new signed playback session when the URL expires.
Domain restrictions check the playback request Origin or Referer host when allowedDomains is set.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Capabilities

Create a stream

Profiles

Video codecs

Custom ladders

Playback

JS player

Webhook payloads

Behavior and limits

​Capabilities

​Create a stream

​Profiles

​Video codecs

​Custom ladders

​Playback

​JS player

​Webhook payloads

​Behavior and limits

Capabilities

Create a stream

Profiles

Video codecs

Custom ladders

Playback

JS player

Webhook payloads

Behavior and limits