Audio

Our audio endpoints are compatible with the OpenAI API, supporting the same v1/audio/speech and v1/audio/transcriptions formats.

Text-to-speech

Here is an example of text-to-speech: Parameters:

model: The model ID of the model you want to use
input: The text to convert to speech
response_format: The format of the audio output (default: “mp3”, options: “mp3”, “opus”, “aac”, “flac”, “wav”, “pcm”)
speed: The speed of the generated audio (0.25 to 4.0, default: 1.0)

from synapsai import SynapsAI

model = SynapsAI("your-api-key")

response = model.audio.speech.create(
    model="model-id",
    input="Hello, world!",
    response_format="mp3",
    speed=1.0
)

# Save to file
response.stream_to_file("speech.mp3")

curl -X POST https://api.synapsai.cloud/v1/audio/speech \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "input": "Hello, world!"
    }' \
  --output speech.mp3

Audio transcription

Here is an example of audio transcription with the updated API: Parameters:

model: The model ID of the model you want to use (required)
file: The audio file to transcribe (required)
language: The language of the audio input in ISO-639-1 format (e.g. “en”) (optional, auto-detected if not specified)
prompt: Optional prompt to guide transcription (max 244 characters)
response_format: Output format - “json”, “text”, “str”, “verbose_json”, “vtt” (default: “json”)
temperature: The sampling temperature (0.0 to 1.0, default: 0.0)
stream: Enable real-time streaming of transcription chunks (default: false)
timestamp_granularities: The timestamp granularities to include (optional, options: “word”, “segment”, “char”)
Advanced parameters: seed, top_p, top_k, n, frequency_penalty, presence_penalty, max_completion_tokens, to_language, repetition_penalty

from synapsai import SynapsAI

client = SynapsAI("your-api-key")

with open("audio.mp3", "rb") as file:
    response = client.audio.transcriptions.create(
        model="your-model-id",
        file=file,
        language="en"
    )

print(response.text)

from synapsai import SynapsAI

client = SynapsAI("your-api-key")

with open("audio.mp3", "rb") as file:
    response = client.audio.transcriptions.create(
        model="your-model-id",
        file=file,
        language="en",
        prompt="This is a business meeting about quarterly results",
        temperature=0.1,
        top_p=0.9,
        frequency_penalty=0.1,
        max_completion_tokens=500,
        timestamp_granularities=["word", "segment"],
        response_format="verbose_json"
    )

print(response.text)
print(f"Duration: {response.duration}s")
for word in response.words:
    print(f"{word.word}: {word.start}-{word.end}")

from synapsai import SynapsAI

client = SynapsAI("your-api-key")

# Sync streaming
for chunk in client.audio.transcriptions.create(
    model="your-model-id",
    file="path/to/audio.wav",
    language="en",
    stream=True,
    timestamp_granularities=["word"]
):
    print(f"Chunk: {chunk.text}", end="\r")
    if chunk.words:
        for word in chunk.words:
            print(f"  {word.word}: {word.start:.2f}-{word.end:.2f}")

import asyncio
from synapsai import AsyncSynapsAI

async def stream_transcription():
    client = AsyncSynapsAI("your-api-key")
    
    async for chunk in await client.audio.transcriptions.create(
        model="your-model-id",
        file="path/to/audio.wav",
        language="en",
        stream=True,
        temperature=0.2
    ):
        print(f"Live: {chunk.text}")
        
        if chunk.usage:
            print(f"Tokens used: {chunk.usage.total_tokens}")

asyncio.run(stream_transcription())

curl -X POST https://api.synapsai.cloud/v1/audio/transcriptions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="your-model-id" \
  -F file="@audio.mp3" \
  -F language="en"

curl -X POST https://api.synapsai.cloud/v1/audio/transcriptions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="your-model-id" \
  -F file="@audio.mp3" \
  -F language="en" \
  -F prompt="Business meeting about quarterly results" \
  -F temperature=0.1 \
  -F response_format="verbose_json" \
  -F timestamp_granularities[]=word \
  -F timestamp_granularities[]=segment

Audio translation

Here is an example of audio translation with the new API: Parameters:

model: The model ID of the model you want to use (required)
file: The audio file to translate (required)
language: The source language in ISO-639-1 format (optional, auto-detected if not specified)
prompt: Optional prompt to guide translation (max 244 characters)
response_format: Output format - “json”, “text”, “str”, “verbose_json”, “vtt” (default: “json”)
temperature: The sampling temperature (0.0 to 1.0, default: 0.0)
stream: Enable real-time streaming of translation chunks (default: false)
Advanced parameters: seed, top_p, top_k, n, frequency_penalty, presence_penalty, max_completion_tokens, to_language, repetition_penalty

from synapsai import SynapsAI

client = SynapsAI("your-api-key")

# Simple translation (auto-detects source language)
with open("spanish_audio.mp3", "rb") as file:
    response = client.audio.translations.create(
        model="your-model-id",
        file=file
    )

print(f"Detected language: {response.language}")
print(f"Translation: {response.text}")

from synapsai import SynapsAI

client = SynapsAI("your-api-key")

with open("french_audio.mp3", "rb") as file:
    response = client.audio.translations.create(
        model="your-model-id",
        file=file,
        language="fr",  # Specify source language
        prompt="This is a technical presentation about AI",
        temperature=0.1,
        top_p=0.9,
        frequency_penalty=0.1,
        response_format="verbose_json"
    )

print(f"Source: {response.language}")
print(f"Translation: {response.text}")
print(f"Duration: {response.duration}s")

from synapsai import SynapsAI

client = SynapsAI("your-api-key")

# Sync streaming with language detection
for chunk in client.audio.translations.create(
    model="your-model-id",
    file="path/to/multilingual_audio.wav",
    stream=True,
    temperature=0.2
):
    print(f"Detected: {chunk.language or 'Unknown'}")
    print(f"Translation: {chunk.text}")
    
    if chunk.segments:
        for segment in chunk.segments:
            print(f"  [{segment.start:.2f}-{segment.end:.2f}] {segment.text}")

import asyncio
from synapsai import AsyncSynapsAI

async def stream_translation():
    client = AsyncSynapsAI("your-api-key")
    
    async for chunk in await client.audio.translations.create(
        model="your-model-id",
        file="path/to/german_audio.wav",
        stream=True,
        language="de",  # Specify German source
        temperature=0.1
    ):
        print(f"German → English: {chunk.text}")
        
        if chunk.usage:
            print(f"Translation complete. Tokens: {chunk.usage.total_tokens}")

asyncio.run(stream_translation())

curl -X POST https://api.synapsai.cloud/v1/audio/translations \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="your-model-id" \
  -F file="@spanish_audio.mp3"

curl -X POST https://api.synapsai.cloud/v1/audio/translations \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F model="your-model-id" \
  -F file="@french_audio.mp3" \
  -F language="fr" \
  -F prompt="Technical presentation about AI" \
  -F temperature=0.1 \
  -F response_format="verbose_json"

Error Handling

Common Errors

Invalid audio format: Ensure file is WAV, MP3, M4A, etc.
File too large: Check model limits (typically 25MB)
Unsupported language: Verify language codes are ISO-639-1
Stream parsing errors: Chunks are logged and skipped automatically

Error Response Example

try:
    response = client.audio.transcriptions.create(
        model="your-model-id",
        file="invalid_file.xyz"
    )
except synapsai.APIError as e:
    print(f"API Error: {e}")
    print(f"Status: {e.status_code}")

Best Practices

For Accuracy

Use prompt with context about the audio content
Set temperature low (0.0-0.3) for consistent results
Specify language when known to improve accuracy

For Performance

Use streaming (stream=True) for long audio files
Set appropriate max_completion_tokens to limit output
Consider top_p/top_k for faster generation

For Real-time Applications

Always use streaming with timestamp_granularities=["word"]
Handle chunk parsing errors gracefully
Accumulate text chunks for complete transcription

You can also try text-to-speech, transcription, and translation using the Playground. For deeper insights into the audio endpoints, see our API reference.

Getting started

Guides

Examples

Manage

Platform

Resources

Support

Legal

Text-to-speech

Audio transcription

Audio translation

Error Handling

Common Errors

Error Response Example

Best Practices

For Accuracy

For Performance

For Real-time Applications

​Text-to-speech

​Audio transcription

​Audio translation

​Error Handling

​Common Errors

​Error Response Example

​Best Practices

​For Accuracy

​For Performance

​For Real-time Applications

Text-to-speech

Audio transcription

Audio translation

Error Handling

Common Errors

Error Response Example

Best Practices

For Accuracy

For Performance

For Real-time Applications