Developer Documentation

The authoritative API reference and integration manual for the MeowAPI & YukiBots high-speed audio delivery mesh. Built specifically for Telegram Voice Chat bots (VPlay), music apps, and high-concurrency stream distribution.

Production Cluster Status

Syncing telemetry...

Primary Gateway (api1)

api.yukibots.me ...

Secondary Gateway (api2)

api2.yukibots.me ...

Global Edge Cluster (api3)

api3.yukibots.me ...

1. Architecture Overview

MeowAPI provides a multi-gateway, hyper-memory media extraction and distribution infrastructure. Static audio streams are ingested through global edge nodes and stored with 1-year immutable caching (public, max-age=31536000, immutable), providing sub-35ms delivery latencies on repeat stream requests.

Zero Server Load: All media streams support standard HTTP Range Requests (Accept-Ranges: bytes). Video and voice chat engines can stream directly from edge chunk streams without buffering entire files into local RAM or disk storage.

2. Authentication

All streaming and search operations require a valid developer API key (format: yuki_[32-hex-characters]). You can pass your API key using any of the following three standard methods:

Method 1: Custom HTTP Header (Recommended for Security):

HTTP Header

x-api-key: yuki_059ffc1ace3f47e9890192009b7ce525

Method 2: Authorization Header:

Authorization

Authorization: Bearer YOUR_KEY

Method 3: URL Query Parameter (Required for Direct Streaming in Pytgcalls / FFmpeg):

URL Query

https://api.yukibots.me/stream/qdpXxGPqW-Y?key=yuki_059ffc1ace3f47e9890192009b7ce525&type=audio

3. Standard Rate Limiting

All clusters enforce a Token Bucket Rate Limiter per API key:

Burst Capacity: 4 tokens
Refill Rate: 4 tokens every 3 seconds (~1.33 req/sec continuous)
Daily Quota: 6,000 requests per 24-hour UTC window on Free Tier.
Exceeded Behavior: Returns HTTP 429 Too Many Requests with a Retry-After header in <6ms.

4. Production Gateways

Always maintain automatic client-side failover across the three production gateways:

Gateway	Base URL	Routing Priority	Purpose
Primary Gateway (api1)	`https://api.yukibots.me`	Priority 1	Primary high-speed music and search routing.
Secondary Gateway (api2)	`https://api2.yukibots.me`	Priority 2	Failover cluster with synchronized Redis/Memory caches.
Global Edge (api3)	`https://api3.yukibots.me`	Priority 3	Anycast edge network for low-latency worldwide playback.

5. Spotify Platform Streaming

MeowAPI natively supports seamless Spotify music streaming without requiring developers to register their own Spotify Developer App credentials. You can stream tracks directly using Spotify track IDs or full share links.

Supported Spotify Media Types:

Individual Tracks: https://open.spotify.com/track/{track_id}
Shortlinks: https://spotify.link/{id}
Direct Track IDs: 4cOdK2wGLETKBW3PvgPWqT

How Spotify Streaming Operates:

When you query a Spotify track on api.yukibots.me, the gateway performs high-speed ISCR and metadata matching, extracts the high-resolution 640x640 album artwork, duration, and artist info, and pipes high-fidelity 320kbps MP3 audio with byte-range seek capability.

Spotify Track Stream (cURL)

# Stream via Spotify Track ID
curl -L -H "x-api-key: YOUR_KEY"   "https://api.yukibots.me/stream/spotify/4cOdK2wGLETKBW3PvgPWqT" -o "song.mp3"

# Stream via Spotify Full URL
curl -L -H "x-api-key: YOUR_KEY"   "https://api.yukibots.me/stream/spotify/?url=https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT" -o "song.mp3"

6. VPlay & Telegram Voice Chat (VC) Music Bots

If you run a Telegram Voice Chat music bot (YukkiMusic, AnonXMusic, FallenMusic, or custom PyTgCalls bots), MeowAPI is specifically architected to solve your biggest infrastructure bottlenecks:

Zero Local Disk Consumption: The bot never downloads 100MB+ audio files to your VPS disk. Streams are piped directly over HTTP chunk streams into pytgcalls.
Instant Sub-1.5s Voice Chat Playback: Audio starts playing in Telegram VC within 1-2 seconds of user running /play command.
100% Elimination of YouTube IP Bans: YouTube blocks VPS data center IPs with HTTP 429 and "Sign in to confirm you're not a bot" errors. MeowAPI handles all proxy rotation, token signing, and Telegram Vault storage on its dedicated edge mesh, so your bot never encounters IP blocks.
Low VPS CPU & RAM Usage: Because no FFmpeg local encoding or yt-dlp scraping runs on your bot server, a 1-core $3 VPS can easily handle 50+ concurrent voice chat streams.

VPlay / PyTgCalls Python Implementation:

Python (PyTgCalls + Pyrogram)

import aiohttp
from pyrogram import Client, filters
from pytgcalls import PyTgCalls
from pytgcalls.types.input_stream import AudioPiped

API_KEY = "yuki_YOUR_API_KEY"
GATEWAY = "https://api.yukibots.me"

app = Client("my_vc_bot", api_id=12345, api_hash="abcdef", bot_token="BOT_TOKEN")
call_py = PyTgCalls(app)

@app.on_message(filters.command(["play", "vplay"]))
async def play_music(client, message):
    if len(message.command) < 2:
        return await message.reply_text("Usage: /play [song name or Spotify/YouTube link]")
    
    query = " ".join(message.command[1:])
    chat_id = message.chat.id
    status_msg = await message.reply_text("Searching track...")

    async with aiohttp.ClientSession() as session:
        # Check if user sent a Spotify URL
        if "spotify.com" in query:
            stream_url = f"{GATEWAY}/stream/spotify/?url={query}&key={API_KEY}"
            title = "Spotify Track"
        else:
            # Search YouTube via MeowAPI Search Engine
            headers = {"x-api-key": API_KEY}
            async with session.get(f"{GATEWAY}/search?q={query}", headers=headers) as resp:
                if resp.status != 200:
                    return await status_msg.edit("Track not found or gateway busy.")
                data = await resp.json()
                track = data["results"][0]
                video_id = track["id"]
                title = track["title"]
            stream_url = f"{GATEWAY}/stream/{video_id}?key={API_KEY}&type=audio"

    # Stream directly into Telegram Voice Chat via AudioPiped
    try:
        await call_py.join_group_call(
            chat_id,
            AudioPiped(stream_url)
        )
        await status_msg.edit(f"🎶 **Playing in VC:** {title}
⚡ *Powered by MeowAPI*")
    except Exception as e:
        await status_msg.edit(f"Playback error: {e}")

call_py.start()
app.run()

7. Deezer & DirectStream Engines

In addition to YouTube and Spotify, MeowAPI provides dedicated high-speed routes for Deezer and Direct HLS/M3U8 streams:

Deezer Stream:

Pass Deezer track ID or full URL to receive direct high-fidelity audio stream:

cURL Deezer

curl -L -H "x-api-key: YOUR_KEY"   "https://api.yukibots.me/stream/deezer/3135556" -o "deezer_song.mp3"

DirectStream / Live Radio Streams:

If you have direct .mp3, .m4a, or .m3u8 broadcast streams, the /download endpoint inspects and validates the stream headers, returning a resilient proxy stream link.

8. API Endpoint Reference

GET /search

Search music catalogs by song title, artist, or YouTube ID. Returns high-accuracy metadata and thumbnails.

Parameter	Type	Required	Description
`q`	string	Yes	Song name, search query, or track ID.
`key`	string	Optional	API key (if not sent via header).

Sample Response (JSON)

{
  "query": "faded",
  "results": [
    {
      "id": "qdpXxGPqW-Y",
      "title": "Alan Walker - Faded",
      "artist": "Alan Walker",
      "duration": "3:33",
      "duration_sec": 213,
      "thumbnail": "https://i.ytimg.com/vi/qdpXxGPqW-Y/hqdefault.jpg"
    }
  ]
}

GET /download

Generates a secure download and streaming token for any valid YouTube, Spotify, or media URL.

Parameter	Type	Required	Description
`url`	string	Yes	Full YouTube URL, video ID, or Spotify link.
`type`	string	No	`audio` (default) or `video`.

Sample Response (JSON)

{
  "status": "success",
  "video_id": "qdpXxGPqW-Y",
  "title": "Alan Walker - Faded",
  "download_url": "/stream/qdpXxGPqW-Y?key=YOUR_KEY&type=audio",
  "format": "mp3",
  "bitrate": "320kbps"
}

GET /stream/{id}

Pipes high-fidelity audio or video stream with standard HTTP Range Header support. Zero-latency transmission for Telegram Voice Chats and music players.

Parameter	Type	Default	Description
`type`	string	audio	`audio` (320kbps MP3/Opus) or `video` (MP4).
`quality`	string	320	Audio: `128`, `320`. Video: `480`, `720`.
`key`	string	-	API key (can also be passed in header).

HTTP Response Headers

HTTP/2 200 OK
Content-Type: audio/mpeg
Cache-Control: public, max-age=31536000, immutable
Accept-Ranges: bytes
Connection: keep-alive

GET /lyrics

Fetches synchronized song lyrics with title and artist matching.

cURL Lyrics

curl -H "x-api-key: YOUR_KEY"   "https://api.yukibots.me/lyrics?title=Faded&artist=Alan+Walker"

9. Multi-Language SDK & Code Samples

Python (Requests):

Python

import requests

API_KEY = "YOUR_KEY"
BASE_URL = "https://api.yukibots.me"
headers = {"x-api-key": API_KEY}

# 1. Search song
resp = requests.get(f"{BASE_URL}/search", params={"q": "faded"}, headers=headers)
data = resp.json()
first_id = data["results"][0]["id"]

# 2. Download audio stream
stream = requests.get(f"{BASE_URL}/stream/{first_id}?type=audio", headers=headers, stream=True)
with open("faded.mp3", "wb") as f:
    for chunk in stream.iter_content(chunk_size=16384):
        f.write(chunk)
print("Saved faded.mp3 successfully!")

Node.js (Axios / Fetch):

Node.js

const axios = require('axios');
const fs = require('fs');

const API_KEY = 'YOUR_KEY';
const client = axios.create({
  baseURL: 'https://api.yukibots.me',
  headers: { 'x-api-key': API_KEY }
});

async function main() {
  const search = await client.get('/search', { params: { q: 'faded' } });
  const songId = search.data.results[0].id;

  const stream = await client.get('/stream/' + songId + '?type=audio', { responseType: 'stream' });
  stream.data.pipe(fs.createWriteStream('faded.mp3'));
  console.log('Streaming audio chunk pipeline...');
}
main();

cURL Bash One-Liners:

cURL Bash

# Health probe
curl "https://api.yukibots.me/health"

# Search track
curl -H "x-api-key: YOUR_KEY" "https://api.yukibots.me/search?q=faded"

# Download 320kbps MP3
curl -L -H "x-api-key: YOUR_KEY" "https://api.yukibots.me/stream/qdpXxGPqW-Y?type=audio" -o "faded.mp3"

# Download 720p HD MP4 Video
curl -L -H "x-api-key: YOUR_KEY" "https://api.yukibots.me/stream/qdpXxGPqW-Y?type=video&quality=720" -o "faded.mp4"

Need Live Assistance or Custom Integration?

Our engineering team and bot community are available on Telegram for live support, quota upgrades, and VPlay bot debugging.

Message @MeowApiRobot

10. Fair Use Policy & Status Codes

Developers must respect the 4 req / 3s rate limiter. Automated scraping loops or rapid key distribution will trigger automated edge firewall blocks.

Status Code	Meaning	Resolution
`200 OK`	Successful execution	Stream payload or JSON returned.
`400 Bad Request`	Missing parameter	Ensure `q` or `url` is provided.
`401 Unauthorized`	Invalid or missing API key	Check key in `console.yukibots.me` or rotate key.
`429 Too Many Requests`	Rate limit reached	Back off for interval specified in `Retry-After` header.
`502 Bad Gateway`	Upstream origin timeout	Retry request on Secondary Gateway `api2.yukibots.me`.