सामग्री पर जाएँ
दस्तावेज़

परिचय

Tunelio API आपको एक ही रिक्वेस्ट में किसी भी YouTube वीडियो या ऑडियो के लिए सीधा डाउनलोड URL देता है — कोई कतार नहीं, कोई polling नहीं, कोई progress webhook नहीं। पूरा API बस दो endpoint है: मेटाडेटा के लिए GET /info, डाउनलोड लिंक के लिए GET /create।

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

मानसिक मॉडल

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

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

ऑथेंटिकेशन

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

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

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

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

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

तीन पंक्तियों में अपनी पहली कॉल करें। key को अपनी से और URL को किसी भी YouTube लिंक से बदलें।

curl "https://tunelio.dev/create?quality=720p&url=https://youtu.be/dQw4w9WgXcQ" \
  -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
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

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

Query पैरामीटर

urlstringrequiredYouTube URL — /info जैसे ही फ़ॉर्मैट।
qualitystringrequired144p, 240p, 360p, 480p, 720p, 1080p, 2160p (सिर्फ़ Mega), या ऑडियो के लिए mp3 में से एक।

आज़माएँ

GETtunelio.dev/create
आज़माएँ · लागत 10 credits
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 से आपके अंतिम-यूज़र तक स्ट्रीम होता है।
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 कॉल करें।

लागत

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

संदर्भ

रेट लिमिट

रेट लिमिट प्रति API key होती हैं, प्रति मिनट रिक्वेस्ट में मापी जाती हैं। वे एक रोलिंग विंडो पर हर 60 सेकंड में रीसेट होती हैं। 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