文档

简介

Tunelio API 提供 YouTube 视频和音频直连、丰富的媒体元数据以及带时间戳的转录文本。下载链接在同一个请求中返回——无需队列、轮询或进度 webhook。

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

心智模型

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

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

快速上手

认证

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

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

通过 Telegram（在我们的机器人中一键完成）或邮箱注册登录，然后在控制台生成你的 API 密钥。整个流程约 60 秒，且不需要支付方式。

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

快速上手

快速开始

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

1. Download Streams (/create)

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

2. YouTube Transcripts & Subtitles (/transcript)

Extract full timestamped text, auto vs manual subtitles, SRT, VTT, or plain text without bot detection walls (6 credits).

curl -X GET "https://tunelio.dev/transcript?url=dQw4w9WgXcQ&lang=en&format=json" \
  -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

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

Query 参数

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

qualitystringrequired144p、240p、360p、480p、720p、1080p、2160p(仅 Mega)之一,或 mp3 表示音频,或 opus 表示原始 Opus 音频(不重新编码)。

audioBitrateintegeroptional可选。仅在 quality=opus 时使用 — 按 kbps 选择最接近的原生 Opus 码率档位(例如 64)。其他质量下会被忽略。

试一试

GETtunelio.dev/create

试一试 · 花费 10 credits

urlstring · 必填

qualitystring · 必填

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

响应结构

urlstring (URL)Signed stream 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, mp3, or opus.

modestring"video" or "audio".

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".

statusstring"ok" on success — otherwise the error message.

花费

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

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

Endpoint

GET /transcript

Fetch full transcripts and subtitles for any YouTube video with timestamps, language selection, and manual vs. auto-generated indicators.

Query 参数

urlstringrequiredYouTube watch, shorts, embed, youtu.be URL or 11-char Video ID.

langstringoptionalTarget language code (e.g. en, es, de, ja). Defaults to en.

typestringoptionalFilter by type: any (prefers manual), manual, or auto.

formatstringoptionalOutput format: json (default), text, srt, or vtt.

试一试

GETtunelio.dev/transcript

试一试 · 花费 6 credits

urlstring · 必填

langstring

formatstring

GET tunelio.dev/transcript?url=https://youtu.be/dQw4w9WgXcQ&lang=en&format=json

响应结构

video_idstringThe 11-character YouTube video ID.

titlestringTitle of the YouTube video.

languagestringSelected language code.

language_namestringDisplay name of selected language.

is_generatedbooleanTrue if auto-generated ASR, false if manually uploaded.

typestring"manual" or "auto".

available_languagesarray<Language>List of all available subtitle/transcript tracks.

segments_countintegerNumber of timed text segments.

segmentsarray<Segment>Array of { start, duration, text } objects.

full_textstringComplete continuous text of the transcript.

statusstring"ok" on success.

花费

Extracting a transcript costs 6 credits per unique video request. Cached repeats respond in under 5ms.

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 拿一个新的。

花费

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

Repackaging

By default /tunnel streams the file as it is built — right for a download, wrong for a player: there is no Range and no length known up front. Add one of these to the same link to get the same media packaged differently. The link does not change, nothing extra is charged, and the result is built once and then cached.

&progressive=1A plain, non-fragmented mp4: moov first, exact Content-Length, full Range and seeking. This is the shape iOS and AVPlayer want.

&start=90&end=100Only that slice, as a progressive mp4. The start snaps back to the nearest keyframe — the same as ffmpeg -ss -c copy — so a clip can begin a few seconds early. The end is exact.

&hls=1An HLS playlist (application/vnd.apple.mpegurl) over the same media, for AVFoundation’s native path. Its entries point back at /tunnel with &hls=data.

Repackaging applies to merged mp4 downloads. Audio-only and other formats answer 400, a clip combined with hls answers 400, and a file too large to build answers 413 — download it normally instead.

参考

速率限制

速率限制按 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