Getting Started with the Speech-to-Text API

Convert recorded or streaming audio to text with enterprise-grade accuracy using our neural Speech-to-Text API. Includes native speaker diarization, word-level timestamps, and multi-language SDK examples.

3-Step Quickstart Guide

Step 1: Obtain Your API Key

Sign in to your YourVoic Developer Portal to generate your secret API key. Keep this key secure and avoid committing it to public version control repositories.

Step 2: Choose Your Engine & Model

Select either Cipher for cost-effective batch transcription (from 2 credits/sec) or Lucid for conversational AI and live audio streaming.

Step 3: Execute Your First Transcription Request

Below are production-ready code examples in Python, JavaScript/Node.js, and cURL demonstrating how to upload an audio file and parse the recognized text and word-level timestamps.

Python (requests)

import requests
import json

# YourVoic STT Universal Endpoint
API_URL = "https://yourvoic.com/api/v1/stt/transcribe"
API_KEY = "YOUR_API_KEY"

headers = {
    "X-API-Key": API_KEY
}

# Open audio file in binary mode
with open("speech_sample.mp3", "rb") as audio_file:
    files = {
        "file": ("speech_sample.mp3", audio_file, "audio/mpeg")
    }
    payload = {
        "model": "cipher-fast",
        "language": "auto",
        "punctuate": "true",
        "smart_format": "true",
        "response_format": "verbose_json"
    }

    response = requests.post(API_URL, headers=headers, files=files, data=payload)

if response.status_code == 200:
    data = response.json()
    print("Full Transcript:")
    print(data["text"])
    print(f"\nDuration: {data['duration']}s | Language: {data['language']}")
    print(f"Confidence: {data['confidence'] * 100:.1f}%")
else:
    print(f"Transcription failed ({response.status_code}):", response.text)

Node.js / JavaScript (Fetch API & FormData)

import fs from 'node:fs';
import FormData from 'form-data';
import fetch from 'node-fetch';

async function transcribeAudio() {
  const form = new FormData();
  form.append('file', fs.createReadStream('sample.wav'));
  form.append('model', 'cipher-fast');
  form.append('language', 'en');
  form.append('smart_format', 'true');
  form.append('response_format', 'verbose_json');

  const response = await fetch('https://yourvoic.com/api/v1/stt/transcribe', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      ...form.getHeaders()
    },
    body: form
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`STT Request Failed (${response.status}): ${errorText}`);
  }

  const result = await response.json();
  console.log('Transcript:', result.text);
  console.log(`Word count: ${result.words?.length || 0}`);
}

transcribeAudio().catch(console.error);

cURL (Command Line)

curl -X POST "https://yourvoic.com/api/v1/stt/transcribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@speech_sample.mp3" \
  -F "model=cipher-fast" \
  -F "language=en" \
  -F "smart_format=true" \
  -F "response_format=verbose_json"

Detailed Response JSON Payload

When requesting verbose_json format, the API returns high-resolution word timestamps, speaker labels, and recognition confidence scores:

{
  "success": true,
  "job_id": "stt_job_8b21ef409c12",
  "text": "Welcome to YourVoic. Our neural speech recognition engine transcribes audio accurately with zero setup.",
  "model": "cipher-fast",
  "language": "en",
  "language_probability": 0.998,
  "duration": 6.12,
  "confidence": 0.987,
  "credits_used": 12,
  "words": [
    {"word": "Welcome", "start": 0.18, "end": 0.62, "confidence": 0.995, "speaker": 0},
    {"word": "to", "start": 0.64, "end": 0.78, "confidence": 0.991, "speaker": 0},
    {"word": "YourVoic.", "start": 0.80, "end": 1.25, "confidence": 0.982, "speaker": 0},
    {"word": "Our", "start": 1.45, "end": 1.62, "confidence": 0.989, "speaker": 0},
    {"word": "neural", "start": 1.65, "end": 1.98, "confidence": 0.994, "speaker": 0},
    {"word": "speech", "start": 2.01, "end": 2.34, "confidence": 0.992, "speaker": 0},
    {"word": "recognition", "start": 2.36, "end": 2.92, "confidence": 0.988, "speaker": 0},
    {"word": "engine", "start": 2.95, "end": 3.32, "confidence": 0.991, "speaker": 0},
    {"word": "transcribes", "start": 3.35, "end": 3.90, "confidence": 0.985, "speaker": 0},
    {"word": "audio", "start": 3.92, "end": 4.25, "confidence": 0.994, "speaker": 0},
    {"word": "accurately", "start": 4.28, "end": 4.88, "confidence": 0.989, "speaker": 0},
    {"word": "with", "start": 4.90, "end": 5.10, "confidence": 0.993, "speaker": 0},
    {"word": "zero", "start": 5.12, "end": 5.42, "confidence": 0.995, "speaker": 0},
    {"word": "setup.", "start": 5.45, "end": 5.95, "confidence": 0.984, "speaker": 0}
  ],
  "segments": [
    {
      "id": 0,
      "start": 0.18,
      "end": 1.25,
      "text": "Welcome to YourVoic.",
      "speaker": 0,
      "confidence": 0.989
    },
    {
      "id": 1,
      "start": 1.45,
      "end": 5.95,
      "text": "Our neural speech recognition engine transcribes audio accurately with zero setup.",
      "speaker": 0,
      "confidence": 0.986
    }
  ]
}

Audio Encoding Best Practices

• Sampling Frequency: Audio sampled at 16,000 Hz or 44,100/48,000 Hz yields optimal accuracy across phoneme detection models.
• Channel Count: Standard single-channel mono is recommended. Multi-channel audio is automatically mixed down without loss of speech clarity.
• File Formats: Supported file formats include WAV (uncompressed PCM), MP3, AAC, FLAC, OGG Vorbis, and WebM/Opus.