DOCUMENTATION · v0.2.0

API REFERENCE

Base URL: https://apis.kailashhh.com · JSON · CORS enabled

GET/api/stream

Stream API

Resolve a YouTube video ID to a direct audio stream URL. Tries multiple clients (ANDROID_VR → TVHTML5 → IOS) in sequence.

PARAMTYPEREQDESCRIPTION
idstringrequired
11-character YouTube video ID
EXAMPLE REQUEST
curl "https://apis.kailashhh.com/api/stream?id=4NRXx6U8ABQ"
EXAMPLE RESPONSE
{
  "url": "https://rr1---sn-xxx.googlevideo.com/...",
  "mimeType": "audio/webm; codecs=\"opus\"",
  "bitrate": 160000,
  "itag": 251,
  "title": "Blinding Lights",
  "author": "The Weeknd",
  "duration": "200",
  "thumbnail": "https://i.ytimg.com/vi/.../hqdefault.jpg",
  "client": "ANDROID_VR"
}
NOTES
·URLs expire ~6 hours after issue (YouTube CDN)
·client field tells you which client succeeded
·If all clients fail, use /api/stream/proxy instead
·Itag preference: 251 (opus 160k) → 140 (mp4a 128k) → 250 → 249 → 139
GET/api/stream/proxy

Stream Proxy (Test)

Alternative stream endpoint. Converts the video to MP3 via ytmp3 scraper then proxies the audio bytes. Bypasses YouTube player API entirely. Slower to start (2-8s conversion) but more reliable when player API is blocked.

PARAMTYPEREQDESCRIPTION
idstringrequired
11-character YouTube video ID
EXAMPLE REQUEST
curl "https://apis.kailashhh.com/api/stream/proxy?id=4NRXx6U8ABQ" -o track.mp3
EXAMPLE RESPONSE
audio/mpeg binary stream
NOTES
·Falls back to YTDLP_API_URL backend if configured (faster)
·Supports Range header — seek works in <audio> elements
·MP3 only via ytmp3 scraper, opus/m4a require YTDLP_API_URL
·Test endpoint — validate before using in production
GET/api/suggestions

Next / Suggestions

Returns "up next" radio suggestions for a YouTube video ID. Uses YTMusic WEB_REMIX /next endpoint.

PARAMTYPEREQDESCRIPTION
idstringrequired
11-character YouTube video ID (seed track)
limitnumberoptional
Number of suggestions (max 25). Default: 10
EXAMPLE REQUEST
curl "https://apis.kailashhh.com/api/suggestions?id=4NRXx6U8ABQ&limit=10"
EXAMPLE RESPONSE
{
  "id": "4NRXx6U8ABQ",
  "suggestions": [
    {
      "id": "...", "title": "...", "artist": "...",
      "duration": "3:45", "thumbnail": "...",
      "url": "https://www.youtube.com/watch?v=...",
      "source": "ytv2"
    }
  ],
  "total": 10
}
NOTES
·Seed track is excluded from results
·Same shape as search results — drop-in compatible with player
·YouTube only — Saavn has no equivalent endpoint
GET/api/saavn/stream

Saavn Stream Proxy

Proxies a JioSaavn CDN URL through the server. Required to bypass CORS + referer restrictions on Saavn CDN.

PARAMTYPEREQDESCRIPTION
urlstringrequired
URL-encoded Saavn CDN stream URL (from search?source=saavn results → streamUrl field)
EXAMPLE REQUEST
curl "https://apis.kailashhh.com/api/saavn/stream?url=https%3A%2F%2Faac.saavncdn.com%2F..."
EXAMPLE RESPONSE
audio/mp4 binary stream (320kbps AAC)
NOTES
·Only accepts *.saavncdn.com URLs
·Forwards Range header — seek works natively
·Use streamUrl field from /api/search?source=saavn results
GET/api/download

Download API

Download audio from a YouTube URL as MP3.

PARAMTYPEREQDESCRIPTION
urlstringrequired
YouTube or YT Music URL
formatselectoptional
Output format. Default: mp3
EXAMPLE REQUEST
curl "https://apis.kailashhh.com/api/download?url=https://youtu.be/4NRXx6U8ABQ"
EXAMPLE RESPONSE
{ "status": true, "title": "Blinding Lights", "format": "mp3", "url": "https://cdn.ymcdn.org/..." }
NOTES
·mp3 uses ytmp3 scraper (no backend needed)
·m4a/opus/best require YTDLP_API_URL env var (self-hosted yt-dlp)
·Saavn downloads go via /api/saavn/stream directly
POST/api/chat

Chat API

Non-streaming chat. Returns full reply after model finishes.

PARAMTYPEREQDESCRIPTION
messagestringrequired
User message
modelselectoptional
Model to use. Default: saanvi
historystringoptional
JSON array of {role, content} messages
systemstringoptional
System prompt (claude + gpt-4o only)
EXAMPLE REQUEST
curl -X POST "https://apis.kailashhh.com/api/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"hello","model":"claude"}'
EXAMPLE RESPONSE
{ "reply": "Hello! How can I help?", "model": "claude" }
NOTES
·saanvi — free, no key needed
·boss — AWS Lambda endpoint
·claude — requires ANTHROPIC_API_KEY
·gpt-4o — requires OPENAI_API_KEY
·For token-by-token streaming use POST /api/chat/stream (SSE)
POST/api/chat/stream

Chat Stream API

Streaming chat via Server-Sent Events. Tokens arrive as they are generated.

PARAMTYPEREQDESCRIPTION
messagestringrequired
User message
modelselectoptional
Model to use. Default: saanvi
systemstringoptional
System prompt (claude + gpt-4o only)
EXAMPLE REQUEST
curl -X POST "https://apis.kailashhh.com/api/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{"message":"count to 5","model":"claude"}'
EXAMPLE RESPONSE
data: "1"
data: " 2"
data: " 3"
data: " 4"
data: " 5"
data: [DONE]
NOTES
·Content-Type: text/event-stream
·Each data event is a JSON-encoded string token
·Stream ends with data: [DONE]
GET/api/blog

Blog API

Fetch blog posts as JSON or RSS.

PARAMTYPEREQDESCRIPTION
formatselectoptional
Response format. Default: json
limitnumberoptional
Number of posts (max 50)
tagstringoptional
Filter by tag
EXAMPLE REQUEST
curl "https://apis.kailashhh.com/api/blog?format=json&limit=5"
EXAMPLE RESPONSE
{ "posts": [{ "slug": "...", "title": "...", "date": "...", "tags": [] }], "total": 1, "limit": 5 }
NOTES
·rss returns application/rss+xml
·Posts sorted by date descending