Mirrors/cobalt
1
0
Fork 0
mirror of https://github.com/wukko/cobalt.git synced 2024-11-15 12:50:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs/api: update to reflect new request/response schema

Browse source
This commit is contained in:
dumbmoron 2024-09-04 16:28:39 +00:00
parent 41c23337ff
commit 9800a9b54f
No known key found for this signature in database
1 changed files with 85 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

126
docs/api.md
View file

@ -1,77 +1,105 @@
# cobalt api documentation # 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.
``` <!-- TODO: authorization -->
👍 you can use api.cobalt.tools in your projects for free, just don't be an asshole.
```
## POST: `/api/json` ## POST: `/`
cobalt's main processing endpoint. cobalt's main processing endpoint.
request body type: `application/json` request body type: `application/json`
response 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 Accept: application/json
Content-Type: application/json Content-Type: application/json
``` ```
### request body variables ### request body
| key | type | variables | default | description | | key | type | expected value(s) | default | description |
|:------------------|:----------|:-----------------------------------|:----------|:--------------------------------------------------------------------------------| |:-----------------------------|:----------|:-----------------------------------|:----------|:--------------------------------------------------------------------------------|
| `url` | `string` | URL encoded as URI | `null` | **must** be included in every request. | | `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. | | `videoQuality` | `string` | `144 / ... / 2160 / 4320 / max` | `1080` | `720` quality is recommended for phones. |
| `vQuality` | `string` | `144 / ... / 2160 / max` | `720` | `720` quality is recommended for phones. | | `audioFormat` | `string` | `best / mp3 / ogg / wav / opus` | `mp3` | |
| `aFormat` | `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. |
| `filenamePattern` | `string` | `classic / pretty / basic / nerdy` | `classic` | changes the way files are named. previews can be seen in the web app. | | `filenameStyle` | `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` | | | `downloadMode` | `string` | `auto / audio / mute` | `auto` | `audio` downloads only the audio, `mute` skips the audio track in videos. |
| `isTTFullAudio` | `boolean` | `true / false` | `false` | enables download of original sound used in a tiktok video. | | `youtubeVideoCodec` | `string` | `h264 / av1 / vp9` | `h264` | `h264` is recommended for phones. |
| `isAudioMuted` | `boolean` | `true / false` | `false` | disables audio track in video downloads. | | `youtubeDubLang` | `string` | `en / ru / cs / ja / ...` | -- | specifies the language of audio to download, when the youtube video is dubbed |
| `dubLang` | `boolean` | `true / false` | `false` | backend uses Accept-Language header for youtube video audio tracks when `true`. | | `youtubeDubBrowserLang` | `boolean` | `true / false` | `false` | uses value from the Accept-Language header for `youtubeDubLang`. |
| `disableMetadata` | `boolean` | `true / false` | `false` | disables file metadata when set to `true`. | | `alwaysProxy` | `boolean` | `true / false` | `false` | tunnels all downloads through the processing server, even when not necessary. |
| `twitterGif` | `boolean` | `true / false` | `false` | changes whether twitter gifs are converted to .gif | | `disableMetadata` | `boolean` | `true / false` | `false` | disables file metadata when set to `true`. |
| `tiktokH265` | `boolean` | `true / false` | `false` | changes whether 1080p h265 videos are preferred or not. | | `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 ### response
| key | type | variables | 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` | | `status` | `string` | `stream / redirect` |
| `text` | `string` | various text, mostly used for errors | | `url` | `string` | url for the cobalt stream, or redirect to an external link |
| `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 |
### picker item variables ### picker response
item type: `object` | key | type | values |
|:-------------|:---------|:------------------------------------------------------------|
| `status` | `string` | `picker` |
| `picker` | `array` | array of objects containing the individual media |
| key | type | variables | description | #### picker object
|:--------|:---------|:--------------------------------------------------------|:---------------------------------------| | key | type | values |
| `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 | | | `type` | `string` | `photo` / `video` / `gif` |
| `thumb` | `string` | item thumbnail that's displayed in the picker | used for `video` and `gif` types | | `url` | `string` | |
| `thumb` | `string` | **optional** thumbnail url |
## GET: `/api/stream` ### error response
cobalt's live render (or stream) endpoint. usually, you will receive a url to this endpoint | key | type | values |
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. | `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 #### error object
[read the source code](/src/modules/stream/manage.js). | key | type | values |
|:-------------|:---------|:------------------------------------------------------------|
| `code` | `string` | machine-readable error code explaining the failure reason |
| `context` | `object` | **optional** container for providing more context |
## GET: `/api/serverInfo` #### 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. returns current basic server info.
response body type: `application/json` 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 | | key | type | variables |
|:------------|:---------|:------------------| |:------------|:---------|:------------------|
| `version` | `string` | cobalt version | | `commit` | `string` | commit hash |
| `commit` | `string` | git commit |
| `branch` | `string` | git branch | | `branch` | `string` | git branch |
| `name` | `string` | server name | | `remote` | `string` | git remote |
| `url` | `string` | server url |
| `cors` | `number` | cors status |
| `startTime` | `string` | server start time |