LYRA DEVELOPER SPECIFICATION • v1.0

Lyra API Documentation

High-speed song search, direct audio streaming URLs, and download endpoints engineered specifically for Py-TgCalls Telegram music bots.

Get Real API Key Live Server

Production Base URL

All requests are served over high-speed HTTPS:

https://api.shnwaz.dev/api/v1

Authentication

Pass your API key as a query param or request header:

Query: ?api_key=8fLyra1d4a

Header: x-api-key: 8fLyra1d4a

Unlimited Engine

Zero rate limits, 999,999,999 requests quota enabled:

UNLIMITED_MODEACTIVE

Full Implementation Examples

import httpx
from pyrogram import Client, filters
from pytgcalls import PyTgCalls
from pytgcalls.types import AudioPiped

app = Client("my_bot", api_id=12345, api_hash="your_api_hash", bot_token="your_bot_token")
call_py = PyTgCalls(app)

LYRA_STREAM_URL = "https://api.shnwaz.dev/api/v1/stream"
LYRA_KEY = "8fLyra1d4a"

@app.on_message(filters.command("play") & filters.group)
async def play_handler(_, message):
    query = " ".join(message.command[1:])
    if not query:
        return await message.reply_text("Please provide a song name or YouTube link.")

    status_msg = await message.reply_text("⚡ Fetching audio stream via Lyra API...")

    async with httpx.AsyncClient() as client:
        res = await client.get(
            LYRA_STREAM_URL,
            params={"id": query, "api_key": LYRA_KEY},
            timeout=10.0
        )
        data = res.json()

    if data.get("status") != "success":
        return await status_msg.edit_text("❌ Failed to resolve music stream.")

    stream_url = data["stream_url"]
    song_title = data["title"]
    duration = data["duration"]

    # Direct audio stream into Telegram Voice Chat (zero local ffmpeg load)
    await call_py.join_group_call(
        message.chat.id,
        AudioPiped(stream_url)
    )

    await status_msg.edit_text(
        f"▶️ **Now Playing:** {song_title}\n⏱ **Duration:** {duration}\n⚡ **Latency:** {data['latency_ms']}ms"
    )

API Endpoints Reference

Detailed specifications and response structures

GET/api/v1/search

Search Music & Videos

Fast YouTube / YouTube Music search with titles, durations, video IDs, thumbnails, and channel names.

Parameters

Parameter	Type	Required	Description
query	string	Yes	Song name, artist, YouTube URL, or Spotify link
limit	integer	No	Number of search results to return (default: 10, max: 25)

Example 200 OK Response

{
  "status": "success",
  "query": "Alan Walker Faded",
  "count": 10,
  "results": [
    {
      "id": "60ItHLz5WEA",
      "title": "Alan Walker - Faded",
      "duration": "03:32",
      "channel": "Alan Walker",
      "thumbnail": "https://i.ytimg.com/vi/60ItHLz5WEA/hq720.jpg",
      "views": "3.6B views",
      "url": "https://www.youtube.com/watch?v=60ItHLz5WEA"
    }
  ]
}

GET/api/v1/stream

Extract Direct Audio Stream (Py-TgCalls)

Resolves direct high-speed audio stream URLs (.m4a / .webm) ready for Telegram Voice Chats without local CPU transcoding.

Parameters

Parameter	Type	Required	Description
id	string	Yes	YouTube 11-char Video ID, full YouTube URL, or search query
quality	string	No	'best', 'high', or 'low' (default: 'best')
api_key	string	Yes	Your Lyra API key (e.g. 8fLyra1d4a)

Example 200 OK Response

{
  "status": "success",
  "id": "60ItHLz5WEA",
  "title": "Alan Walker - Faded",
  "channel": "Alan Walker",
  "duration": "03:32",
  "duration_seconds": 212,
  "thumbnail": "https://i.ytimg.com/vi/60ItHLz5WEA/maxresdefault.jpg",
  "stream_url": "https://rr3---sn-gwpa-25ued.googlevideo.com/videoplayback?...",
  "proxy_stream_url": "https://api.shnwaz.dev/api/v1/stream/raw?id=60ItHLz5WEA&api_key=8fLyra1d4a",
  "format": "m4a",
  "bitrate": 128.0,
  "filesize": 3418520,
  "latency_ms": 14.2
}

GET/api/v1/stream/raw

Raw Chunked Audio Pipe

Direct chunked binary audio stream over HTTP. Use if you want Lyra to proxy and stream the audio data directly to your client.

Parameters

Parameter	Type	Required	Description
id	string	Yes	YouTube Video ID or URL
api_key	string	Yes	Your Lyra API key

Example 200 OK Response

[Binary Chunked Audio Stream (audio/mp4 / audio/webm)]

GET/api/v1/download

Download Audio Track

Direct file download attachment header with proper song filename, allowing users to save the file instantly.

Parameters

Parameter	Type	Required	Description
id	string	Yes	YouTube Video ID or URL
api_key	string	Yes	Your Lyra API key

Example 200 OK Response

[Binary Audio File with Content-Disposition: attachment; filename="Song_Name.m4a"]

POST/api/v1/keys/generate

Generate API Key

Creates a new API key in the format: 8fLyra1d4a with unlimited quota.

Parameters

Parameter	Type	Required	Description
email	string (body)	Yes	Developer's email address
name	string (body)	No	Friendly name / label for the key
plan	string (body)	No	'unlimited' (default)

Example 200 OK Response

{
  "status": "success",
  "key": "8fLyra1d4a",
  "user_email": "developer@shnwaz.dev",
  "user_name": "My Telegram Music Bot",
  "plan": "unlimited",
  "daily_requests_limit": 999999999,
  "daily_video_limit": 999999999,
  "expires_at": "2027-09-28T18:00:00Z",
  "is_active": true
}

GET/api/v1/keys/usage

Check API Key Usage & Status

Inspect real-time daily quota consumption and expiry.

Parameters

Parameter	Type	Required	Description
key	string	Yes	Your Lyra API Key

Example 200 OK Response

{
  "status": "success",
  "key": "8fLyra1d4a",
  "plan": "unlimited",
  "requests_today": 12,
  "daily_requests_limit": 999999999,
  "video_requests_today": 0,
  "daily_video_limit": 999999999,
  "expires_at": "2027-09-28T18:00:00Z",
  "percent_used": 0.0
}