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

# Voz

> Transcribe audio y genera voz con la API de MKA1. Usa segmentos etiquetados por hablante cuando necesites separación de múltiples interlocutores.

Utiliza los endpoints de voz de la API de MKA1 cuando necesites transcripción de voz a texto basada en archivos o conversión de texto a voz.
Para sesiones de voz bidireccionales en tiempo real, usa el [Modo de voz avanzado](/es/docs/advanced-voice-mode).

## Elige el endpoint adecuado

| Caso de uso                                             | Endpoint                                                                              | Notas                                       |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------- |
| Transcribir un archivo grabado                          | [Transcripción de voz a texto](/es/api-reference/speech/speech-to-text-transcription) | Sube audio con `multipart/form-data`        |
| Generar un archivo WAV desde texto                      | [Texto a voz](/es/api-reference/speech/text-to-speech)                                | Mejor para generación de archivos completos |
| Iniciar la reproducción tan pronto como llegue el audio | [Texto a voz en streaming](/es/api-reference/speech/streaming-text-to-speech)         | Mejor para reproducción de baja latencia    |

## Transcribir audio

Envía un archivo de audio al endpoint de transcripción cuando quieras obtener texto de un archivo grabado.
Si tu aplicación actúa en nombre de un usuario final, también envía `X-On-Behalf-Of`.

Formatos de audio soportados: `FLAC`, `MP3`, `MP4`, `MPEG`, `MPGA`, `M4A`, `OGG`, `WAV`, `WebM`, `PCM`.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm speech transcribe \
    --file ./episode.wav \
    --language en \
    --prompt 'This is a technical podcast about machine learning.' \
    --temperature 0.2 \
    -H 'X-On-Behalf-Of: <end-user-id>'
  ```

  ```ts MKA1 SDK theme={null}
  import { SDK } from '@meetkai/mka1';
  import { openAsBlob } from 'node:fs';

  const mka1 = new SDK({
    bearerAuth: 'Bearer <mka1-api-key>',
  });

  const result = await mka1.llm.speech.transcribe({
    language: 'en',
    prompt: 'This is a technical podcast about machine learning.',
    temperature: 0.2,
    requestBody: {
      file: await openAsBlob('episode.wav'),
    },
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

  console.log(result.text);
  console.log(result.language);
  console.log(result.confidence);
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;
  using MeetKai.MKA1.Types.Requests;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var result = await sdk.Llm.Speech.TranscribeAsync(new TranscribeRequest()
  {
      Language = "en",
      Prompt = "This is a technical podcast about machine learning.",
      Temperature = 0.2,
      Body = new TranscribeRequestBody()
      {
          File = new TranscribeFile()
          {
              FileName = "episode.wav",
              Content = File.ReadAllBytes("episode.wav"),
          },
      },
  });

  Console.WriteLine(result.TranscriptionResponse!.Text);
  Console.WriteLine(result.TranscriptionResponse!.Language);
  Console.WriteLine(result.TranscriptionResponse!.Confidence);
  ```

  ```python Python SDK theme={null}
  from mka1 import SDK

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  result = sdk.llm.speech.transcribe(
      file={"file_name": "episode.wav", "content": open("episode.wav", "rb")},
      language="en",
      prompt="This is a technical podcast about machine learning.",
      temperature=0.2,
  )

  print(result.text)
  print(result.language)
  print(result.confidence)
  ```

  ```bash bash theme={null}
  curl 'https://apigw.mka1.com/api/v1/llm/speech/transcriptions?language=en&prompt=This%20is%20a%20technical%20podcast%20about%20machine%20learning.&temperature=0.2' \
    --request POST \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --form 'file=@episode.wav'
  ```
</CodeGroup>

La respuesta incluye el texto transcrito, además del idioma detectado y el nivel de confianza:

```json theme={null}
{
  "text": "Hello! We're excited to show you our native speech capabilities.",
  "language": "en",
  "confidence": 0.8429018476208717
}
```

## Separar hablantes en una transcripción

Si necesitas diarización, habilita los datos de hablante en la solicitud de transcripción.
Cuando está habilitado, la respuesta puede incluir un arreglo `speakers` con segmentos etiquetados por hablante y metadatos de tiempo.

<Warning>
  Para `include_speaker_data`, sube audio en formato WAV o PCM para transcripción no en streaming. Otros formatos de audio devuelven `400 BAD_REQUEST` con el mensaje `Speaker diarization currently requires WAV/PCM audio for non-streaming transcription`.
</Warning>

```ts theme={null}
const result = await mka1.llm.speech.transcribe({
  language: 'en',
  includeSpeakerData: true,
  prompt: 'This is a short podcast clip about AI product updates.',
  temperature: 0.2,
  requestBody: {
    file: await openAsBlob('panel.wav'),
  },
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

console.log(result.speakers);
```

Ejemplo de respuesta con separación de hablantes:

```json theme={null}
{
  "text": "Welcome back to the show. Today we're looking at how speech APIs fit into production apps. We'll keep it practical and focus on latency, accuracy, and speaker turns.",
  "language": "en",
  "confidence": 0.91177404,
  "speakers": [
    {
      "speaker": "Speaker-1",
      "text": "Welcome back to the show.",
      "confidence": 0.91177404,
      "offset_ms": 80,
      "duration_ms": 1280
    },
    {
      "speaker": "Speaker-2",
      "text": "Today we're looking at how speech APIs fit into production apps.",
      "confidence": 0.91177404,
      "offset_ms": 1540,
      "duration_ms": 3380
    },
    {
      "speaker": "Speaker-1",
      "text": "We'll keep it practical and focus on latency, accuracy, and speaker turns.",
      "confidence": 0.91177404,
      "offset_ms": 5220,
      "duration_ms": 3660
    }
  ]
}
```

Usa el campo `text` de nivel superior cuando necesites una transcripción unificada.
Usa `speakers` cuando necesites subtítulos, turnos de habla o análisis de hablantes posteriores.

## Generar voz

Utiliza el endpoint estándar de texto a voz cuando quieras un archivo WAV completo.
El cuerpo de la respuesta es audio binario y las cabeceras de la respuesta incluyen `X-Language-Code`.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm speech speak \
    --text 'Welcome to the MKA1 API speech guide.' \
    --language en \
    --output-file speech.wav
  ```

  ```ts MKA1 SDK theme={null}
  import { writeFileSync } from 'node:fs';

  const result = await mka1.llm.speech.speak({
    text: 'Welcome to the MKA1 API speech guide.',
    language: 'en',
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

  const audioBody = result.body as Blob | Uint8Array;
  const audioBuffer = audioBody instanceof Uint8Array
    ? Buffer.from(audioBody)
    : Buffer.from(await audioBody.arrayBuffer());
  const languageCode =
    result.headers['X-Language-Code'] ?? result.headers['x-language-code'];

  writeFileSync('speech.wav', audioBuffer);
  console.log(languageCode);
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var result = await sdk.Llm.Speech.SpeakAsync(new TextToSpeechRequest()
  {
      Text = "Welcome to the MKA1 API speech guide.",
      Language = TextToSpeechRequestLanguage.En,
  });

  File.WriteAllBytes("speech.wav", result.Bytes!);
  ```

  ```python Python SDK theme={null}
  result = sdk.llm.speech.speak(
      text="Welcome to the MKA1 API speech guide.",
      language="en",
  )

  with open("speech.wav", "wb") as f:
      f.write(result.body)
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/speech/tts \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "text": "Welcome to the MKA1 API speech guide.",
      "language": "en"
    }' \
    --output speech.wav
  ```
</CodeGroup>

## Transmitir voz para menor latencia

Utiliza texto a voz en streaming cuando quieras que la reproducción comience antes de que el archivo de audio esté completo.
Elige `mp3` para cargas útiles más pequeñas o `pcm` para audio sin comprimir.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm speech speak-streaming \
    --text 'Start speaking this response as soon as audio is ready.' \
    --language en \
    --format-param mp3 \
    --output-file speech.mp3
  ```

  ```ts MKA1 SDK theme={null}
  const result = await mka1.llm.speech.speakStreaming({
    text: 'Start speaking this response as soon as audio is ready.',
    language: 'en',
    format: 'mp3',
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

  const contentType =
    result.headers['Content-Type'] ?? result.headers['content-type'];
  const languageCode =
    result.headers['X-Language-Code'] ?? result.headers['x-language-code'];

  console.log(contentType);
  console.log(languageCode);
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  var result = await sdk.Llm.Speech.SpeakStreamingAsync(new TextToSpeechStreamingRequest()
  {
      Text = "Start speaking this response as soon as audio is ready.",
      Language = TextToSpeechStreamingRequestLanguage.En,
      Format = TextToSpeechStreamingRequestFormat.Mp3,
  });

  // Response contains either MP3 or WAV bytes depending on format
  var audioBytes = result.TwoHundredAudioMpegBytes ?? result.TwoHundredAudioWavBytes;
  File.WriteAllBytes("speech.mp3", audioBytes!);
  ```

  ```python Python SDK theme={null}
  result = sdk.llm.speech.speak_streaming(
      text="Start speaking this response as soon as audio is ready.",
      language="en",
      format="mp3",
  )

  with open("speech.mp3", "wb") as f:
      f.write(result.body)
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/speech/tts/stream \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "text": "Start speaking this response as soon as audio is ready.",
      "language": "en",
      "format": "mp3"
    }' \
    --output speech.mp3
  ```
</CodeGroup>

## Próximos pasos

* Revisa la referencia de [Transcripción de voz a texto](/es/api-reference/speech/speech-to-text-transcription) para detalles de solicitud y respuesta
* Revisa la referencia de [Texto a voz](/es/api-reference/speech/text-to-speech) para generación de WAV
* Revisa la referencia de [Texto a voz en streaming](/es/api-reference/speech/streaming-text-to-speech) para salida de baja latencia
* Usa el [Modo de voz avanzado](/es/docs/advanced-voice-mode) para conversaciones en tiempo real