OATDA Speech Generation#

Generate spoken audio from text through OATDA's unified audio API.

API Key Resolution#

All commands need the OATDA API key. Resolve it inline for each exec call:

bash

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}"

If the key is empty or null, tell the user to get one at https://oatda.com and configure it.

Security: Never print the full API key. Only verify existence or show first 8 chars.

Model Mapping#

User saysProviderModeltts, tts-1, openai tts (default)openaitts-1tts hd, tts-1-hdopenaitts-1-hdgpt tts, gpt-4o mini ttsopenaigpt-4o-mini-tts

Default: openai / tts-1 if no model specified.

If the user provides provider/model format directly (for example openai/tts-1), split on /.

Common OpenAI voices include alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, and shimmer. Use alloy if the user does not specify a voice.

⚠️ Models change over time. If a model ID fails, query oatda-list-models with ?type=audio first.

Discovering Audio Model Parameters#

Query available audio models and inspect supported_params before sending optional fields:

bash

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}" && \
curl -s -X GET "https://oatda.com/api/v1/llm/models?type=audio" \
  -H "Authorization: Bearer $OATDA_API_KEY" | jq '.audio_models[] | {id, supported_params}'

Look for:

• audio_modes containing tts
• supported voice values
• allowed response_format values
• optional fields like instructions or language

API Call#

The speech endpoint returns binary audio, not JSON. Always save the response to a file.

bash

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}" && \
curl -s -X POST "https://oatda.com/api/v1/llm/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -d '{
    "provider": "<PROVIDER>",
    "model": "<MODEL>",
    "input": "<TEXT_TO_SPEAK>",
    "voice": "alloy",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

Common Parameters#

• input: Text to convert to speech, max 15000 characters
• voice: Voice name, e.g. alloy, nova, shimmer
• response_format: mp3, opus, aac, flac, wav, pcm, mulaw, or alaw
• speed: 0.25 to 4.0, default 1.0
• instructions: Optional tone/style guidance for supported models
• language: Optional language code for supported models

Success Handling#

If the request succeeds, tell the user where the file was saved, for example:

Speech generated successfully: speech.mp3

If headers matter, use curl -D headers.txt while still saving the audio body with --output.

Error Handling#

HTTP StatusMeaningAction401Invalid API keyTell user to check their key402Insufficient creditsTell user to check balance400Bad request / model not supportedCheck model format and query oatda-list-models with type=audio429Rate limited or monthly capWait briefly and retry once500Provider errorShow the error message if returned

Example#

bash

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}" && \
curl -s -X POST "https://oatda.com/api/v1/llm/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -d '{
    "provider": "openai",
    "model": "tts-1",
    "input": "Welcome to OATDA, one API to direct all.",
    "voice": "alloy",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

Notes#

• Endpoint: /api/v1/llm/speech
• Use input, not prompt, for TTS requests
• Always save the response with --output
• Use oatda-list-models to discover available audio models
• Equivalent capability name: generate_speech
• Related skills: oatda-list-models, oatda-transcribe-audio, oatda-translate-audio