Mirrors/cobalt
1
0
Fork 0
mirror of https://github.com/wukko/cobalt.git synced 2025-05-29 13:00:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs/api: rewrite with up-to-date info and better formatting

Browse Source
This commit is contained in:
wukko 2025-05-27 18:06:56 +06:00
parent c2d76010c5
commit 50a0f29ed9
No known key found for this signature in database
GPG Key ID: 3E30B3F26C7B4AA2
1 changed files with 162 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
docs/api.md
View File

@ -1,8 +1,15 @@
# cobalt api documentation
this document provides info about methods and acceptable variables for all cobalt api requests.
methods, acceptable values, headers, responses and everything else related to making and parsing requests from a cobalt api instance.
> [!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.
> 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 use the cobalt api, you should [host your own instance](/docs/run-an-instance.md) or ask an instance owner for access.
- [POST /](#post)
- [POST /session](#post-session)
- [GET /](#get)
- [GET /tunnel](#get-tunnel)
all endpoints (except for `GET /`) are rate limited and return current rate limiting status in `RateLimit-*` headers, according to the ["RateLimit Header Fields for HTTP" spec](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html#name-header-specifications).
## authentication
an api instance may be configured to require you to authenticate yourself.
@ -40,14 +47,11 @@ challenge, if the instance has turnstile configured. the resulting token is pass
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## POST: `/`
## 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.
> you must include correct `Accept` and `Content-Type` headers with every `POST /` request.
```
Accept: application/json
@ -55,103 +59,132 @@ 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. |
| `allowH265` | `boolean` | `true / false` | `false` | allows h265 videos when enabled. applies to tiktok & xiaohongshu. |
| `convertGif` | `boolean` | `true / false` | `true` | changes whether mute looping videos are converted to .gif |
| `youtubeHLS` | `boolean` | `true / false` | `false` | specifies whether to use HLS for downloading video or audio from youtube. |
body type: `application/json`
not a fan of reading tables of text?
you can read [the api schema](/api/src/processing/schema.js) directly from code instead!
### api schema
all keys except for `url` are optional. value options are separated by `/`.
#### general
| key | type | description/value | default |
|:-----------------------|:----------|:----------------------------------------------------------------|:-----------|
| `url` | `string` | source URL | *required* |
| `audioBitrate` | `string` | `320 / 256 / 128 / 96 / 64 / 8` (kbps) | `128` |
| `audioFormat` | `string` | `best / mp3 / ogg / wav / opus` | `mp3` |
| `downloadMode` | `string` | `auto / audio / mute` | `auto` |
| `filenameStyle` | `string` | `classic / pretty / basic / nerdy` | `basic` |
| `videoQuality` | `string` | `max / 4320 / 2160 / 1440 / 1080 / 720 / 480 / 360 / 240 / 144` | `1080` |
| `disableMetadata` | `boolean` | title, artist, and other info will not be added to the file | `false` |
| `alwaysProxy` | `boolean` | always tunnel all files, even when not necessary | `false` |
| `localProcessing` | `boolean` | remux/transcode files locally instead of the server | `false` |
#### service-specific options
| key | type | description/value | default |
|:-----------------------|:----------|:--------------------------------------------------|:--------|
| `youtubeVideoCodec` | `string` | `h264 / av1 / vp9` | `h264` |
| `youtubeDubLang` | `string` | any valid language code, such as: `en` or `zh-CN` | *none* |
| `convertGif` | `boolean` | convert twitter gifs to the actual GIF format | `true` |
| `allowH265` | `boolean` | allow H265/HEVC videos from tiktok/xiaohongshu | `false` |
| `tiktokFullAudio` | `boolean` | download the original sound used in a video | `false` |
| `youtubeBetterAudio` | `boolean` | prefer higher quality youtube audio if possible | `false` |
| `youtubeHLS` | `boolean` | use HLS formats when downloading from youtube | `false` |
### 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
body type: `application/json`
the response will always be a JSON object containing the `status` key, which is one of:
- `tunnel`: cobalt is proxying and/or remuxing/transcoding the file for you.
- `local-processing`: cobalt is proxying the files for you, but you have to remux/transcode them locally.
- `redirect`: cobalt will redirect you to the direct service URL.
- `picker`: there are multiple items to choose from, a picker should be shown.
- `error`: something went wrong, here's an error code.
### 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 |
| key | type | value |
|:-------------|:---------|:-----------------------------------------------------------|
| `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 |
### local processing response
| key | type | value |
|:-------------|:-----------|:--------------------------------------------------------------|
| `status` | `string` | `local-processing` |
| `type` | `string` | `merge`, `mute`, `audio`, or `gif` |
| `service` | `string` | origin service (`youtube`, `twitter`, `instagram`, etc) |
| `tunnel` | `string[]` | array of tunnel URLs |
| `output` | `object` | details about the output file ([see below](#output-object)) |
| `audio` | `object` | audio-specific details (optional, [see below](#audio-object)) |
| `isHLS` | `boolean` | whether the output is in HLS format (optional) |
#### output object
| key | type | value |
|:-----------|:---------|:----------------------------------------------------------------------------------|
| `type` | `string` | mime type of the output file |
| `filename` | `string` | filename of the output file |
| `metadata` | `object` | metadata associated with the file (optional, [see below](#outputmetadata-object)) |
#### output.metadata object
all keys in this table are optional.
| key | type | description |
|:------------|:---------|:-------------------------------------------|
| `album` | `string` | album name or collection title |
| `copyright` | `string` | copyright information or ownership details |
| `title` | `string` | title of the track or media file |
| `artist` | `string` | artist or creator name |
| `track` | `string` | track number or position in album |
| `date` | `string` | release date or creation date |
#### audio object
| key | type | value |
|:----------|:----------|:-------------------------------------------|
| `copy` | `boolean` | defines whether audio codec data is copied |
| `format` | `string` | output audio format |
| `bitrate` | `string` | preferred bitrate of audio format |
### 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 |
| key | type | value |
|:----------------|:---------|:-----------------------------------------------------------------------------------------------|
| `status` | `string` | `picker` |
| `audio` | `string` | returned when an image slideshow (such as on tiktok) has a general background audio (optional) |
| `audioFilename` | `string` | cobalt-generated filename, returned if `audio` exists (optional) |
| `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 |
| key | type | value |
|:-------------|:----------|:--------------------------|
| `type` | `string` | `photo` / `video` / `gif` |
| `url` | `string` | |
| `thumb` | `string` | thumbnail url (optional) |
### error response
| key | type | values |
|:-------------|:---------|:------------------------------------------------------------|
| `status` | `string` | `error` |
| `error` | `object` | contains more context about the error |
| key | type | value |
|:-------------|:---------|:------------------------------|
| `status` | `string` | `error` |
| `error` | `object` | error code & optional context |
#### error object
| key | type | values |
|:-------------|:---------|:------------------------------------------------------------|
| `code` | `string` | machine-readable error code explaining the failure reason |
| `context` | `object` | **optional** container for providing more context |
| key | type | value |
|:-------------|:---------|:----------------------------------------------------------|
| `code` | `string` | machine-readable error code explaining the failure reason |
| `context` | `object` | additional error context (optional) |
#### 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`
| key | type | value |
|:-------------|:---------|:----------------------------------------------------------------------------|
| `service` | `string` | origin service (optional) |
| `limit` | `number` | the maximum downloadable video duration or the rate limit window (optional) |
## 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 |
|:----------------|:-----------|:-------------------------------------------------------|
@ -159,3 +192,48 @@ the turnstile challenge response is submitted via the `cf-turnstile-response` he
| `exp` | `number` | number in seconds indicating the token lifetime |
on failure, an [error response](#error-response) is returned.
## GET `/`
provides basic instance info.
### response
body type: `application/json`
| key | type | description |
|:------------|:---------|:---------------------------------------------------------|
| `cobalt` | `object` | information about the cobalt instance |
| `git` | `object` | information about the codebase that is currently running |
#### cobalt object
| key | type | description |
|:-------------------|:-----------|:-----------------------------------------------|
| `version` | `string` | cobalt version |
| `url` | `string` | instance url |
| `startTime` | `string` | instance start time in unix milliseconds |
| `turnstileSitekey` | `string` | site key for a turnstile widget (optional) |
| `services` | `string[]` | array of services which this instance supports |
#### git object
| key | type | description |
|:------------|:---------|:------------|
| `commit` | `string` | commit hash |
| `branch` | `string` | git branch |
| `remote` | `string` | git remote |
## GET `/tunnel`
endpoint for file tunnels (proxy/remux/transcode). the response is a file stream. all errors are reported via
[HTTP status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status).
### returned headers
- `Content-Length`: file size, in bytes. returned when exact final file size is known.
- `Estimated-Content-Length`: estimated file size, in bytes. returned when real `Content-Length` is not known.
a rough estimate which should NOT be used for strict size verification.
can be used to show approximate download progress in UI.
### possible HTTP status codes
- 200: OK
- 401: Unauthorized
- 403: Bad Request
- 404: Not Found
- 429: Too Many Requests (rate limit exceeded, check [RateLimit-* headers](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html#name-header-specifications))
- 500: Internal Server Error.