External API Fallback

External API Fallback asks an outside service for the files of a video when a built-in module could not read it. The service must speak the API of Cobalt, the open-source downloader: the site sends it the link, and it answers with file addresses. It helps on shared hosting, where some platforms refuse the address of the server. The plugin is free and works with every licence.

When it is asked

The plugin answers the media_fallback hook, like the yt-dlp Bridge. Five modules call it when they give up: YouTube, Facebook, Instagram, TikTok and X. A link from a site that no module knows never reaches it.

When both plugins are on, yt-dlp is asked first and the external API only when yt-dlp found nothing. As long as External extractor API URL is empty, the plugin does nothing at all.

Setting it up

1. Admin → Plugins → External API Fallback → Enable.
2. On Settings → Advanced, fill in External extractor API URL: the address the requests are posted to, usually the root address of a Cobalt instance.
3. On the same tab, External extractor API key is sent as Authorization: Api-Key <your key>. Leave it empty for an instance that needs no key. A saved key is not shown again; tick Clear the saved external extractor api key to remove it.
4. Choose what to ask for under Admin → Plugins → External API Fallback → Settings:

What it sends and what comes back

For one link the site sends up to two requests, each allowed 30 seconds:

{"url": "<the link>", "videoQuality": "1080", "downloadMode": "auto"}
{"url": "<the link>", "downloadMode": "audio", "audioFormat": "mp3"}

The second one only when Also request an audio-only file is on. The answer decides what the visitor gets:

• tunnel, redirect, stream or success: one file. The first request gives a format called Video, the second one Audio (MP3). The title is taken from the file name.
• picker (a post with several pictures or videos): every item, as Video 1, Image 2 and so on, plus its sound when the service offers one; the first preview picture becomes the thumbnail.
• error or anything else: nothing, and the visitor gets the usual error message.

What the visitor sees

The usual results page, with fewer details than a module gives: no sizes, no resolutions and no duration, and a title made from the file name. On Platforms → Test a link the raw result of such a link says "via": "external-api".

Privacy and limits

• The link goes to someone else. Every link this plugin handles is sent to the operator of the API. Choose a service you trust; the safest is a Cobalt instance you run yourself.
• Cookies stay here. The cookies a visitor pastes for a private video are never sent to the API.
• Its own address. Requests to the API leave from the server's own address; the proxies of the platform are not used for them.
• Its own limits. A public instance may ask for a key, refuse your server or limit how often you ask. With a tunnel answer the file itself comes through the service's server, so its bandwidth and speed count too.
• Waiting time. Two requests of up to 30 seconds each can add a minute to a link that fails, and the module may try again over another route. A slow service makes visitors wait.

Tips

• Treat it as the last resort. Routes and proxies and yt-dlp give more: sizes and every resolution.
• The plugin is only asked when a module fails, so a link that works normally never shows it. When a link does fail, try it on Platforms → Test a link: a result that carries "via": "external-api" came from the API.
• When the service changes its address or key, update Settings → Advanced; the plugin itself needs no change.