diff --git a/docs/api.md b/docs/api.md index 6cd66bba..c52363cd 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,77 +1,105 @@ # cobalt api documentation -this document provides info about methods and acceptable variables for all cobalt api requests. +this document provides info about methods and acceptable variables for all cobalt api requests. + + + +## POST: `/` +cobalt's main processing endpoint. + +request body type: `application/json` +response body type: `application/json` ``` -👍 you can use api.cobalt.tools in your projects for free, just don't be an asshole. -``` - -## POST: `/api/json` -cobalt's main processing endpoint. - -request body type: `application/json` -response body type: `application/json` - -``` -⚠️ you must include Accept and Content-Type headers with every POST /api/json request. +⚠️ you must include Accept and Content-Type headers with every `POST /` request. Accept: application/json Content-Type: application/json ``` -### request body variables -| key | type | variables | default | description | -|:------------------|:----------|:-----------------------------------|:----------|:--------------------------------------------------------------------------------| -| `url` | `string` | URL encoded as URI | `null` | **must** be included in every request. | -| `vCodec` | `string` | `h264 / av1 / vp9` | `h264` | applies only to youtube downloads. `h264` is recommended for phones. | -| `vQuality` | `string` | `144 / ... / 2160 / max` | `720` | `720` quality is recommended for phones. | -| `aFormat` | `string` | `best / mp3 / ogg / wav / opus` | `mp3` | | -| `filenamePattern` | `string` | `classic / pretty / basic / nerdy` | `classic` | changes the way files are named. previews can be seen in the web app. | -| `isAudioOnly` | `boolean` | `true / false` | `false` | | -| `isTTFullAudio` | `boolean` | `true / false` | `false` | enables download of original sound used in a tiktok video. | -| `isAudioMuted` | `boolean` | `true / false` | `false` | disables audio track in video downloads. | -| `dubLang` | `boolean` | `true / false` | `false` | backend uses Accept-Language header for youtube video audio tracks when `true`. | -| `disableMetadata` | `boolean` | `true / false` | `false` | disables file metadata when set to `true`. | -| `twitterGif` | `boolean` | `true / false` | `false` | changes whether twitter gifs are converted to .gif | -| `tiktokH265` | `boolean` | `true / false` | `false` | changes whether 1080p h265 videos are preferred or not. | +### request body +| key | type | expected value(s) | default | description | +|:-----------------------------|:----------|:-----------------------------------|:----------|:--------------------------------------------------------------------------------| +| `url` | `string` | URL encoded as URI | `null` | **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 body variables -| key | type | variables | +### 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 +- `stream` - cobalt is proxying the download for you + +### stream/redirect response +| key | type | values | |:-------------|:---------|:------------------------------------------------------------| -| `status` | `string` | `error / redirect / stream / success / rate-limit / picker` | -| `text` | `string` | various text, mostly used for errors | -| `url` | `string` | direct link to a file or a link to cobalt's live render | -| `pickerType` | `string` | `various / images` | -| `picker` | `array` | array of picker items | -| `audio` | `string` | direct link to a file or a link to cobalt's live render | +| `status` | `string` | `stream / redirect` | +| `url` | `string` | url for the cobalt stream, or redirect to an external link | -### picker item variables -item type: `object` +### picker response +| key | type | values | +|:-------------|:---------|:------------------------------------------------------------| +| `status` | `string` | `picker` | +| `picker` | `array` | array of objects containing the individual media | -| key | type | variables | description | -|:--------|:---------|:--------------------------------------------------------|:---------------------------------------| -| `type` | `string` | `video / photo / gif` | used only if `pickerType` is `various` | -| `url` | `string` | direct link to a file or a link to cobalt's live render | | -| `thumb` | `string` | item thumbnail that's displayed in the picker | used for `video` and `gif` types | +#### picker object +| key | type | values | +|:-------------|:----------|:------------------------------------------------------------| +| `type` | `string` | `photo` / `video` / `gif` | +| `url` | `string` | | +| `thumb` | `string` | **optional** thumbnail url | -## GET: `/api/stream` -cobalt's live render (or stream) endpoint. usually, you will receive a url to this endpoint -from a successful call to `/api/json`. however, the parameters passed to it are **opaque** -and **unmodifiable** from your (the api client's) perspective, and can change between versions. +### error response +| key | type | values | +|:-------------|:---------|:------------------------------------------------------------| +| `status` | `string` | `error` | +| `error` | `object` | contains more context about the error | -therefore you don't need to worry about what they mean - but if you really want to know, you can -[read the source code](/src/modules/stream/manage.js). +#### error object +| key | type | values | +|:-------------|:---------|:------------------------------------------------------------| +| `code` | `string` | machine-readable error code explaining the failure reason | +| `context` | `object` | **optional** container for providing more context | -## GET: `/api/serverInfo` -returns current basic server info. +#### 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 variables +### 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 | |:------------|:---------|:------------------| -| `version` | `string` | cobalt version | -| `commit` | `string` | git commit | +| `commit` | `string` | commit hash | | `branch` | `string` | git branch | -| `name` | `string` | server name | -| `url` | `string` | server url | -| `cors` | `number` | cors status | -| `startTime` | `string` | server start time | +| `remote` | `string` | git remote |