Media API

The Media API provides endpoints for text-to-speech synthesis, audio transcription, and YouTube music search. These endpoints power the audio-related features in ryOS applications like iPod, Karaoke, and voice input.

All endpoints run on Vercel Node.js runtime and implement rate limiting to prevent abuse.

Text-to-Speech

Convert text to spoken audio using OpenAI or ElevenLabs voice synthesis.

Endpoint

Request

{
  "stability": 0.3,
  "similarity_boost": 0.8,
  "use_speaker_boost": true,
  "speed": 1.1
}

• mp3_44100_128 - MP3 at 44.1kHz, 128kbps

• mp3_22050_32 - MP3 at 22.05kHz, 32kbps
• pcm_16000 - PCM at 16kHz
• pcm_22050 - PCM at 22.05kHz
• pcm_24000 - PCM at 24kHz
• pcm_44100 - PCM at 44.1kHz
• ulaw_8000 - μ-law at 8kHz

Response

Returns audio stream with headers:

{
  "error": "'text' is required"
}

{
  "error": "rate_limit_exceeded",
  "scope": "burst" | "daily",
  "limit": 10,
  "windowSeconds": 60,
  "resetSeconds": 45,
  "identifier": "username or anon:ip"
}

Rate Limits

> Note: Authenticated admin users bypass rate limiting.

Example

curl -X POST https://your-domain.com/api/speech \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to ryOS!",
    "model": "elevenlabs",
    "voice_id": "kAyjEabBEu68HYYYRAHR"
  }' \
  --output speech.mp3

curl -X POST https://your-domain.com/api/speech \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to ryOS!",
    "model": "openai",
    "voice": "nova",
    "speed": 1.0
  }' \
  --output speech.mp3

Audio Transcription

Transcribe audio files to text using OpenAI Whisper.

Endpoint

Request

Response

{
  "text": "Transcribed text content here"
}

{
  "error": "No audio file provided"
}

{
  "error": "Invalid file type. Must be an audio file."
}

{
  "error": "File exceeds maximum size of 2MB"
}

{
  "error": "rate_limit_exceeded",
  "scope": "burst" | "daily",
  "limit": 10,
  "windowSeconds": 60,
  "resetSeconds": 45,
  "identifier": "ip:xxx.xxx.xxx.xxx"
}

Rate Limits

Example

curl -X POST https://your-domain.com/api/audio-transcribe \
  -F "[email protected]"

{
  "text": "This is the transcribed text from the audio recording."
}

const formData = new FormData();
formData.append('audio', audioBlob, 'recording.webm');

const response = await fetch('/api/audio-transcribe', {
  method: 'POST',
  body: formData,
});

const { text } = await response.json();
console.log('Transcription:', text);

YouTube Search

Search YouTube for music videos. Results are filtered to the Music category.

Endpoint

Request

Response

{
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "channelTitle": "Rick Astley",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
      "publishedAt": "2009-10-25T06:57:33Z"
    }
  ]
}

{
  "error": "Invalid request body"
}

{
  "error": "YouTube API access denied",
  "code": 403,
  "hint": "YouTube API access denied. Ensure the API key is valid and YouTube Data API v3 is enabled in Google Cloud Console."
}

{
  "error": "YouTube API is not configured",
    "hint": "Add YOUTUBE_API_KEY to your .env.local file and restart the API server"
}

{
  "error": "rate_limit_exceeded",
  "scope": "burst" | "daily"
}

Rate Limits

API Key Rotation

The endpoint supports multiple YouTube API keys for quota rotation:

• YOUTUBE_API_KEY - Primary key

• YOUTUBE_API_KEY_2 - Backup key

When the primary key's quota is exceeded, requests automatically fall back to backup keys.

Example

curl -X POST https://your-domain.com/api/youtube-search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Taylor Swift Shake It Off",
    "maxResults": 5
  }'

{
  "results": [
    {
      "videoId": "nfWlot6h_JM",
      "title": "Taylor Swift - Shake It Off",
      "channelTitle": "TaylorSwiftVEVO",
      "thumbnail": "https://i.ytimg.com/vi/nfWlot6h_JM/mqdefault.jpg",
      "publishedAt": "2014-08-19T04:00:02Z"
    }
  ]
}

const response = await fetch('/api/youtube-search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'Daft Punk Around the World',
    maxResults: 10,
  }),
});

const { results } = await response.json();
results.forEach(video => {
  console.log(`${video.title} - ${video.channelTitle}`);
});

Environment Variables

Related

• Song API - Song library management for karaoke

• Chat API - AI chat with voice integration
• AI System - Overview of AI capabilities