Audio & Voice API

One REST API for Indian-language voice. Every endpoint below shares the same base URL, authentication and error envelope — learn it once and every call follows the same shape. For live, two-way conversation over a WebSocket, see Realtime Speech to Speech instead.

Base URL https://platform.oogam.ai/v1 · authenticate with Authorization: Bearer sk-setu-… (Authentication) · errors use one JSON envelope · every request is metered in rupees from your project wallet, and the exact charge for each call comes back in the X-Naad-Cost-Paise response header.

Endpoints at a glance

All audio endpoints need the naad product enabled on your API key. Language codes are 3-letter (full list) and the models never auto-detect — always send the spoken language.

Text to Speech

POST /audio/speech — JSON body in, audio bytes out, always synchronous. Billed per character.

Response: raw audio bytes — save the body straight to a file, there is no JSON wrapper on success. Useful response headers:

curl https://platform.oogam.ai/v1/audio/speech \
  -H "Authorization: Bearer $OOGAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "naad-tts-v1",
    "input": "नमस्ते! आज मैं आपकी क्या मदद कर सकती हूँ?",
    "voice": "aditi",
    "language": "HIN"
  }' \
  --output hello.wav

Speech to Text

POST /audio/transcriptions — multipart form in, transcript out. Billed per audio minute. Uploads up to 200 MB; formats: wav, mp3, m4a, aac, flac, ogg, webm. Mislabeled files are detected from their bytes and corrected automatically.

Sync vs async

Short clips return the transcript directly (200). Long recordings return 202 {"id":"…","status":"processing","object":"transcription.job"} — poll GET /audio/transcriptions-status/{id} until it resolves. Handle both (check for status 202) and you never need to know which path ran.

curl https://platform.oogam.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $OOGAM_API_KEY" \
  -F "model=naad-stt-v1" \
  -F "language=HIN" \
  -F "response_format=verbose_json" \
  -F "diarize=true" \
  -F "file=@call-recording.wav"

verbose_json response

With response_format=verbose_json (and diarize=true) each segment carries timings and a speaker label:

{
  "text": "नमस्ते, मैं राज बोल रहा हूँ। आपका ऑर्डर कल पहुँच जाएगा।",
  "language": "HIN",
  "duration": 6.4,
  "segments": [
    { "id": 0, "start": 0.0, "end": 2.1, "speaker": "SP1",
      "text": "नमस्ते, मैं राज बोल रहा हूँ।" },
    { "id": 1, "start": 2.4, "end": 6.4, "speaker": "SP1",
      "text": "आपका ऑर्डर कल पहुँच जाएगा।" }
  ]
}

Polling an async job

curl https://platform.oogam.ai/v1/audio/transcriptions-status/JOB_ID \
  -H "Authorization: Bearer $OOGAM_API_KEY"

# 202 {"status":"processing"}          → keep polling (every few seconds)
# 200 <transcript>                     → done, same shape as the sync reply
# 200 {"status":"failed","error":"…"}  → the model could not process it

Translation to English

POST /audio/translations — identical parameters to transcription, but the transcript always comes back in English no matter the spoken language. Same sync/async behaviour, same per-minute billing, same 200/202 shapes and the same status-polling endpoint pattern.

Speech to Speech (batch)

POST /audio/speech-to-speech — re-voice a whole recording in one call: send audio, get audio back in the target voice. Multipart form, synchronous, billed per source minute (₹0.38 / min). Uploads up to 25 MB. For live, turn-taking conversation use the realtime WebSocket instead.

Response: re-voiced audio bytes, with the same X-Naad-* headers as TTS.

curl https://platform.oogam.ai/v1/audio/speech-to-speech \
  -H "Authorization: Bearer $OOGAM_API_KEY" \
  -F "model=naad-sts-v1" \
  -F "voice=aditi" \
  -F "speed=1.0" \
  -F "file=@original.wav" \
  --output revoiced.wav

Multi-speaker conversation

POST /audio/conversation — turn a scripted dialogue into one continuous clip with distinct voices per speaker. JSON in, audio out; billed per character across all turns.

Each segment is { "voice_id": "…", "text": "…" }:

Limits: at most 50 segments, 2,000 characters per segment, 12,000 characters total, request body 256 KB.

Response: one audio clip (bytes) with headers X-Conversation-Id and X-Segments. Longer dialogues (4+ turns) may return an async job instead — poll it the same way as STT:

curl https://platform.oogam.ai/v1/audio/conversation \
  -H "Authorization: Bearer $OOGAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "HIN",
    "model": "naad-tts-v1",
    "segments": [
      { "voice_id": "aditi",        "text": "नमस्ते! Naad में आपका स्वागत है।" },
      { "voice_id": "male_voice_1", "text": "धन्यवाद! यह आवाज़ बहुत साफ़ है।" },
      { "voice_id": "aditi",        "text": "बिलकुल — और पूरी तरह भारतीय।" }
    ]
  }' \
  --output dialogue.wav

Voice changer

POST /audio/voice-changer — swap the voice of a clip while keeping the words and timing. Multipart form, synchronous, billed per source minute (₹0.45 / min), uploads up to 25 MB.

curl https://platform.oogam.ai/v1/audio/voice-changer \
  -H "Authorization: Bearer $OOGAM_API_KEY" \
  -F "model=naad-s2s-v1" \
  -F "voice=kavya" \
  -F "file=@memo.wav" \
  --output changed.wav

Voice isolation

POST /audio/isolate — strip background noise and music, leaving clean speech (ideal to prep field recordings before STT). Multipart form, synchronous, billed per minute (₹0.23 / min). Uploads up to 150 MB.

curl https://platform.oogam.ai/v1/audio/isolate \
  -H "Authorization: Bearer $OOGAM_API_KEY" \
  -F "model=naad-isolate-v1" \
  -F "file=@noisy-field-recording.wav" \
  --output clean.wav

List voices

GET /voices returns every voice your key may use and the model catalogue with live pricing. It is the source of truth for the voice field above — see the full Voices reference for every response field, including the available flag and how a clone's live_voice_id maps onto the realtime WebSocket.

curl https://platform.oogam.ai/v1/voices \
  -H "Authorization: Bearer $OOGAM_API_KEY"

Endpoint errors

These are specific to the audio endpoints; auth, rate-limit and wallet errors are shared across the whole API (see the full error reference).