Introduction

The Tunelio API gives you a direct download URL for any YouTube video or audio in a single request — no queues, no polling, no progress webhooks. The whole surface is two endpoints: GET /info for metadata, GET /create for the download link.

Base URL: https://tunelio.dev. All requests use TLS 1.2+. Responses are JSON with UTF-8 encoding.

Mental model

Call /info to see what formats are available for a given URL, then call /create with the chosen quality. The response from /create contains a url that points to our CDN tunnel — hand that to your user, your downloader, or a presigned S3 upload. There's no step three.

Authentication

All requests require an API key sent as a Bearer token in the Authorization header.

Authorization: Bearer tnl_8f3a92b1c4d5e6f7a8b9c0d1e2f3a4b5

Sign in with Telegram (one tap with @TunelioDevBot — no email or password), then generate your API key from the Dashboard. The whole flow takes about 60 seconds and doesn't require a payment method.

Quickstart

Make your first call in three lines. Replace the key with your own and the URL with any YouTube link.

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

GET /info

Resolves a YouTube URL and returns the full metadata — title, duration, thumbnail, and every available video and audio format with file sizes and dimensions.

Query parameters

Try it

Response shape

Cost

6 credits per call. Cached identical URLs return for free within 30 minutes.

GET /create

Generates a direct, signed CDN download URL for a chosen format. The link comes back in the same response — there's no job to poll, no webhook to listen for.

Query parameters

Try it

Response shape

Cost

10 credits per call. The cost is the same regardless of file size — you pay for the resolution work, not the bytes.

GET /credits

Returns your remaining credit balance and effective plan. Use it to check how much you have left before a batch of calls, or to surface a balance in your own dashboard.

No query parameters — just your API key. The same Bearer token (or X-API-Key header) used everywhere else authenticates this call.

Try it

Response shape

Response headers

The same balance is mirrored in response headers, matching /info and /create — handy if you want the numbers without parsing the body:

Cost

Free. Checking your balance never consumes credits.

/tunnel

/tunnel is the URL you get back from /create. You never call it from your code — you hand the URL to your user, your <a download> tag, your S3 uploader, your Telegram bot, etc.

What it returns

The actual file — MP4 or MP3 — with appropriate Content-Type and Content-Disposition: attachment; filename="…" headers. It supports HTTP range requests, so video players can seek and downloaders can resume.

Authentication

None. The URL is self-signed with an exp timestamp and a sig HMAC. After expires passes, the link returns 410 Gone — call /create again for a fresh one.

Costs

Free. Bandwidth is on us within reason — we throttle abuse but normal use never triggers it.

Rate limits

Rate limits are per API key, measured in requests per minute. They reset every 60 seconds on a rolling window. Ultra and Mega plans have no rate limit.

Exceeding the limit returns 429 Too Many Requests with a Retry-After header (in seconds). If you regularly bump the ceiling, upgrade rather than adding client-side backoff — limits exist so you don't accidentally drain your credits.

Errors

All error responses follow the same shape:

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

Status codes

Credits & billing

Every call costs a fixed number of credits regardless of video size or duration:

A typical "fetch info, then download" round-trip is 16 credits. New accounts start with 100 free credits. Paid plans refresh monthly with fresh credits each cycle.

Failed requests (4xx and 5xx) do not consume credits — you're only billed for successful resolutions.