### Install and start nscd Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md Installs and starts nscd so that the ffmpeg-static binary can resolve DNS on Ubuntu 22.04. ```bash sudo apt install nscd sudo service nscd start ``` -------------------------------- ### Start cobalt container Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md Starts the cobalt container from the cobalt directory. ```sh docker compose up -d ``` -------------------------------- ### Prefill link with URL in # parameter Source: https://github.com/imputnet/cobalt/blob/main/web/README.md Pass the URL directly in the # parameter to prefill the input box and start the download automatically. ```text https://cobalt.tools/#https://www.youtube.com/watch?v=dQw4w9WgXcQ ``` -------------------------------- ### GET / Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Provides basic instance information including version, URL, start time, and supported services. Also includes git commit details. ```APIDOC ## GET / ### Description Provides basic instance information. ### Method GET ### Endpoint / ### Response #### Success Response (200) - **cobalt** (object) - Information about the cobalt instance - **git** (object) - Information about the codebase that is currently running #### Response Example { "cobalt": { "version": "string", "url": "string", "startTime": "string", "turnstileSitekey": "string", "services": ["string"] }, "git": { "commit": "string", "branch": "string", "remote": "string" } } ``` -------------------------------- ### Example API Key File (JSON) Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Shows a sample key file with two API keys. The first key has a limit of 10 requests, IP allowlist, and user agent filter. The second key has an unlimited limit, a single IP, and a specific user agent. Do not reuse the UUIDs from this example; generate your own. ```json { "b5c7160a-b655-4c7a-b500-de839f094550": { "limit": 10, "ips": ["10.0.0.0/8", "192.168.42.42"], "userAgents": ["*Chrome*"] }, "b00b1234-a3e5-99b1-c6d1-dba4512ae190": { "limit": "unlimited", "ips": ["192.168.1.2"], "userAgents": ["cobaltbot/1.0"] } } ``` -------------------------------- ### Prefill link with URI-encoded URL in # parameter Source: https://github.com/imputnet/cobalt/blob/main/web/README.md Use a URI-encoded URL in the # parameter to prefill the input box and start the download automatically. ```text https://cobalt.tools/#https%3A//www.youtube.com/watch%3Fv=dQw4w9WgXcQ ``` -------------------------------- ### GET / Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Returns information about the cobalt API instance, such as version and supported services. This endpoint is not rate limited. ```APIDOC ## [GET] / ### Description Returns information about the cobalt API instance, such as version and supported services. This endpoint is not rate limited. ### Method GET ### Endpoint / ### Response #### Success Response (200) - **version** (string) - API version. - **services** (array) - List of supported services. #### Response Example { "version": "10.0.0", "services": ["youtube", "twitter", "instagram"] } ``` -------------------------------- ### Generate UUID with Node.js Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Command to generate a new UUIDv4 for use as an API key identifier. Requires Node.js to be installed. ```bash node -e "console.log(crypto.randomUUID())" ``` -------------------------------- ### GET /tunnel Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Retrieves a tunneled media file. This endpoint is used to fetch media content through the cobalt tunnel. ```APIDOC ## [GET] /tunnel ### Description Retrieves a tunneled media file. This endpoint is used to fetch media content through the cobalt tunnel. ### Method GET ### Endpoint /tunnel ### Parameters #### Query Parameters - **url** (string) - Required - The tunneled media URL. ### Request Example GET /tunnel?url=https%3A%2F%2Ftunnel.cobalt.tools%2F... ### Response #### Success Response (200) - **body** (binary) - The media file content. ### Error Handling - **api.auth..missing** - Authentication required. ``` -------------------------------- ### GET /tunnel Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Endpoint for file tunnels (proxy/remux/transcode). The response is a file stream. All errors are reported via HTTP status codes. ```APIDOC ## GET /tunnel ### Description Endpoint for file tunnels (proxy/remux/transcode). The response is a file stream. All errors are reported via HTTP status codes. ### Method GET ### Endpoint /tunnel ### Response #### Success Response (200) - **Content-Length** (header) - File size in bytes, returned when exact final file size is known. - **Estimated-Content-Length** (header) - Estimated file size in bytes, returned when real Content-Length is not known. Rough estimate, should NOT be used for strict size verification. #### Error Responses - **401** - Unauthorized - **403** - Bad Request - **404** - Not Found - **429** - Too Many Requests (rate limit exceeded, check RateLimit-* headers) - **500** - Internal Server Error ``` -------------------------------- ### Add JWT_SECRET to docker-compose.yml Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Generate a JWT_SECRET (at least 64 characters) and add it to the environment variables. Never use the example secret. ```yaml environment: API_URL: "https://your.instance.url.here.local/" TURNSTILE_SITEKEY: "2x00000000000000000000BB" # use your key TURNSTILE_SECRET: "2x0000000000000000000000000000000AA" # use your key JWT_SECRET: "bgBmF4efNCKPirD" # create a new secret, NEVER use this one ``` -------------------------------- ### Create cobalt folder Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md Creates a directory for the cobalt configuration file. ```sh mkdir cobalt ``` -------------------------------- ### Create docker-compose.yml Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md Navigates into the cobalt folder and creates a docker compose config file using nano. ```sh cd cobalt && nano docker-compose.yml ``` -------------------------------- ### POST / Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md The POST / endpoint returns a response object that varies based on the processing outcome. This documentation covers the local processing response and the picker response structures. ```APIDOC ## POST / ### Description The POST / endpoint returns a response object that varies based on the processing outcome. This documentation covers the local processing response and the picker response structures. ### Method POST ### Endpoint / ### Response #### Success Response (200) ##### local processing response - **status** (string) - `local-processing` - **type** (string) - `merge`, `mute`, `audio`, `gif`, or `remux` - **service** (string) - origin service (`youtube`, `twitter`, `instagram`, etc) - **tunnel** (string[]) - array of tunnel URLs - **output** (object) - details about the output file (see below) - **audio** (object) - audio-specific details (optional, see below) - **isHLS** (boolean) - whether the output is in HLS format (optional) ##### output object - **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) - **subtitles** (boolean) - whether tunnels include a subtitle file ##### output.metadata object All keys in this table are optional. - **album** (string) - album name or collection title - **composer** (string) - composer of the track - **genre** (string) - track's genre(s) - **copyright** (string) - copyright information or ownership details - **title** (string) - title of the track or media file - **artist** (string) - artist or creator name - **album_artist** (string) - album's artist or creator name - **track** (string) - track number or position in album - **date** (string) - release date or creation date - **sublanguage** (string) - subtitle language code (ISO 639-2) ##### audio object - **copy** (boolean) - defines whether audio codec data is copied - **format** (string) - output audio format - **bitrate** (string) - preferred bitrate of audio format - **cover** (boolean) - whether tunnels include a cover art file (optional) - **cropCover** (boolean) - whether cover art should be cropped to a square (optional) ##### picker response - **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 - **type** (string) - `photo` / `video` / `gif` - **url** (string) - - **thumb** (string) - thumbnail url (optional) ``` -------------------------------- ### POST / Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Submits a request to the cobalt API to process a media link. This is the main endpoint for downloading or extracting media from supported services. ```APIDOC ## [POST] / ### Description Submits a request to the cobalt API to process a media link. This is the main endpoint for downloading or extracting media from supported services. ### Method POST ### Endpoint / ### Parameters #### Request Body - **url** (string) - Required - The media link to process. ### Request Example { "url": "https://example.com/video" } ### Response #### Success Response (200) - **status** (string) - Status of the request. - **url** (string) - Direct URL to the media file. #### Response Example { "status": "tunnel", "url": "https://tunnel.cobalt.tools/..." } ### Error Handling - **api.auth..missing** - Authentication required. ``` -------------------------------- ### Set API_KEY_URL environment variable Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Adds the path to the keys file in the container environment. Use this after mounting the keys file. Replace the value with a direct URL if storing the file remotely. ```yaml environment: # ... other variables here ... API_KEY_URL: "file:///keys.json" ``` -------------------------------- ### Mount keys.json as read-only volume Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Adds the local keys.json file to the Docker container as a read-only volume. Required when keeping the keys file locally on the instance server. ```yaml volumes: - ./keys.json:/keys.json:ro # ro - read-only ``` -------------------------------- ### POST / Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md cobalt's main processing endpoint. It accepts a JSON request body with a source URL and optional configuration options, and returns a JSON response indicating the processing status and result. ```APIDOC ## [POST] / ### Description cobalt's main processing endpoint. It accepts a JSON request body with a source URL and optional configuration options, and returns a JSON response indicating the processing status and result. ### Method POST ### Endpoint / ### Headers - **Accept** (string) - Required - Must be `application/json` - **Content-Type** (string) - Required - Must be `application/json` ### Parameters #### Request Body - **url** (string) - Required - Source URL - **audioBitrate** (string) - Optional - Audio bitrate in kbps. Options: `320 / 256 / 128 / 96 / 64 / 8`. Default: `128` - **audioFormat** (string) - Optional - Audio format. Options: `best / mp3 / ogg / wav / opus`. Default: `mp3` - **downloadMode** (string) - Optional - Download mode. Options: `auto / audio / mute`. Default: `auto` - **filenameStyle** (string) - Optional - Filename style. Options: `classic / pretty / basic / nerdy`. Default: `basic` - **videoQuality** (string) - Optional - Video quality. Options: `max / 4320 / 2160 / 1440 / 1080 / 720 / 480 / 360 / 240 / 144`. Default: `1080` - **disableMetadata** (boolean) - Optional - If true, title, artist, and other info will not be added to the file. Default: `false` - **alwaysProxy** (boolean) - Optional - If true, always tunnel all files, even when not necessary. Default: `false` - **localProcessing** (string) - Optional - Local processing mode. Options: `disabled / preferred / forced`. Default: `disabled` - **subtitleLang** (string) - Optional - Any valid ISO 639-1 language code. Default: none - **youtubeVideoCodec** (string) - Optional - YouTube video codec. Options: `h264 / av1 / vp9`. Default: `h264` - **youtubeVideoContainer** (string) - Optional - YouTube video container. Options: `auto / mp4 / webm / mkv`. Default: `auto` - **youtubeDubLang** (string) - Optional - Any valid ISO 639-1 language code. Default: none - **convertGif** (boolean) - Optional - If true, convert twitter gifs to the actual GIF format. Default: `true` - **allowH265** (boolean) - Optional - If true, allow H265/HEVC videos from tiktok. Default: `false` - **tiktokFullAudio** (boolean) - Optional - If true, download the original sound used in a video. Default: `false` - **youtubeBetterAudio** (boolean) - Optional - If true, prefer higher quality youtube audio if possible. Default: `false` - **youtubeHLS** (boolean) - Optional - If true, use HLS formats when downloading from youtube. Default: `false` ### Response #### Success Response (200) 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. For `tunnel` and `redirect` statuses, the response includes: - **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 #### Response Example ```json { "status": "tunnel", "url": "https://example.com/file", "filename": "video.mp4" } ``` ``` -------------------------------- ### Enable Turnstile in docker-compose.yml Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Add the Turnstile sitekey and secret key to your environment variables in docker-compose.yml. Replace the placeholder values with your own keys. ```yaml environment: API_URL: "https://your.instance.url.here.local/" TURNSTILE_SITEKEY: "2x00000000000000000000BB" # use your key TURNSTILE_SECRET: "2x0000000000000000000000000000000AA" # use your key ``` -------------------------------- ### POST /session Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Creates a new session for the cobalt API. This endpoint is used to obtain a session token for subsequent requests. ```APIDOC ## [POST] /session ### Description Creates a new session for the cobalt API. This endpoint is used to obtain a session token for subsequent requests. ### Method POST ### Endpoint /session ### Parameters #### Request Body - **turnstileToken** (string) - Optional - Turnstile challenge token if required by the instance. ### Request Example { "turnstileToken": "..." } ### Response #### Success Response (200) - **token** (string) - Session token. #### Response Example { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ### Error Handling - **api.auth..missing** - Authentication required. ``` -------------------------------- ### POST /session Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Generates a JWT token for request authentication. Requires a Turnstile challenge solution submitted via the `cf-turnstile-response` header. ```APIDOC ## POST /session ### Description Generates a JWT token for request authentication. Requires a Turnstile challenge solution submitted via the `cf-turnstile-response` header. ### Method POST ### Endpoint /session ### Headers - **cf-turnstile-response** (string) - Required - Turnstile challenge solution ### Response #### Success Response (200) - **token** (string) - A `Bearer` token used for later request authentication - **exp** (number) - Number in seconds indicating the token lifetime #### Response Example { "token": "string", "exp": 0 } #### Error Response On failure, an error response is returned with `status` set to `error` and an `error` object containing a machine-readable `code` and optional `context`. ``` -------------------------------- ### Api-Key authentication header Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Use the Api-Key scheme with an assigned API key. The instance owner provides the key; see the instance documentation for configuration. ```http Authorization: Api-Key aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ``` -------------------------------- ### KeyFileContents TypeScript Type Definition Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Defines the structure of the API key file as a JSON-serialized object. Each key is a UUIDv4 string mapping to an object with optional fields: name, limit (number or "unlimited"), ips (array of IP/CIDR strings), userAgents (array with wildcard support), and allowedServices ("all" or array). ```typescript type KeyFileContents = Record< UUIDv4String, { name?: string, limit?: number | "unlimited", ips?: (CIDRString | IPString)[], userAgents?: string[], allowedServices?: "all" | string[], } >; ``` -------------------------------- ### Authorization header format Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Authentication is done by passing the Authorization header with the authentication scheme and token. The scheme and token are separated by a space. ```http Authorization: ``` -------------------------------- ### Require authentication with API_AUTH_REQUIRED Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md Sets API_AUTH_REQUIRED to 1 to always require authentication via API keys or turnstile. If only keys are configured, all requests without a valid key are refused. ```yaml environment: # ... other variables here ... API_AUTH_REQUIRED: 1 ``` -------------------------------- ### Bearer authentication header Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md Use the Bearer scheme with a JWT token issued by the server, typically after solving a turnstile challenge. Tokens are short-lived. ```http Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.