Spaces:
Paused
Paused
| # 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](/docs/run-an-instance.md) or ask an instance owner for access. | |
| ## 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](#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`](#api-key-authentication) | |
| - [`Bearer`](#bearer-authentication) | |
| ### 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](run-an-instance.md#api-key-file-format) 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](run-an-instance.md#list-of-all-environment-variables) | |
| 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 / es-US / ...` | -- | specifies the language of audio to download when a youtube video is dubbed. | | |
| | `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` | allows h265 videos when enabled. applies to tiktok & xiaohongshu. | | |
| | `twitterGif` | `boolean` | `true / false` | `true` | changes whether twitter gifs are converted to .gif | | |
| | `youtubeHLS` | `boolean` | `true / false` | `false` | specifies whether to use HLS for downloading video or audio from youtube. | | |
| ### 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](run-an-instance.md#list-of-all-environment-variables) 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](#error-response) is returned. | |