दस्तावेज़

परिचय

Tunelio API सीधे YouTube वीडियो और ऑडियो URL, विस्तृत मीडिया मेटाडेटा और टाइमस्टैम्प वाले ट्रांसक्रिप्ट देता है। डाउनलोड लिंक उसी रिक्वेस्ट में लौटता है — कोई कतार, polling या progress webhook नहीं।

बेस URL: https://tunelio.dev. सभी रिक्वेस्ट TLS 1.2+ का उपयोग करती हैं। जवाब UTF-8 एन्कोडिंग के साथ JSON होते हैं।

मानसिक मॉडल

किसी दिए गए URL के लिए कौन-से फ़ॉर्मैट उपलब्ध हैं यह देखने के लिए /info कॉल करें, फिर चुनी गई क्वालिटी के साथ /create कॉल करें। /create का जवाब एक url रखता है जो हमारे stream tunnel की ओर इशारा करता है — इसे अपने यूज़र, अपने डाउनलोडर या एक presigned S3 अपलोड को सौंप दें। तीसरा कोई चरण नहीं है।

कभी कोई polling नहीं। अगर आपने दूसरे download API इस्तेमाल किए हैं तो आप शायद job ID और SSE स्ट्रीम के आदी हों। हमारे पास वे नहीं हैं — हर रिक्वेस्ट request/response है।

शुरुआत करें

ऑथेंटिकेशन

सभी रिक्वेस्ट को Authorization हेडर में Bearer टोकन के रूप में भेजी गई एक API key चाहिए।

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

Telegram (हमारे बॉट के साथ एक टैप) का उपयोग करके साइन इन करें या अपने ईमेल पते से पंजीकरण करें, फिर Dashboard से अपनी API key बनाएँ। पूरी प्रक्रिया में लगभग 60 सेकंड लगते हैं और किसी भुगतान तरीके की ज़रूरत नहीं होती।

अपनी key को सर्वर-साइड रखें। key रखने वाला कोई भी व्यक्ति आपके क्रेडिट खर्च कर सकता है। इसे कभी किसी ब्राउज़र बंडल या मोबाइल बाइनरी में एम्बेड न करें — अपने ख़ुद के बैकएंड के ज़रिए प्रॉक्सी करें।

शुरुआत करें

क्विकस्टार्ट

तीन पंक्तियों में अपनी पहली कॉल करें। key को अपनी से और 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_…"

Endpoints

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 क्रेडिट।

Endpoints

GET /create

एक चुने गए फ़ॉर्मैट के लिए एक सीधा, हस्ताक्षरित डाउनलोड URL बनाता है। लिंक उसी जवाब में वापस आता है — न तो कोई job poll करने के लिए, न कोई webhook सुनने के लिए।

Query पैरामीटर

urlstringrequiredYouTube URL — /info जैसे ही फ़ॉर्मैट।

qualitystringrequired144p, 240p, 360p, 480p, 720p, 1080p, 2160p (सिर्फ़ Mega), ऑडियो के लिए mp3, मूल AAC ऑडियो के लिए m4a, या रॉ Opus ऑडियो के लिए opus में से एक। m4a और opus री-एन्कोड नहीं होते, इसलिए ये बहुत तेज़ी से डाउनलोड होते हैं और Range सपोर्ट करते हैं।

audioBitrateintegeroptionalवैकल्पिक। सिर्फ़ quality=opus के साथ उपयोग होता है — kbps में निकटतम नेटिव Opus बिटरेट टियर चुनता है (जैसे 64)। बाकी क्वालिटी के लिए अनदेखा किया जाता है।

ऑडियो फ़ॉर्मेट

ऑडियो के लिए m4a या opus चुनें, जब तक आपको खास तौर पर mp3 की ज़रूरत न हो। ये वीडियो का मूल ऑडियो ट्रैक हैं, जो बिना री-एन्कोड किए जैसे के तैसे भेजे जाते हैं, इसलिए mp3 से बहुत तेज़ी से डाउनलोड होते हैं और सटीक Content-Length तथा Range सपोर्ट के साथ आते हैं। mp3 डाउनलोड के दौरान ही एन्कोड होता है, इसलिए यह सबसे धीमा विकल्प है।

आज़माएँ

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, m4a 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 सीधे हमारे सर्वर से आपके अंतिम-यूज़र तक स्ट्रीम होता है।

Endpoints

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.

Endpoints

GET /credits

आपका शेष क्रेडिट बैलेंस और प्रभावी प्लान लौटाता है। कॉल के एक बैच से पहले यह जाँचने के लिए इसका उपयोग करें कि आपके पास कितना बचा है, या अपने ख़ुद के डैशबोर्ड में एक बैलेंस दिखाने के लिए।

कोई query पैरामीटर नहीं — बस आपकी API key। वही Bearer टोकन (या 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 सिर्फ़-पढ़ने वाला और हमेशा मुफ़्त है, इसलिए आप इसे जितनी बार चाहें poll कर सकते हैं — उदाहरण के लिए एक बड़े बैच से पहले — बिना कुछ खर्च किए।

Endpoints

/tunnel

/tunnel वह URL है जो आपको /create से वापस मिलता है। आप इसे कभी अपने कोड से कॉल नहीं करते — आप URL को अपने यूज़र, अपने <a download> टैग, अपने S3 अपलोडर, अपने Telegram बॉट आदि को सौंपते हैं।

यह क्या लौटाता है

असली फ़ाइल — MP4 या MP3 — उपयुक्त Content-Type और Content-Disposition: attachment; filename="…" हेडर के साथ। यह HTTP range रिक्वेस्ट सपोर्ट करता है, इसलिए वीडियो प्लेयर सीक कर सकते हैं और डाउनलोडर फिर से शुरू कर सकते हैं।

ऑथेंटिकेशन

कोई नहीं। URL एक exp टाइमस्टैम्प और एक sig HMAC के साथ स्वयं-हस्ताक्षरित है। expires बीत जाने के बाद, लिंक 410 Gone लौटाता है — एक नए के लिए फिर से /create कॉल करें।

लागत

मुफ़्त। उचित सीमा के भीतर बैंडविड्थ हमारी ओर से है — हम दुरुपयोग को सीमित करते हैं, लेकिन सामान्य उपयोग इसे कभी ट्रिगर नहीं करता।

Repackaging

Audio asked for as m4a or opus is the published track itself: /tunnel sends it with an exact Content-Length and answers Range with 206, so a download can resume or seek; one request already runs at full speed. mp3 is encoded while it streams, so it downloads several times slower, with no Range and no length known up front — prefer m4a or opus when speed matters.

Video is likewise streamed as it is built — right for a download, wrong for a player. 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. On audio, progressive=1 changes nothing and a clip or hls answers 400. A clip combined with hls answers 400, and a file too large to build answers 413 — download it normally instead.

संदर्भ

रेट लिमिट

रेट लिमिट प्रति API key होती हैं, प्रति मिनट रिक्वेस्ट में मापी जाती हैं। वे एक रोलिंग विंडो पर हर 60 सेकंड में रीसेट होती हैं। सिर्फ़ मुफ़्त Trial प्लान पर लिमिट है (प्रति मिनट 15 रिक्वेस्ट); Pro, Ultra और Mega प्लान पर कोई रेट लिमिट नहीं है।

Trial15 req / min

Pro5 req / sec

Ultrano limit

Megano limit

सीमा पार करने पर एक Retry-After हेडर (सेकंड में) के साथ 429 Too Many Requests लौटता है। अगर आप नियमित रूप से ऊपरी सीमा तक पहुँचते हैं, तो क्लाइंट-साइड backoff जोड़ने के बजाय अपग्रेड करें — सीमाएँ इसलिए हैं ताकि आप ग़लती से अपने क्रेडिट न ख़त्म कर लें।

संदर्भ

त्रुटियाँ

सभी त्रुटि जवाब एक ही स्वरूप का पालन करते हैं:

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

एक सामान्य "info लाएँ, फिर डाउनलोड करें" राउंड-ट्रिप 16 क्रेडिट का होता है। नए अकाउंट 100 मुफ़्त क्रेडिट के साथ शुरू होते हैं। सशुल्क प्लान हर महीने नए क्रेडिट के साथ ताज़ा होते हैं। बचे हुए क्रेडिट चक्र के अंत में समाप्त हो जाते हैं, जबकि वॉलेट का पैसा कभी समाप्त नहीं होता।

विफल रिक्वेस्ट (4xx और 5xx) क्रेडिट खर्च नहीं करतीं — आपसे सिर्फ़ सफल रिज़ॉल्यूशन का बिल लिया जाता है।

अटक गए या कुछ छूट रहा है?

हमें Telegram पर संदेश भेजें → @TunelioDevBot