oatda-generate-speech

OATDA Speech Generation

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

When to Use

Use this skill when the user wants to:

• Convert text to speech or audio
• Create voiceovers, announcements, narration, or accessibility audio
• Use TTS models from OpenAI, xAI, Google and others through OATDA
• Use the OATDA generate_speech capability

HTTP vs MCP (read this first)

Path	Response	Use when
MCP generate_speech	Text with AUDIO_URL: (HMAC ?exp=&sig=, ~1h TTL) + metadata in structuredContent (download_url, format, duration_seconds, costs)	Already connected to OATDA MCP (Cursor, etc.)
HTTP POST /api/v1/llm/speech	Raw audio bytes (Content-Disposition: attachment)	Shell/scripts: curl --output speech.mp3

Upstream providers (OpenAI TTS, xAI Grok TTS) do not return a hosted download URL for speech. xAI returns raw bytes (curl ... --output hello.mp3 in their docs). OATDA MCP mirrors TTS into a short-lived signed download so editors can fetch without a browser session.

MCP agents: After generate_speech, extract AUDIO_URL: from the tool text (or structuredContent.download_url) and download with curl - no login required. Do not expect MCP AudioContent / base64 audio blocks (removed). URL expires in ~1 hour.

Shell/scripts: Prefer HTTP with --output (see step 4), or MCP signed URL + curl.

Prerequisites

The user needs an OATDA API key. Check in this order:

1. $OATDA_API_KEY environment variable
2. ~/.oatda/credentials.json config file

If neither exists, tell the user:

You need an OATDA API key. Get one at https://oatda.com, then set it: export OATDA_API_KEY=your_key_here

Step-by-Step Instructions

1. Resolve the API key

# Check env var first; if empty, auto-load from credentials file
if [[ -z "$OATDA_API_KEY" ]]; then
  export OATDA_API_KEY=$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)
fi

# Verify key exists (show first 8 chars only)
echo "${OATDA_API_KEY:0:8}"