Language hints

Overview

Soniox Speech-to-Text AI is a powerful, multilingual model that transcribes speech in over 60 languages with exceptional accuracy. There is no need to pre-select a language — the model automatically detects and transcribes any supported language. It also handles multilingual audio seamlessly, even when multiple languages are mixed within a single sentence or conversation.

However, when you have prior knowledge of the languages likely to be spoken in your audio, you can use language hints to guide the model toward those languages for even greater recognition accuracy.

How language hints work

You can provide language hints using the language_hints parameter, passing in a list of expected language codes (e.g., en for English, es for Spanish).

These hints do not limit the model to only those languages — they simply bias the model toward recognizing the provided languages when possible.

This feature is supported in both:

• Asynchronous transcription
• Real-time transcription

Example: Hinting English and Spanish

{
  "language_hints": ["en", "es"]
}

This guides the model to prioritize English and Spanish during transcription, while still allowing it to detect other languages if they appear in the audio.

When to use language hints

Use language_hints when:

• You know or expect specific languages in the audio
• You want to improve accuracy for particular languages
• The audio includes uncommon or similar-sounding languages
• You're transcribing content for a known audience or market
• If no hints are provided, Soniox will default to fully automatic detection

Supported languages

Soniox Speech-to-Text AI supports over 60 languages. See the full list of supported languages and ISO codes on the Supported languages page.

Example

The following example demonstrates how to transcribe a file containing multiple languages, with language hints provided for English, Spanish, French, and Portuguese:

import os
import time
 
import requests
 
# Retrieve the API key from environment variable (ensure SONIOX_API_KEY is set)
api_key = os.environ["SONIOX_API_KEY"]
api_base = "https://api.soniox.com"
audio_url = "https://soniox.com/media/examples/coffee_shop.mp3"
 
session = requests.Session()
session.headers["Authorization"] = f"Bearer {api_key}"
 
 
def poll_until_complete(transcription_id):
    while True:
        res = session.get(f"{api_base}/v1/transcriptions/{transcription_id}")
        res.raise_for_status()
        data = res.json()
        if data["status"] == "completed":
            return
        elif data["status"] == "error":
            raise Exception(
                f"Transcription failed: {data.get('error_message', 'Unknown error')}"
            )
        time.sleep(1)
 
 
def main():
    print("Starting transcription...")
 
    res = session.post(
        f"{api_base}/v1/transcriptions",
        json={
            "audio_url": audio_url,
            "model": "stt-async-preview",
            "language_hints": ["en", "es"],
        },
    )
    res.raise_for_status()
    transcription_id = res.json()["id"]
    print(f"Transcription ID: {transcription_id}")
 
    poll_until_complete(transcription_id)
 
    # Get the transcript text
    res = session.get(f"{api_base}/v1/transcriptions/{transcription_id}/transcript")
    res.raise_for_status()
    print("Transcript:")
    print(res.json()["text"])
 
 
if __name__ == "__main__":
    main()