Encoding

Turn a master into the qualities a player needs, packaged for adaptive streaming and encrypted if you want. The outputs land in your storage, ready to serve.

How it works #

You submit a job saying which file to encode and at which qualities. We answer 202 with a queued job: encoding takes minutes, so nothing waits for it. When it finishes, each output appears as a file of yours in storage, ready to serve with a signed URL.

The source can be a file already in your storage (sourceFileId) or a public URL (sourceUrl). If it is yours, we hand the encoder a temporary permission — your file is never made public, and that pull does not count as delivery on your bill.

The frame rate is a ceiling

By default we cap the output at 30 fps. A master already below it is left alone — a 24 fps film comes out at 24 — and only a faster one is brought down. Raising the ceiling to 60 with fps: 60 doubles the price of the video and its weight; and it invents nothing either: a 30 fps master gives 30, charged as 30.

Nothing is upscaled

Asking for 1080p from a 720p master produces 720p, not a blurry 1080p. And you are billed for the 720p you got, not the 1080p you asked for: the quote is a ceiling, and the charge is settled against what was actually produced.

Submitting a job #

Two qualities, HLS and DASH packages, encrypted with your keys

curl -X POST https://kms.airi.live/v1/encoding/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "sourceFileId": "a1b2c3d4-…",
    "heights": [1080, 720],
    "durationSeconds": 600,
    "package": "hls+dash",
    "drm": true
  }'

Field	What it does
`heights`	The qualities: 240, 360, 480, 720, 1080, 1440 or 2160
`codec`	`h264` (default) or `hevc`. HEVC is ~40% smaller and costs twice as much
`fps`	A ceiling, not a target: 30 by default, 60 if you raise it. A 24 fps film stays at 24
`package`	`none`, `hls`, `dash` or `hls+dash`. A package is what lets a player switch quality mid-playback
`mp4`	Whether you also want a standalone MP4 per quality. Default yes
`drm`	Encrypt the packages with a key from your own KMS
`durationSeconds`	How long the master is. It only sizes the hold — see below
`customId`	Your own identifier. Doubles as an idempotency key

The customId makes retrying safe: an identical request that died on the wire returns the job it already started, and is paid for once. Reusing the same identifier for a different ladder collides instead of silently ignoring what you asked for.

What it costs #

Billing is per minute of output, per quality, once per deliverable format. Ten minutes at 1080p and 720p is twenty output minutes, not ten. Ask for MP4, HLS and DASH as well and that is three passes of the same ladder.

Quality	H.264	HEVC
Up to 480p	$0.0065 /min	$0.013 /min
720p and 1080p	$0.013 /min	$0.026 /min
1440p	$0.0325 /min	$0.065 /min
4K	$0.0585 /min	$0.117 /min
Audio (per output)	$0.0013 /min	$0.0013 /min

You can ask the exact price before spending anything, from the same code that later charges:

example

curl "https://kms.airi.live/v1/encoding/quote?heights=1080,720&durationSeconds=600" \
  -H "Authorization: Bearer $TOKEN"

Held on submit, settled on completion

The price is held against your balance before the encoder is called, because an encode cannot be undone. On completion it is settled against the duration the encoder measured and the qualities actually produced — anything left over comes back. That is why durationSeconds only sizes the hold: under-declaring does not make it cheaper.

Billing is by fraction of a minute, not by started minute: a ten-second clip pays a sixth of one. An encrypted job also costs one key, at the usual DRM tariff. And a job that fails costs you nothing: whatever was produced is deleted and the hold is returned in full.

Packages and DRM #

An HLS or DASH package is a folder of a manifest and its segments. In your storage it appears as one file weighing the whole folder, and its signed URL covers the entire folder automatically — which is what makes the segments resolve.

With drm: true we ask your own KMS for a key and hand it to the encoder, so the package comes out already encrypted and with the licence URL inside the manifest. It signals Widevine and PlayReady at once, in a single pass.

An encrypted job delivers two packages

The three DRM systems do not fit in one packaging, so a job with drm: true produces two, under the same key: a DASH encrypted with CENC for Widevine and PlayReady (Chrome, Edge, Firefox, Android) and an HLS encrypted with SAMPLE-AES for FairPlay (Safari, iOS, tvOS). This is not a workaround: Apple requires SAMPLE-AES and the other two require CENC. Ask for hls, dash or both and you get both — half the platforms is not worth delivering.

We check it, we do not assume it

Before handing you an encrypted package we read its initialisation segment and verify it carries the tenc box, which is what says the samples really are encrypted. If it is missing, the job is marked failed, whatever was produced is deleted, and your money comes back. A visible failure beats a package that looks protected and is not.

Standalone MP4s are not encrypted

Only packages are: a progressive download is not a protected delivery format, and pretending otherwise would be worse than not offering it. Asking for drm: true without a package is refused rather than quietly delivered in the clear.

Following a job #

example

curl "https://kms.airi.live/v1/encoding/jobs/$ID" -H "Authorization: Bearer $TOKEN"

queued: Accepted, waiting at the provider
running: Encoding
finalising: Finished; we are measuring and creating your files
completed: Done. outputFileIds are your files
failed: Failed. You were not charged
cancelled: You cancelled it

Cancelling does not stop the encode

The provider offers no way to abort a running task, so the job finishes and we pay for it. Cancelling means we stop billing you, and whatever was produced is deleted.

Permissions #

`encoding:write`: Submit and cancel jobs.
`encoding:read`: Read jobs and ask for quotes.
`storage:read`: Needed when the source is a file of yours.