download-video

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Download Video (agent-first)

下载视频（Agent优先）

Turn a social post URL into a downloadable video. The whole flow is one hosted API call — no browser, no login, no watermark, no yt-dlp install. It returns direct CDN MP4 URLs for every quality (up to 1080p) plus author/caption/metadata, and can stream the file straight to disk.

将社交帖子链接转换为可下载的视频。整个流程只需一次托管API调用——无需浏览器、无需登录、无水印、无需安装yt-dlp。它会返回所有画质（最高1080p）的CDN直接MP4链接，以及作者/标题/元数据，还可直接将文件流式传输到磁盘。

When to use

使用场景

User pastes a Twitter/X, TikTok, Instagram, or YouTube post link and wants the video, the MP4 URL, a GIF, or the images.
User says "download / save / grab / rip this video", "get the highest quality", "download without watermark", or "just give me the direct link".
An agent needs a video file (or its CDN URL) to feed into another step.

用户粘贴Twitter/X、TikTok、Instagram或YouTube的帖子链接，想要获取视频、MP4链接、GIF或图片。
用户说出“下载/保存/获取/提取这个视频”“获取最高画质”“无水印下载”或“直接给我链接”。
Agent需要视频文件（或其CDN链接）用于后续步骤。

How it works (routing)

工作原理（路由）

There is one host per platform, and each host serves only its own platform. The helper script detects the platform from the URL and routes automatically — you normally don't pick the host yourself:

Platform	Host
Twitter / X	`https://download-twitter-video.drummerduck.com`
TikTok	`https://download-tktk-video.drummerduck.com`
Instagram	`https://download-instagram-video.drummerduck.com`
YouTube	`https://download-youtube-video.drummerduck.com`

Sending a TikTok link to the Twitter host returns

INVALID_URL

— always match the link to its platform host (the script does this for you).

每个平台对应一个独立的主机，每个主机仅服务对应的平台。辅助脚本会从链接中检测平台并自动路由——通常无需手动选择主机：

平台	主机
Twitter / X	`https://download-twitter-video.drummerduck.com`
TikTok	`https://download-tktk-video.drummerduck.com`
Instagram	`https://download-instagram-video.drummerduck.com`
YouTube	`https://download-youtube-video.drummerduck.com`

将TikTok链接发送到Twitter主机会返回

INVALID_URL

——务必确保链接与对应平台的主机匹配（脚本会自动完成此操作）。

Step 1 — The fast path (script)

步骤1 — 快速路径（脚本）

bash

scripts/dl.sh <post-url> [options]

```
scripts/dl.sh <url>
```
— download the best-quality MP4 into the current dir, using the server-provided filename (
```
<handle>-<id>-<quality>.mp4
```
).
```
--info
```
— print compact metadata + the list of available qualities (run this first if the user wants a specific resolution — labels differ per post).
```
--json
```
— print the full result JSON (every media item and variant URL).
```
--quality 720p
```
— pick a specific variant label (falls back to best if that label isn't offered for this post).
```
--n 2
```
— pick the Nth media item in a multi-photo/video post.
```
--out ./clips/
```
(a dir) or
```
--out ./clip.mp4
```
(a file) — where to save.
```
--key <KEY>
```
(or
```
DXV_API_KEY
```
env) — API key for higher limits (see Limits).
```
--host http://localhost:3000
```
— hit a specific deployment; skips routing.

Examples:

bash

undefined

bash

scripts/dl.sh <post-url> [options]

```
scripts/dl.sh <url>
```
— 将最佳画质MP4下载到当前目录，使用服务器提供的文件名（
```
<handle>-<id>-<quality>.mp4
```
）。
```
--info
```
— 打印简洁元数据+可用画质列表（如果用户需要特定分辨率，建议先运行此命令——不同帖子的画质标签可能不同）。
```
--json
```
— 打印完整结果JSON（所有媒体项和版本链接）。
```
--quality 720p
```
— 选择特定版本标签（如果该帖子不提供此标签，则自动 fallback 到最佳画质）。
```
--n 2
```
— 选择多图/视频帖子中的第N个媒体项。
```
--out ./clips/
```
（目录）或
```
--out ./clip.mp4
```
（文件）——指定保存位置。
```
--key <KEY>
```
（或
```
DXV_API_KEY
```
环境变量）——用于提升调用限制的API密钥（参见限制部分）。
```
--host http://localhost:3000
```
— 指定特定部署地址；跳过路由。

示例：

bash

undefined

Best quality, into ./

最佳画质，下载到当前目录

scripts/dl.sh "https://x.com/SpaceX/status/1732824684683784516"

See what's available first, then grab 720p into a folder

先查看可用选项，再将720p画质视频下载到指定文件夹

scripts/dl.sh "https://www.tiktok.com/@user/video/1234567890" --info scripts/dl.sh "https://www.tiktok.com/@user/video/1234567890" --quality 720p --out ./clips/

Just the direct MP4 URLs, no download (pipe to jq etc.)

仅获取直接MP4链接，不下载（可通过管道传递给jq等工具）

scripts/dl.sh "https://www.instagram.com/reel/Cxyz/" --json


The script needs only `curl`. `jq` or `python3`, if present, make `--json`/`--info`
output pretty and handle URL-encoding — but it degrades gracefully without them.

scripts/dl.sh "https://www.instagram.com/reel/Cxyz/" --json


该脚本仅依赖`curl`。如果存在`jq`或`python3`，可让`--json`/`--info`的输出更美观，并处理URL编码——但即使没有这些工具，脚本也能正常运行。

Step 2 — Or call the API directly

步骤2 — 直接调用API

No script needed — it's a plain HTTP API. Two endpoints per host:

GET|POST /api/extract
→ JSON metadata + all variant URLs (you download the CDN URL yourself, or hand it to the user):

bash

curl "https://download-twitter-video.drummerduck.com/api/extract?url=<POST_URL>"

无需脚本——这是一个普通HTTP API。每个主机包含两个端点：

GET|POST /api/extract
→ 返回JSON元数据+所有版本链接（需自行下载CDN链接内容，或直接提供给用户）：

bash

curl "https://download-twitter-video.drummerduck.com/api/extract?url=<POST_URL>"

POST form:

POST表单方式：

curl -X POST -H "content-type: application/json"
-d '{"url":"<POST_URL>"}'
https://download-twitter-video.drummerduck.com/api/extract

Response: `{ "ok": true, "data": { source, id, url, author{name,handle,avatar},
text, createdAt, thumbnail, engine, media: [ { type, poster, durationMs, width,
height, variants: [ { quality, width, height, bitrate, container, mimeType, url,
size } ] } ] } }`. Variants are sorted best-first; `url` is a direct CDN link.

**`GET /api/download`** → streams the actual file as an attachment (this is what
`dl.sh` uses). Params: `url` (required), `quality` (optional label), `n`
(optional media index):
```bash
curl -OJ "https://download-tktk-video.drummerduck.com/api/download?url=<POST_URL>&quality=720p"

Errors come back as

{ "ok": false, "error": { "code", "message" } }

—

INVALID_URL

(wrong platform or unparseable),

NO_MEDIA

(post has no video),

RATE_LIMITED

(see below),

BLOCKED

UPSTREAM_ERROR

INTERNAL

curl -X POST -H "content-type: application/json"
-d '{"url":"<POST_URL>"}'
https://download-twitter-video.drummerduck.com/api/extract

响应格式：`{ "ok": true, "data": { source, id, url, author{name,handle,avatar},
text, createdAt, thumbnail, engine, media: [ { type, poster, durationMs, width,
height, variants: [ { quality, width, height, bitrate, container, mimeType, url,
size } ] } ] } }`。版本按画质从优到劣排序；`url`为CDN直接链接。

**`GET /api/download`** → 将实际文件作为附件流式传输（`dl.sh`脚本即使用此端点）。参数：`url`（必填）、`quality`（可选标签）、`n`（可选媒体项索引）：
```bash
curl -OJ "https://download-tktk-video.drummerduck.com/api/download?url=<POST_URL>&quality=720p"

错误响应格式为

{ "ok": false, "error": { "code", "message" } }

——包括

INVALID_URL

（错误平台或无法解析链接）、

NO_MEDIA

（帖子无视频）、

RATE_LIMITED

（参见下文）、

BLOCKED

、

UPSTREAM_ERROR

、

INTERNAL

。

Step 3 — Or wire it as an MCP server

步骤3 — 接入为MCP服务器

Each host also exposes a streamable-HTTP MCP server at

/api/mcp

. Add the one(s) you need:

json

{
  "mcpServers": {
    "twitter-video":  { "type": "http", "url": "https://download-twitter-video.drummerduck.com/api/mcp" },
    "tiktok-video":   { "type": "http", "url": "https://download-tktk-video.drummerduck.com/api/mcp" },
    "instagram-video":{ "type": "http", "url": "https://download-instagram-video.drummerduck.com/api/mcp" },
    "youtube-video":  { "type": "http", "url": "https://download-youtube-video.drummerduck.com/api/mcp" }
  }
}

Tools (named per platform):

extract_<platform>_video

(full media + URLs),

get_<platform>_info

(metadata only), and

get_free_api_key

(mint a key).

每个主机还在

/api/mcp

路径提供可流式传输的HTTP MCP服务器。按需添加所需服务器：

json

{
  "mcpServers": {
    "twitter-video":  { "type": "http", "url": "https://download-twitter-video.drummerduck.com/api/mcp" },
    "tiktok-video":   { "type": "http", "url": "https://download-tktk-video.drummerduck.com/api/mcp" },
    "instagram-video":{ "type": "http", "url": "https://download-instagram-video.drummerduck.com/api/mcp" },
    "youtube-video":  { "type": "http", "url": "https://download-youtube-video.drummerduck.com/api/mcp" }
  }
}

工具（按平台命名）：

extract_<platform>_video

（完整媒体+链接）、

get_<platform>_info

（仅元数据）和

get_free_api_key

（生成密钥）。

Limits & API keys

限制与API密钥

Anonymous: ~30 requests/hour per IP.
Free key: ~300/hour, 2000/day. Mint one (no signup) and reuse it:
bash
```
curl -X POST -H "content-type: application/json" -d '{"label":"my-bot"}' \
  https://download-twitter-video.drummerduck.com/api/keys
```
Save the returned key (shown once) and send it as
```
Authorization: Bearer <KEY>
```
(or
```
X-API-Key: <KEY>
```
), or export
```
DXV_API_KEY
```
for the script.
```
GET /api/keys
```
is self-documenting and, with a key, reports that key's tier/limits.

Rate-limit state is on

x-ratelimit-limit

x-ratelimit-remaining

x-ratelimit-reset

response headers; a

RATE_LIMITED

error includes

retry-after

匿名用户：每IP约30次请求/小时。
免费密钥：约300次/小时，2000次/天。无需注册即可生成并重复使用：
bash
```
curl -X POST -H "content-type: application/json" -d '{"label":"my-bot"}' \
  https://download-twitter-video.drummerduck.com/api/keys
```
保存返回的密钥（仅显示一次），并通过
```
Authorization: Bearer <KEY>
```
（或
```
X-API-Key: <KEY>
```
）发送，或为脚本设置
```
DXV_API_KEY
```
环境变量。
```
GET /api/keys
```
可自行查看文档，使用密钥时会返回该密钥的等级/限制信息。

速率限制状态包含在响应头

x-ratelimit-limit

x-ratelimit-remaining

x-ratelimit-reset

中；

RATE_LIMITED

错误会包含

retry-after

字段。

Verify

验证

Confirm the saved file exists and is non-trivial in size, or that the printed variant URLs resolve.
If the user wanted a specific resolution, check
```
--info
```
first — available quality labels (e.g.
```
1080p
```
,
```
720p
```
,
```
360p
```
) vary per post; an unavailable label silently falls back to best.
Report which platform host was used and the quality actually downloaded.

确认保存的文件存在且大小合理，或打印的版本链接可正常访问。
如果用户需要特定分辨率，先查看
```
--info
```
的结果——可用画质标签（如
```
1080p
```
、
```
720p
```
、
```
360p
```
）因帖子而异；若标签不可用，会自动 fallback 到最佳画质。
告知用户使用的平台主机以及实际下载的画质。

Provenance

来源

Public hosted API — no auth required to extract:

GET|POST /api/extract

GET /api/download

POST /api/keys

, MCP at

/api/mcp

— on the four

download-*-video.drummerduck.com

hosts above.

Built from the private source project
```
mewc/download-x-video
```
(the Next.js app behind these hosts). This skill calls only the public website API — it contains no private source, keys, or internal endpoints.

公开托管API——提取操作无需授权：
- ```
GET|POST /api/extract
```
  、
```
GET /api/download
```
  、
```
POST /api/keys
```
  以及
```
/api/mcp
```
  路径的MCP服务器——均部署在上述四个
```
download-*-video.drummerduck.com
```
  主机上。
基于私有源项目
```
mewc/download-x-video
```
构建（即这些主机背后的Next.js应用）。本工具仅调用公开网站API——不包含任何私有源码、密钥或内部端点。