> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio

> Examples of audio transcription and text-to-speech with SynapsAI Cloud

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)

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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
  ```
</CodeGroup>

## 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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (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`

<CodeGroup>
  ```python title="Python - Basic Transcription" theme={null}
  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)
  ```

  ```python title="Python - Advanced Transcription" theme={null}
  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}")
  ```

  ```python title="Python - Streaming Transcription" theme={null}
  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}")
  ```

  ```python title="Python - Async Streaming" theme={null}
  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 title="cURL - Basic" theme={null}
  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 title="cURL - Advanced" theme={null}
  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
  ```
</CodeGroup>

## 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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (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`

<CodeGroup>
  ```python title="Python - Basic Translation" theme={null}
  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}")
  ```

  ```python title="Python - Advanced Translation" theme={null}
  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")
  ```

  ```python title="Python - Streaming Translation" theme={null}
  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}")
  ```

  ```python title="Python - Async Streaming Translation" theme={null}
  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 title="cURL - Basic Translation" theme={null}
  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 title="cURL - Advanced Translation" theme={null}
  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"
  ```
</CodeGroup>

## 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

```python theme={null}
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](https://platform.synapsai.cloud/playground). For deeper insights into the audio endpoints, see our [API reference](https://docs.synapsai.cloud/api-reference/transcribe-audio-to-text).