文档

简介

Tunelio API 让你在一次请求中就拿到任意 YouTube 视频或音频的直接下载 URL——没有队列,没有轮询,没有进度 webhook。整个接口面只有两个 endpoint:GET /info 用于元数据,GET /create 用于下载链接。

基础 URL:https://tunelio.dev。所有请求使用 TLS 1.2+。响应为 UTF-8 编码的 JSON。

心智模型

调用 /info 查看某个 URL 有哪些可用格式,然后带上选定的清晰度调用 /create。/create 的响应里包含一个指向我们 CDN tunnel 的 url——把它交给你的用户、你的下载器,或一个预签名的 S3 上传。没有第三步。

永远不轮询。如果你用过其他下载 API,可能习惯了 job ID 和 SSE 流。我们没有这些——每个请求都是请求/响应。

快速上手

认证

所有请求都需要一个作为 Bearer token 放在 Authorization 头里的 API 密钥。

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

先用 Telegram 登录(在 @TunelioDevBot 里一键完成——无需邮箱或密码),然后在控制台生成你的 API 密钥。整个流程约 60 秒,且不需要支付方式。

把密钥保存在服务端。任何拿到密钥的人都能花你的额度。绝不要把它嵌入浏览器打包文件或移动端二进制——请通过你自己的后端代理。

快速上手

快速开始

三行代码完成你的第一次调用。把密钥换成你自己的,URL 换成任意 YouTube 链接。

curl "https://tunelio.dev/create?quality=720p&url=https://youtu.be/dQw4w9WgXcQ" \
  -H "Authorization: Bearer tnl_…"

Endpoint

GET /info

解析一个 YouTube URL,返回完整的元数据——标题、时长、缩略图,以及每一种可用的视频和音频格式及其文件大小和分辨率。

Query 参数

urlstringrequired一个 YouTube URL:watch?v=、youtu.be/、/shorts/、/embed/ 或 /live/。这些都会被同样解析。

试一试

GETtunelio.dev/info

试一试 · 花费 6 credits

urlstring · 必填

GET tunelio.dev/info?url=https://youtu.be/dQw4w9WgXcQ

响应结构

titlestringVideo title as published.

duration_secondsintegerTotal length in seconds.

duration_strstringHuman-readable HH:MM:SS (or MM:SS when < 1h). Zero-padded.

thumbnailstring (URL)Highest-resolution thumbnail available.

formats[]array<Format>Every video format. See sub-fields below.

formats[].qualitystringHuman label: 144p, 240p, 360p, 480p, 720p, 1080p.

formats[].file_sizeinteger (bytes)Exact size in bytes.

formats[].file_size_strstringHuman-readable size — e.g. "84.50 MB" or "1.20 GB".

formats[].widthintegerEncoded frame width in pixels.

formats[].heightintegerEncoded frame height in pixels.

audioFormatobject<Audio>|nullThe best MP3 audio rendition — single object, or null if no audio track is available.

audioFormat.formatstringContainer — currently mp3.

audioFormat.file_sizeintegerExact MP3 size in bytes.

audioFormat.file_size_strstringHuman-readable MP3 size — e.g. "35.01 MB".

花费

每次调用 6 个额度。

Endpoint

GET /create

为选定的格式生成一个直接的、签名的 CDN 下载 URL。链接在同一个响应里返回——没有任务要轮询,没有 webhook 要监听。

Query 参数

urlstringrequiredYouTube URL——与 /info 支持的格式相同。

qualitystringrequired144p、240p、360p、480p、720p、1080p、2160p(仅 Mega)之一,或 mp3 表示音频。

试一试

GETtunelio.dev/create

试一试 · 花费 10 credits

urlstring · 必填

qualitystring · 必填

GET tunelio.dev/create?url=https://youtu.be/dQw4w9WgXcQ&quality=1080p

响应结构

urlstring (URL)Signed CDN tunnel URL. Hand to your user or pipe to storage.

filenamestringSuggested filename based on the video title and chosen format.

qualitystringEcho of your requested quality — e.g. 1080p or mp3.

modestring"video" or "audio".

typestring"merge" (video+audio muxed) or "single" (audio-only or pre-muxed).

expiresinteger (unix)Timestamp when the signed URL stops working — typically 6 hours out.

file_sizeintegerFinal file size in bytes.

file_size_strstringHuman-readable size — e.g. "84.50 MB".

statusstringAlways "tunnel" on success.

花费

每次调用 10 个额度。花费与文件大小无关——你付的是解析清晰度的工作,而不是字节。

字节不经过你的服务器。你的后端只看到那个很小的 JSON 响应。tunnel URL 直接从我们的 CDN 推流到你的终端用户。

Endpoint

GET /credits

返回你的剩余额度余额和当前生效方案。可用来在一批调用前检查还剩多少,或在你自己的控制台里展示余额。

没有 query 参数——只需你的 API 密钥。与其他地方一样的 Bearer token(或 X-API-Key 头)即可认证此调用。

试一试

GETtunelio.dev/credits

试一试 · 花费免费

GET tunelio.dev/credits

响应结构

creditsinteger剩余额度余额,整数。

planstring你当前生效的方案:trial、pro、ultra 或 mega。已失效的付费方案会报告为 trial。

响应头

同样的余额也会镜像在响应头里,与 /info 和 /create 一致——如果你想直接拿数字而不解析响应体,很方便:

X-Credits-Remainingint剩余额度余额。

X-Credits-Planstr你当前生效的方案名称。

花费

免费。查询余额从不消耗额度。

此 endpoint 只读且始终免费,所以你想轮询多频繁都行——比如在一大批调用之前——不花任何东西。

Endpoint

/tunnel

/tunnel 就是你从 /create 拿回来的那个 URL。你从不在代码里调用它——你把这个 URL 交给你的用户、你的 <a download> 标签、你的 S3 上传器、你的 Telegram 机器人等等。

它返回什么

文件本身——MP4 或 MP3——带有相应的 Content-Type 和 Content-Disposition: attachment; filename="…" 头。它支持 HTTP range 请求,所以视频播放器可以拖动进度,下载器可以断点续传。

认证

不需要。该 URL 用一个 exp 时间戳和一个 sig HMAC 自签名。过了 expires 之后,链接返回 410 Gone——再次调用 /create 拿一个新的。

花费

免费。带宽在合理范围内由我们承担——我们会限制滥用,但正常使用从不会触发。

参考

速率限制

速率限制按 API 密钥计算,以每分钟请求数衡量。它们按滑动窗口每 60 秒重置。Ultra 和 Mega 方案没有速率限制。

Trial15 req / min

Pro5 req / sec

Ultrano limit

Megano limit

超出限制会返回 429 Too Many Requests,并带有 Retry-After 头(单位为秒)。如果你经常触顶,请升级方案,而不是在客户端加退避——限制的存在是为了让你不会意外耗光额度。

参考

错误

所有错误响应都遵循同一种结构:

{
  "error": "invalid_url",
  "message": "Provided URL is not a recognised YouTube link."
}

状态码

400invalid_requestMissing or malformed parameter — usually a bad URL or unknown quality.

401unauthorizedMissing or invalid Bearer token.

402insufficient_creditsYour account is out of credits. Top up or upgrade.

404not_foundVideo does not exist, is private, or was deleted.

410goneYou called a /tunnel URL after its expires timestamp.

429rate_limitedPlan rate limit hit. Respect the Retry-After header.

500server_errorUnexpected on our side. Safe to retry with exponential backoff.

503upstream_changedYouTube changed something we hadn't patched yet. Usually self-heals within an hour.

参考

额度与计费

无论视频大小或时长,每次调用都花费固定数量的额度:

GET /info6 credits

GET /create10 credits

/tunnel downloadfree

一次典型的“获取信息,然后下载”往返是 16 个额度。新账户从 100 个免费额度起步。付费方案按月刷新,每个周期都重新发放额度。

失败的请求(4xx 和 5xx)不消耗额度——你只为成功的解析付费。

卡住了,或者缺了点什么?

在 Telegram 上联系我们 → @TunelioDevBot