{
  "service": {
    "name": "hypersyt API",
    "version": "1.2.0",
    "description": "hypersyt is an open, high-speed public gateway providing YouTube transcripts, metadata, search listings, AI-generated video summaries, and text-to-speech audio (one-shot base64 or progressive HTTP streaming) via a Cartesia-compatible proxy (default voice 'jameson'). Data endpoints require zero API keys; TTS is authenticated server-side. Built for seamless integration into web apps, CLI scripts, and AI agents.",
    "baseUrl": "https://api.hypers.wtf",
    "format": "JSON / plain text / binary audio / streaming audio / SSE / WebSocket"
  },
  "authentication": {
    "required": false,
    "type": "None for YouTube data; gateway-managed key for TTS (BYOK supported)",
    "description": "Data endpoints need no keys. TTS routes authenticate server-side against the Cartesia 'double11' proxy with the gateway key (env.TTS_API_KEY); clients may optionally bring their own key via '?key=', 'Authorization: Bearer', or 'X-API-Key' — it is forwarded upstream and never stored or echoed."
  },
  "rateLimits": {
    "policy": "Two separate per-IP fixed-window pools (60-second windows)",
    "limit": "5 data requests + 3 TTS generation requests per 60s per IP",
    "windowSeconds": 60,
    "ruleExplanation": "YouTube data routes (/transcript, /search, /video, /summary) share one 5-request pool. TTS generation routes (/tts, /tts/stream, /tts/bytes, /tts/sse, /tts/websocket) share a separate 3-request pool. Both pools count GET and POST alike. Utility routes (/docs, /health, /stats, /llms.txt) and the voice catalog (/voices, /voices/{id}) are unmetered.",
    "headers": {
      "X-RateLimit-Limit": "Maximum requests allowed in a 60-second window for the matched pool.",
      "X-RateLimit-Remaining": "Remaining calls available before getting throttled.",
      "X-RateLimit-Reset": "Seconds until the 60-second quota resets.",
      "Retry-After": "Seconds you must wait before retrying when a 429 occurs."
    }
  },
  "endpoints": {
    "/transcript": {
      "description": "Fetches timestamped captions or raw continuous text from a YouTube video.",
      "httpMethod": "GET",
      "quotaCost": "1 request (data pool: 5 requests/minute/IP)",
      "parameters": {
        "required": [
          {
            "name": "v",
            "aliases": [
              "videoId",
              "id",
              "url",
              "videoUrl",
              "u"
            ],
            "type": "string",
            "description": "YouTube video ID (e.g., 'OmXoDYf9hq8') or full watch URL."
          }
        ],
        "optional": [
          {
            "name": "format",
            "type": "string",
            "default": "json",
            "options": [
              "json",
              "text",
              "txt"
            ],
            "description": "Set to 'text' or 'txt' to get clean raw text directly without timestamps."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -i \"https://api.hypers.wtf/transcript?v=OmXoDYf9hq8&format=text\"",
        "javascript": "// Modern JavaScript (Browser / Node 18+)\nconst res = await fetch(\"https://api.hypers.wtf/transcript?v=OmXoDYf9hq8&format=text\");\nconst transcript = await res.text();\nconsole.log(transcript);",
        "python": "# Python 3\nimport requests\n\nurl = \"https://api.hypers.wtf/transcript\"\nparams = {\"v\": \"OmXoDYf9hq8\", \"format\": \"text\"}\n\nresponse = requests.get(url, params=params)\nprint(response.text)"
      }
    },
    "/search": {
      "description": "Queries YouTube videos and returns structured search results.",
      "httpMethod": "GET",
      "quotaCost": "1 request (data pool: 5 requests/minute/IP)",
      "parameters": {
        "required": [
          {
            "name": "q",
            "aliases": [
              "query",
              "keyword",
              "k"
            ],
            "type": "string",
            "description": "Search keyword or topic."
          }
        ],
        "optional": [
          {
            "name": "limit",
            "type": "integer",
            "default": 10,
            "range": "1 to 15",
            "description": "Maximum number of items to return."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -i \"https://api.hypers.wtf/search?q=machine+learning&limit=5\"",
        "javascript": "const res = await fetch(\"https://api.hypers.wtf/search?q=machine+learning&limit=5\");\nconst data = await res.json();\nconsole.log(data);",
        "python": "import requests\n\nres = requests.get(\"https://api.hypers.wtf/search\", params={\"q\": \"machine learning\", \"limit\": 5})\ndata = res.json()\nprint(data)"
      }
    },
    "/video": {
      "description": "Fetches metadata, view statistics, and channel details.",
      "httpMethod": "GET",
      "quotaCost": "1 request (data pool: 5 requests/minute/IP)",
      "parameters": {
        "required": [
          {
            "name": "v",
            "aliases": [
              "videoId",
              "id",
              "url",
              "videoUrl",
              "u"
            ],
            "type": "string",
            "description": "YouTube video ID or full URL."
          }
        ],
        "optional": [
          {
            "name": "region",
            "type": "string",
            "description": "Two-letter country code (e.g. 'US', 'IN')."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -i \"https://api.hypers.wtf/video?v=OmXoDYf9hq8\"",
        "javascript": "const res = await fetch(\"https://api.hypers.wtf/video?v=OmXoDYf9hq8\");\nconst videoInfo = await res.json();\nconsole.log(videoInfo);",
        "python": "import requests\n\nres = requests.get(\"https://api.hypers.wtf/video\", params={\"v\": \"OmXoDYf9hq8\"})\nprint(res.json())"
      }
    },
    "/summary": {
      "description": "AI-generated overview and key points from the video transcript.",
      "httpMethod": "GET",
      "quotaCost": "1 request (data pool: 5 requests/minute/IP)",
      "parameters": {
        "required": [
          {
            "name": "v",
            "aliases": [
              "videoId",
              "id",
              "url",
              "videoUrl",
              "u"
            ],
            "type": "string",
            "description": "YouTube video ID or full URL."
          }
        ],
        "optional": [
          {
            "name": "style",
            "type": "string",
            "default": "detailed",
            "options": [
              "detailed",
              "brief"
            ],
            "description": "Summary format style."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -i \"https://api.hypers.wtf/summary?v=OmXoDYf9hq8&style=brief\"",
        "javascript": "const res = await fetch(\"https://api.hypers.wtf/summary?v=OmXoDYf9hq8&style=brief\");\nconst summary = await res.json();\nconsole.log(summary);",
        "python": "import requests\n\nres = requests.get(\"https://api.hypers.wtf/summary\", params={\"v\": \"OmXoDYf9hq8\", \"style\": \"brief\"})\nprint(res.json())"
      }
    },
    "/tts": {
      "description": "One-shot text-to-speech via the Cartesia 'double11' docs-parity proxy. Default voice: 'jameson'. Returns a JSON envelope with the raw audio as base64 (audio_base64); use format=binary or format=stream for progressive raw-audio streaming, or format=text for a bare base64 string.",
      "httpMethod": "GET, POST",
      "quotaCost": "1 request (TTS pool: 3 requests/minute/IP, shared with /tts/stream, /tts/bytes, /tts/sse, /tts/websocket)",
      "parameters": {
        "required": [
          {
            "name": "text",
            "aliases": [
              "transcript",
              "input",
              "t"
            ],
            "type": "string",
            "maxLength": 5000,
            "description": "Text to synthesize. JSON body field (POST) or query parameter (GET)."
          }
        ],
        "optional": [
          {
            "name": "voice",
            "type": "string",
            "default": "jameson",
            "description": "Voice id or built-in alias (jameson, james, blake, scott, sienna, default) — aliases auto-resolve to Cartesia voice UUIDs."
          },
          {
            "name": "model_id",
            "aliases": [
              "model"
            ],
            "type": "string",
            "default": "sonic-3.6",
            "description": "Cartesia model id."
          },
          {
            "name": "language",
            "type": "string",
            "default": "en",
            "description": "ISO language code."
          },
          {
            "name": "container",
            "type": "string",
            "default": "wav",
            "description": "Audio container (wav, mp3, ...)."
          },
          {
            "name": "encoding",
            "type": "string",
            "default": "pcm_s16le",
            "description": "Sample encoding."
          },
          {
            "name": "sample_rate",
            "type": "integer",
            "default": 44100,
            "description": "Sample rate in Hz."
          },
          {
            "name": "format",
            "type": "string",
            "default": "base64",
            "options": [
              "base64",
              "binary",
              "text",
              "stream"
            ],
            "description": "'base64' → JSON envelope with audio_base64; 'binary'/'stream' → raw audio streamed progressively (no buffering); 'text' → bare base64 string."
          },
          {
            "name": "key",
            "type": "string",
            "default": "(gateway key)",
            "description": "Optional bring-your-own proxy key; forwarded upstream via 'Authorization: Bearer', 'X-API-Key', or '?key='."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl \"https://api.hypers.wtf/tts?text=Hello%20world&voice=jameson\"",
        "javascript": "const res = await fetch(\"https://api.hypers.wtf/tts\", {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ text: \"Hello world\", voice: \"jameson\" }),\n});\nconst { audio_base64, content_type } = await res.json();\nconst bytes = Uint8Array.from(atob(audio_base64), (c) => c.charCodeAt(0));\nconsole.log(content_type, bytes.length);",
        "python": "import requests, base64\n\nres = requests.post(\"https://api.hypers.wtf/tts\", json={\"text\": \"Hello world\", \"voice\": \"jameson\"})\naudio = base64.b64decode(res.json()[\"audio_base64\"])\nopen(\"out.wav\", \"wb\").write(audio)"
      }
    },
    "/tts/stream": {
      "description": "Progressive HTTP streaming: raw audio bytes are flushed to the client chunk-by-chunk while the model is still synthesizing — no wait for the full clip. Same friendly parameters as /tts (voice aliases, model defaults). Ideal for <audio> elements and low-latency pipelines. Errors before the first byte return a JSON error envelope; a mid-stream failure simply ends the audio.",
      "httpMethod": "GET, POST",
      "quotaCost": "1 request (TTS pool: 3 requests/minute/IP, shared with /tts, /tts/bytes, /tts/sse, /tts/websocket)",
      "parameters": {
        "required": [
          {
            "name": "text",
            "aliases": [
              "transcript",
              "input",
              "t"
            ],
            "type": "string",
            "maxLength": 5000,
            "description": "Text to synthesize. JSON body field (POST) or query parameter (GET)."
          }
        ],
        "optional": [
          {
            "name": "voice",
            "type": "string",
            "default": "jameson",
            "description": "Voice id or built-in alias (jameson, james, blake, scott, sienna, default) — aliases auto-resolve to Cartesia voice UUIDs."
          },
          {
            "name": "model_id",
            "aliases": [
              "model"
            ],
            "type": "string",
            "default": "sonic-3.6",
            "description": "Cartesia model id."
          },
          {
            "name": "language",
            "type": "string",
            "default": "en",
            "description": "ISO language code."
          },
          {
            "name": "container",
            "type": "string",
            "default": "wav",
            "description": "Audio container (wav, mp3, ...)."
          },
          {
            "name": "encoding",
            "type": "string",
            "default": "pcm_s16le",
            "description": "Sample encoding."
          },
          {
            "name": "sample_rate",
            "type": "integer",
            "default": 44100,
            "description": "Sample rate in Hz."
          },
          {
            "name": "key",
            "type": "string",
            "default": "(gateway key)",
            "description": "Optional bring-your-own proxy key; forwarded upstream via 'Authorization: Bearer', 'X-API-Key', or '?key='."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -N \"https://api.hypers.wtf/tts/stream?text=Hello%20world&voice=jameson\" --output hello.wav",
        "javascript": "const audio = new Audio(\"https://api.hypers.wtf/tts/stream?text=Hello%20world&voice=jameson\");\naudio.play(); // playback starts as soon as the first bytes arrive",
        "python": "import requests\n\nwith requests.post(\"https://api.hypers.wtf/tts/stream\", json={\"text\": \"Hello world\", \"voice\": \"jameson\"}, stream=True) as r:\n    with open(\"hello.wav\", \"wb\") as f:\n        for chunk in r.iter_content(8192):\n            f.write(chunk)"
      }
    },
    "/tts/bytes": {
      "description": "Docs-compatible passthrough to the Cartesia proxy: POST a Cartesia-style body and receive the raw binary audio stream. Simplified /tts fields (text, voice, ...) are also accepted and normalized upstream.",
      "httpMethod": "POST",
      "quotaCost": "1 request (TTS pool: 3 requests/minute/IP)",
      "parameters": {
        "required": [
          {
            "name": "transcript",
            "aliases": [
              "text",
              "input",
              "t"
            ],
            "type": "string",
            "description": "Text to synthesize."
          }
        ],
        "optional": [
          {
            "name": "voice",
            "type": "string | object",
            "default": "jameson",
            "description": "Voice id, UUID, or built-in alias (jameson, james, blake, scott, sienna, default); voice objects pass through verbatim."
          },
          {
            "name": "model_id",
            "type": "string",
            "default": "sonic-3.6",
            "description": "Cartesia model id."
          },
          {
            "name": "output_format",
            "type": "object",
            "default": "{container: wav, encoding: pcm_s16le, sample_rate: 44100}",
            "description": "Cartesia output format."
          },
          {
            "name": "language",
            "type": "string",
            "default": "en",
            "description": "ISO language code."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -X POST \"https://api.hypers.wtf/tts/bytes\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"transcript\": \"Hello world\", \"model_id\": \"sonic-3.6\", \"voice\": {\"mode\": \"id\", \"id\": \"jameson\"}}' \\\n  --output hello.wav",
        "javascript": "const res = await fetch(\"https://api.hypers.wtf/tts/bytes\", {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ text: \"Hello world\", voice: \"jameson\" }),\n});\nconst audio = new Uint8Array(await res.arrayBuffer());",
        "python": "import requests\n\nres = requests.post(\"https://api.hypers.wtf/tts/bytes\", json={\"text\": \"Hello world\", \"voice\": \"jameson\"})\nopen(\"hello.wav\", \"wb\").write(res.content)"
      }
    },
    "/tts/sse": {
      "description": "Docs-compatible passthrough: streams synthesis events (including audio chunks) as server-sent events.",
      "httpMethod": "POST",
      "quotaCost": "1 request (TTS pool: 3 requests/minute/IP)",
      "parameters": {
        "required": [
          {
            "name": "transcript",
            "aliases": [
              "text",
              "input",
              "t"
            ],
            "type": "string",
            "description": "Text to synthesize."
          }
        ],
        "optional": [
          {
            "name": "voice",
            "type": "string | object",
            "default": "jameson",
            "description": "Voice id."
          },
          {
            "name": "model_id",
            "type": "string",
            "default": "sonic-3.6",
            "description": "Cartesia model id."
          }
        ]
      },
      "codeSnippets": {
        "curl": "curl -N -X POST \"https://api.hypers.wtf/tts/sse\" -H \"Content-Type: application/json\" -d '{\"text\": \"Hello world\", \"voice\": \"jameson\"}'",
        "javascript": "const res = await fetch(\"https://api.hypers.wtf/tts/sse\", {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ text: \"Hello world\", voice: \"jameson\" }),\n});\nconst reader = res.body.getReader(); // consume the SSE stream",
        "python": "import requests\n\nwith requests.post(\"https://api.hypers.wtf/tts/sse\", json={\"text\": \"Hello world\", \"voice\": \"jameson\"}, stream=True) as r:\n    for line in r.iter_lines():\n        print(line.decode())"
      }
    },
    "/tts/websocket": {
      "description": "Docs-compatible WebSocket TTS: open a socket, send Cartesia-style JSON messages, receive binary audio frames and control messages. Query params (voice, model_id, ...) are forwarded upstream.",
      "httpMethod": "WS",
      "quotaCost": "1 request per connection (TTS pool: 3 requests/minute/IP)",
      "parameters": {
        "required": [],
        "optional": [
          {
            "name": "voice",
            "type": "string",
            "default": "jameson",
            "description": "Default voice for the session (messages may override)."
          },
          {
            "name": "key",
            "type": "string",
            "default": "(gateway key)",
            "description": "Optional BYOK; WebSocket auth is sent via '?key='."
          }
        ]
      },
      "codeSnippets": {
        "javascript": "const ws = new WebSocket(\"wss://api.hypers.wtf/tts/websocket?voice=jameson\");\nws.onopen = () => ws.send(JSON.stringify({\n  transcript: \"Hello world\",\n  model_id: \"sonic-3.6\",\n  voice: { mode: \"id\", id: \"jameson\" },\n  output_format: { container: \"wav\", encoding: \"pcm_s16le\", sample_rate: 44100 },\n}));\nws.onmessage = (event) => console.log(\"frame:\", event.data.byteLength ?? event.data);",
        "python": "# pip install websockets\nimport asyncio, json, websockets\n\nasync def main():\n    async with websockets.connect(\"wss://api.hypers.wtf/tts/websocket?voice=jameson\") as ws:\n        await ws.send(json.dumps({\n            \"transcript\": \"Hello world\",\n            \"model_id\": \"sonic-3.6\",\n            \"voice\": {\"mode\": \"id\", \"id\": \"jameson\"},\n        }))\n        while True:\n            frame = await ws.recv()\n            print(type(frame).__name__, len(frame))\n\nasyncio.run(main())"
      }
    },
    "/voices": {
      "description": "Lists the voices available on the TTS proxy (docs-compatible).",
      "httpMethod": "GET",
      "quotaCost": "0 (Unmetered)",
      "codeSnippets": {
        "curl": "curl \"https://api.hypers.wtf/voices\"",
        "javascript": "const voices = await (await fetch(\"https://api.hypers.wtf/voices\")).json();",
        "python": "voices = requests.get(\"https://api.hypers.wtf/voices\").json()"
      }
    },
    "/voices/{id}": {
      "description": "Returns details for a single voice id (docs-compatible).",
      "httpMethod": "GET",
      "quotaCost": "0 (Unmetered)",
      "codeSnippets": {
        "curl": "curl \"https://api.hypers.wtf/voices/jameson\"",
        "javascript": "const voice = await (await fetch(\"https://api.hypers.wtf/voices/jameson\")).json();",
        "python": "voice = requests.get(\"https://api.hypers.wtf/voices/jameson\").json()"
      }
    },
    "/stats": {
      "description": "Returns live aggregated platform usage metrics and total request volume.",
      "httpMethod": "GET",
      "quotaCost": "0 (Unmetered)",
      "codeSnippets": {
        "curl": "curl -i \"https://api.hypers.wtf/stats\"",
        "javascript": "const stats = await (await fetch(\"https://api.hypers.wtf/stats\")).json();",
        "python": "stats = requests.get(\"https://api.hypers.wtf/stats\").json()"
      }
    },
    "/health": {
      "description": "Service health and heartbeat check.",
      "httpMethod": "GET",
      "quotaCost": "0 (Unmetered)",
      "codeSnippets": {
        "curl": "curl -i \"https://api.hypers.wtf/health\""
      }
    },
    "/llms.txt": {
      "description": "Machine-readable markdown guide for AI assistants and LLM crawlers.",
      "httpMethod": "GET",
      "quotaCost": "0 (Unmetered)",
      "codeSnippets": {
        "curl": "curl -s \"https://api.hypers.wtf/llms.txt\""
      }
    }
  }
}