cobalt/docs/api.md

cobalt api documentation

this document provides info about methods and acceptable variables for all cobalt api requests.

Important

hosted api instances (such as api.cobalt.tools) use bot protection and are not intended to be used in other projects without explicit permission. if you want to access the cobalt api reliably, you should host your own instance.

authentication

an api instance may be configured to require you to authenticate yourself. if this is the case, you will typically receive an error response with a api.auth.<method>.missing code, which tells you that a particular method of authentication is required.

authentication is done by passing the Authorization header, containing the authentication scheme and the token:

Authorization: <scheme> <token>

currently, cobalt supports two ways of authentication. an instance can choose to configure both, or neither:

• Api-Key
• Bearer

api-key authentication

the api key authentication is the most straightforward. the instance owner will assign you an api key which you can then use to authenticate like so:

Authorization: Api-Key aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

if you are an instance owner and wish to configure api key authentication, see the instance documentation!

bearer authentication

the cobalt server may be configured to issue JWT bearers, which are short-lived tokens intended for use by regular users (e.g. after passing a challenge). currently, cobalt can issue tokens for successfully solved turnstile challenge, if the instance has turnstile configured. the resulting token is passed like so:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

POST: /

cobalt's main processing endpoint.

request body type: application/json response body type: application/json

Important

you must include Accept and Content-Type headers with every POST / request.

Accept: application/json
Content-Type: application/json

request body

key	type	expected value(s)	default	description
url	string	URL to download	--	must be included in every request.
videoQuality	string	144 / ... / 2160 / 4320 / max	1080	720 quality is recommended for phones.
audioFormat	string	best / mp3 / ogg / wav / opus	mp3
audioBitrate	string	320 / 256 / 128 / 96 / 64 / 8	128	specifies the bitrate to use for the audio. applies only to audio conversion.
filenameStyle	string	classic / pretty / basic / nerdy	classic	changes the way files are named. previews can be seen in the web app.
downloadMode	string	auto / audio / mute	auto	audio downloads only the audio, mute skips the audio track in videos.
youtubeVideoCodec	string	h264 / av1 / vp9	h264	h264 is recommended for phones.
youtubeDubLang	string	en / ru / cs / ja / ...	--	specifies the language of audio to download, when the youtube video is dubbed
youtubeDubBrowserLang	boolean	true / false	false	uses value from the Accept-Language header for youtubeDubLang.
alwaysProxy	boolean	true / false	false	tunnels all downloads through the processing server, even when not necessary.
disableMetadata	boolean	true / false	false	disables file metadata when set to true.
tiktokFullAudio	boolean	true / false	false	enables download of original sound used in a tiktok video.
tiktokH265	boolean	true / false	false	changes whether 1080p h265 videos are preferred or not.
twitterGif	boolean	true / false	true	changes whether twitter gifs are converted to .gif

response

the response will always be a JSON object containing the status key, which will be one of:

• error - something went wrong
• picker - we have multiple items to choose from
• redirect - you are being redirected to the direct service URL
• tunnel - cobalt is proxying the download for you

tunnel/redirect response

key	type	values
status	string	tunnel / redirect
url	string	url for the cobalt tunnel, or redirect to an external link
filename	string	cobalt-generated filename for the file being downloaded

picker response

key	type	values
status	string	picker
audio	string	optional returned when an image slideshow (such as on tiktok) has a general background audio
audioFilename	string	optional cobalt-generated filename, returned if audio exists
picker	array	array of objects containing the individual media

picker object

key	type	values
type	string	photo / video / gif
url	string
thumb	string	optional thumbnail url

error response

key	type	values
status	string	error
error	object	contains more context about the error

error object

key	type	values
code	string	machine-readable error code explaining the failure reason
context	object	optional container for providing more context

error.context object

key	type	values
service	string	optional, stating which service was being downloaded from
limit	number	optional number providing the ratelimit maximum number of requests, or maximum downloadable video duration

GET: /

returns current basic server info. response body type: application/json

response body

key	type	variables
cobalt	object	information about the cobalt instance
git	object	information about the codebase that is currently running

cobalt object

key	type	description
version	string	current version
url	string	server url
startTime	string	server start time in unix milliseconds
durationLimit	number	maximum downloadable video length in seconds
services	string[]	array of services which this instance supports

git object

key	type	variables
commit	string	commit hash
branch	string	git branch
remote	string	git remote

POST: /session

used for generating JWT tokens, if enabled. currently, cobalt only supports generating tokens when a turnstile challenge solution is submitted by the client.

the turnstile challenge response is submitted via the cf-turnstile-response header.

response body

key	type	description
token	string	a Bearer token used for later request authentication
exp	number	number in seconds indicating the token lifetime

on failure, an error response is returned.