Create download
const url = 'https://example.com/api/v1/downloads';const options = { method: 'POST', headers: {cookie: 'kivo_session=<kivo_session>', 'Content-Type': 'application/json'}, body: '{"workId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","versionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","audioTrackId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","subtitleTrackId":"example","capabilities":{"file":{"containers":["example"],"trackSelection":true},"video":[{"codec":"example","delivery":["file"],"containers":["example"],"tags":["example"],"profiles":["example"],"maxLevel":1,"maxBitDepth":1,"maxWidth":1,"maxHeight":1,"maxFrameRate":1,"maxBitrateBps":1,"maxRefFrames":1,"interlaced":true,"anamorphic":true,"hdr":["hdr10"],"dolbyVision":[{"profile":1,"compat":[1],"el":true}],"doviFallback":true}],"audio":[{"codec":"example","delivery":["file"],"containers":["example"],"maxChannels":1,"maxSampleRate":1,"maxBitDepth":1,"profiles":["example"]}],"subtitles":[{"codec":"example","delivery":["file"],"containers":["example"]}]},"settings":{"localQuality":{"mode":"auto","maxBitrateBps":1,"bandwidthBps":1},"remoteQuality":{"mode":"auto","maxBitrateBps":1,"bandwidthBps":1},"directPlay":true,"burnSubtitles":true},"quality":"original"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/downloads \ --header 'Content-Type: application/json' \ --cookie kivo_session=<kivo_session> \ --data '{ "workId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "versionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "audioTrackId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "subtitleTrackId": "example", "capabilities": { "file": { "containers": [ "example" ], "trackSelection": true }, "video": [ { "codec": "example", "delivery": [ "file" ], "containers": [ "example" ], "tags": [ "example" ], "profiles": [ "example" ], "maxLevel": 1, "maxBitDepth": 1, "maxWidth": 1, "maxHeight": 1, "maxFrameRate": 1, "maxBitrateBps": 1, "maxRefFrames": 1, "interlaced": true, "anamorphic": true, "hdr": [ "hdr10" ], "dolbyVision": [ { "profile": 1, "compat": [ 1 ], "el": true } ], "doviFallback": true } ], "audio": [ { "codec": "example", "delivery": [ "file" ], "containers": [ "example" ], "maxChannels": 1, "maxSampleRate": 1, "maxBitDepth": 1, "profiles": [ "example" ] } ], "subtitles": [ { "codec": "example", "delivery": [ "file" ], "containers": [ "example" ] } ] }, "settings": { "localQuality": { "mode": "auto", "maxBitrateBps": 1, "bandwidthBps": 1 }, "remoteQuality": { "mode": "auto", "maxBitrateBps": 1, "bandwidthBps": 1 }, "directPlay": true, "burnSubtitles": true }, "quality": "original" }'Downloads a work to keep in the app.
Decides the download as playback is decided, from the capabilities
the app plays offline, but always as whole files: the original
(delivery file) where the app plays it and it’s no larger than
the quality’s estimate, else a conversion to one MP4 per part
(delivery conversion), a remux where only the container is wrong,
copying what it can. A book is always its original, and one the
app can’t play is 409 with code notPlayable and its
reason; so is a user without downloads
(downloadsNotAllowed). The selected subtitle is kept as a file
the app draws; for an app that draws none, a text subtitle
is the conversion’s own text track (method stream), which the
player shows as it does a stream’s, and any other is burned in.
A download that needs work on the server (a conversion, or its
subtitle to prepare) is queued, then preparing, one at a time
across the server in the order asked, kept across restarts; then
ready, or failed with a reason, which retry asks again. The
rest are ready at once. A downloadsChanged event says when the
user’s downloads move. Asking again for exactly the same, as
when an answer was lost, returns the same download, unless it
failed. Downloads don’t count against the user’s stream limit,
nor conversions against the server’s video transcodes. A download
belongs to a session, so an API key’s caller gets 404.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
A UUIDv7.
Download this version. Default as for playback (PlayCreate).
An audio track’s id. Default as for playback (PlayCreate).
A subtitle track’s id, or off. Default as for playback (PlayCreate).
What the client plays offline.
object
Files it plays whole, the original or a download. Absent, it plays none.
object
Containers it plays, such as mkv, mp4, webm, ts, m2ts, mov, m4a, mp3, flac, ogg.
It plays any audio track inside a file, not only the default one, so choosing another audio track keeps the file. Default false.
One kind of video the client decodes.
object
Such as h264, hevc, av1, vp9, mpeg2video, vc1.
Where it decodes it, file or stream.
For file, the containers it decodes this in; other containers don’t match the entry.
For file, the codec tags it takes, such as hvc1, hev1, dvh1, dvhe.
Profiles as ffprobe prints them, such as High, Main 10, Profile 2.
The highest level, as the codec’s specification writes it, such as 4.1 or 5.1.
The decoder’s limit in bits per second. A quality the user picks goes in settings instead.
Whether it plays interlaced video. Default true.
Whether it plays video with non-square pixels. Default true.
The HDR formats it shows, of hdr10, hdr10plus and hlg; SDR always plays. An HDR10+ video matches hdr10.
The Dolby Vision profiles it shows.
A Dolby Vision profile a client shows. A video matches when its
profile is listed, with its base layer’s compatibility ID among
compat when that’s given.
object
The profile, 5, 7, 8 or 10.
The base layer compatibility IDs it shows, such as 1, 2, 4.
Whether it plays a video with an enhancement layer. Absent means it does.
Play a Dolby Vision video whose profile isn’t listed by its base
layer, when that layer matches hdr: profile 8.1 and 7 are
HDR10, 8.4 is HLG, 8.2 is SDR, and 10 is what its compatibility
ID says. Default false.
One kind of audio the client plays.
object
Such as aac, ac3, eac3, truehd, dts, flac, opus, mp3, alac.
Where it plays it, file or stream.
For file, the containers it plays this in.
The most channels that reach the output: decoded on the device, no more than its speakers or its own setting; passed through, as many as the receiver takes. Audio with more channels is transcoded to AAC with as many as the client’s AAC entry allows, at most 6; to stereo it’s mixed keeping dialogue clear.
Profiles as ffprobe prints them, such as LC, HE-AAC, Dolby TrueHD + Dolby Atmos.
A subtitle codec a client shows, and how. The server converts a
text subtitle to a text codec listed for a delivery. In the stream
that’s always WebVTT, the only text HLS carries. As an external
file it’s WebVTT too, where webvtt is listed, converted from
SubRip, WebVTT, mov_text or ASS as plain text, with styling beyond
italics, bold and underline dropped.
An ASS track stays ASS for a client that lists ass, and an
embedded one is burned in for a client that doesn’t. Image
subtitles are never converted; a client that can’t show one has it
burned in.
object
Such as webvtt, subrip, ass, mov_text, hdmv_pgs_subtitle, dvd_subtitle.
file read from the played file, stream a WebVTT rendition of
the HLS stream, external its own file. In picture-in-picture
or on AirPlay a client leaves out external.
For file, the containers it reads this from; other containers don’t match the entry.
The settings a download applies, directPlay and burnSubtitles.
object
The client’s quality on the server’s local networks.
object
A quality pick: auto chosen from limits and measured bandwidth,
original with no cap, limit capped at maxBitrateBps.
For limit, from the fixed ladder.
For auto, the client’s last measured download rate from this server; the play stays below about 80% of it.
The client’s quality anywhere else, used instead of localQuality when the server counts the client as remote.
object
A quality pick: auto chosen from limits and measured bandwidth,
original with no cap, limit capped at maxBitrateBps.
For limit, from the fixed ladder.
For auto, the client’s last measured download rate from this server; the play stays below about 80% of it.
Play files directly. Default true.
Always burn in subtitles. Default false.
A video’s quality, default high. The original goes as it is
wherever the app plays it and it’s no larger than the quality’s
estimate. A book is always its original.
Responses
Section titled “Responses”The download.
A download as the server holds it for its session. Media URLs are
relative to the API root (/api/v1/) and need the user’s
authorization.
object
A UUIDv7.
A UUIDv7.
A UUIDv7.
The quality asked for, original for a book.
Where a download is: queued waiting in line on the server
(queuePosition says where); preparing its subtitles or conversion
being made (progress and remainingMs say how far); ready to
fetch each part’s url, and each subtitle’s; failed (reason says
why, and retry asks again).
While queued, its place in line, 1 when it’s next.
While preparing, how much is converted, from 0 to 1.
While converting, about how long it has left, once that can be told.
When failed, why: transcodeFailed, storageFull,
sourceUnreadable, subtitlesUnavailable or planUnreadable.
What a download fetches: the original file, or a conversion, an
MP4 per part made for the download.
Every track of the version, and the subtitle choice off, as a
play gives them (PlayStarted.tracks), for playing the download
offline. A track inside the downloaded file has delivery file
and its stream index in that file: in a conversion the video, the
audio, then each text track it carries, the chosen one first. A
subtitle delivered external is fetched with the download, at
url, once the download is ready; one that couldn’t be
extracted has no delivery. A choice without a delivery isn’t in
the download.
One choice of a play: a track of its version, or the subtitle choice
off, and how it shows.
object
A track’s id, or off.
A track’s type.
True for the tracks the play shows; absent otherwise.
Absent when choosing it starts a new play.
The codec it’s delivered as, such as hevc, aac or webvtt.
The video’s HDR as delivered; absent for SDR.
What a transcoded track becomes.
object
Video only; what encodes it, the accelerator’s name as GET /api/v1/accelerators gives it, such as Intel Quick Sync (QSV), or CPU.
Why the track isn’t delivered unchanged in the file, or why choosing it starts a new play, when there’s a reason to give.
The capability that failed: its field (such as maxLevel, codec
or containers), what the client declared, and what the track has.
object
The declared value, lists joined by commas; absent when the client declared none.
For file, the track’s stream index, to select it in the player.
For external, the file, relative to the API root.
For an ass subtitle delivered external, the URLs of the
fonts it uses, each once, relative to the API root:
GET /api/v1/fonts/{sha256}, cacheable for good. Load them
before drawing.
Every part’s bytes. Exact when sizeExact; until a conversion
is ready, an estimate from the quality’s cap, which a grainy
title can exceed.
sizeBytes is exact: the download is ready, or the original
goes as it is. Otherwise it’s an estimate.
The version’s parts in order; positions are on their joined timeline.
object
The part’s file, fetched with the user’s authorization and range requests.
The file’s type, as it’s served (video/mp4 for a conversion; for an original, as the version’s files are).
The file’s exact size, once ready.
The file’s strong ETag, once ready, for If-Range.
A converted file’s SHA-256 in lowercase hex, to check it once fetched.
object
The version’s markers on its timeline, in order.
A part of a video’s timeline a player offers to skip. An episode has intro, recap and credits markers, a movie credits only, any other video none. Each kind comes from an admin’s marker, else, for an episode, what the server found in its season’s audio and pictures, else the file’s own chapters (a chapter whose whole name is the marker’s: Intro, Opening Credits, OP; Recap, Previously On; Credits, End Credits, ED, where it belongs and as long as one lasts).
object
What a marker skips. A later server may add kinds; skip a marker of a kind you don’t know.
Where a marker comes from: the file’s chapters, the audio its episode shares with others in its season (and, for credits, its pictures), or an admin. A later server may add sources.
Set on final credits: nothing follows them to the video’s end but, perhaps, a next episode’s preview, so up next may appear at their start.
Once ready or failed, when the server forgets it, unless deleted sooner.
Example
{ "quality": "original", "state": "queued", "reason": "noTracks", "delivery": "file", "tracks": [ { "type": "video", "delivery": "file", "hdr": "hdr10", "reason": "containerUnsupported" } ], "markers": [ { "kind": "intro", "source": "chapter" } ]}The request is malformed or a field is invalid (code invalidRequest).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}No valid session or API key (code unauthenticated), or a failed sign-in (code invalidCredentials).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}No such resource, or the caller may not see it (code notFound).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}The resource’s state doesn’t allow this; the code says why.
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}default
Section titled “default”A server-side failure: 500 (code internal, or transcodeFailed
for a play’s media), or 503
for something unavailable (codes providerUnavailable and
transcodeBusy, for now; notConfigured, until an admin configures
it).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}