Fala

Use os endpoints de fala da API MKA1 quando precisar de conversão de fala em texto baseada em arquivo ou de texto em fala. Para sessões de voz bidirecionais em tempo real, use o Modo de voz avançado.

Escolha o endpoint certo

Caso de uso	Endpoint	Observações
Transcrever um arquivo gravado	Transcrição de fala em texto	Envie áudio usando `multipart/form-data`
Gerar um arquivo WAV a partir de texto	Texto em fala	Ideal para geração de arquivos completos
Iniciar a reprodução assim que o áudio chegar	Texto em fala por streaming	Ideal para reprodução de baixa latência

Transcreva áudio

Envie um arquivo de áudio ao endpoint de transcrição quando quiser saída de texto de um arquivo gravado. Se o seu aplicativo agir em nome de um usuário final, envie também X-On-Behalf-Of. Formatos de áudio compatíveis: FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV, WebM. Para salvar a transcrição (e o áudio de entrada) no histórico, defina store=true.

mka1 llm speech transcribe \
  --file ./episode.wav \
  --language en \
  --prompt 'Este é um podcast técnico sobre aprendizado de máquina.' \
  --temperature 0.2 \
  --store \
  -H 'X-On-Behalf-Of: <end-user-id>'

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({
  xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
  language: 'en',
  prompt: 'Este é um podcast técnico sobre aprendizado de máquina.',
  temperature: 0.2,
  store: true,
  requestBody: {
    file: await openAsBlob('episode.wav'),
  },
});

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

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 = "Este é um podcast técnico sobre aprendizado de máquina.",
    Temperature = 0.2,
    Store = true,
    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);

from meetkai_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="Este é um podcast técnico sobre aprendizado de máquina.",
    temperature=0.2,
    store=True,
)

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

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

A resposta inclui o texto da transcrição, além do idioma detectado e da confiança:

{
  "text": "Olá! Estamos animados para mostrar nossos recursos nativos de fala.",
  "language": "en",
  "confidence": 0.8429018476208717
}

Separe locutores em uma transcrição

Se precisar de diarização, ative os dados de locutor na solicitação de transcrição. Quando ativada, a resposta pode incluir uma matriz speakers com segmentos rotulados por locutor e metadados de tempo.

Para include_speaker_data, envie áudio WAV ou PCM para transcrição sem streaming. Outros formatos de áudio retornam 400 BAD_REQUEST com a mensagem Speaker diarization currently requires WAV/PCM audio for non-streaming transcription.

const result = await mka1.llm.speech.transcribe({
  xOnBehalfOf: '<end-user-id>',
  language: 'en',
  includeSpeakerData: true,
  prompt: 'Este é um pequeno trecho de podcast sobre atualizações de produtos de IA.',
  temperature: 0.2,
  requestBody: {
    file: await openAsBlob('panel.wav'),
  },
});

console.log(result.speakers);

Exemplo de resposta com separação de locutores:

{
  "text": "Bem-vindos de volta ao programa. Hoje veremos como as APIs de fala se encaixam em aplicativos de produção. Vamos manter a abordagem prática e focar em latência, precisão e alternância entre locutores.",
  "language": "en",
  "confidence": 0.91177404,
  "speakers": [
    {
      "speaker": "Speaker-1",
      "text": "Bem-vindos de volta ao programa.",
      "confidence": 0.91177404,
      "offset_ms": 80,
      "duration_ms": 1280
    },
    {
      "speaker": "Speaker-2",
      "text": "Hoje veremos como as APIs de fala se encaixam em aplicativos de produção.",
      "confidence": 0.91177404,
      "offset_ms": 1540,
      "duration_ms": 3380
    },
    {
      "speaker": "Speaker-1",
      "text": "Vamos manter a abordagem prática e focar em latência, precisão e alternância entre locutores.",
      "confidence": 0.91177404,
      "offset_ms": 5220,
      "duration_ms": 3660
    }
  ]
}

Use o campo text de nível superior quando precisar de uma única transcrição combinada. Use speakers quando precisar de legendas, alternância de turnos ou análises posteriores de locutores.

Gere fala

Use o endpoint padrão de texto em fala quando quiser um arquivo WAV completo. O corpo da resposta é áudio binário, e os cabeçalhos da resposta incluem X-Language-Code. Para salvar o áudio gerado no histórico, defina store=true. Quando armazenada, a resposta também inclui X-Tts-Id.

mka1 llm speech speak \
  --text 'Bem-vindo ao guia de fala da API MKA1.' \
  --language en \
  --store \
  --output-file speech.wav

import { writeFileSync } from 'node:fs';

const result = await mka1.llm.speech.speak({
  xOnBehalfOf: '<end-user-id>',
  textToSpeechRequest: {
    text: 'Bem-vindo ao guia de fala da API MKA1.',
    language: 'en',
    store: true,
  },
});

const audioBuffer = Buffer.from(await new Response(result.result).arrayBuffer());
const languageCode = result.headers['x-language-code']?.[0];
const ttsId = result.headers['x-tts-id']?.[0];

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

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 = "Bem-vindo ao guia de fala da API MKA1.",
    Language = TextToSpeechRequestLanguage.En,
    Store = true,
});

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

result = sdk.llm.speech.speak(
    text="Bem-vindo ao guia de fala da API MKA1.",
    language="en",
    store=True,
)

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

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": "Bem-vindo ao guia de fala da API MKA1.",
    "language": "en",
    "store": true
  }' \
  --output speech.wav

Transmita fala para menor latência

Use texto em fala por streaming quando quiser que a reprodução comece antes de o arquivo de áudio completo estar pronto. Escolha mp3 para cargas menores ou pcm para áudio não compactado. Para salvar o áudio gerado no histórico, defina store=true. Quando armazenada, a resposta inclui X-Tts-Id. A persistência do histórico para streaming ocorre conforme possível e é concluída pouco após o fim do stream, portanto uma consulta imediata por X-Tts-Id pode retornar brevemente 404. Se a persistência falhar ou for ignorada, o ID nunca será atribuído e as consultas continuarão retornando 404.

mka1 llm speech speak-streaming \
  --text 'Comece a falar esta resposta assim que o áudio estiver pronto.' \
  --language en \
  --format mp3 \
  --store \
  --output-file speech.mp3

const result = await mka1.llm.speech.speakStreaming({
  xOnBehalfOf: '<end-user-id>',
  textToSpeechStreamingRequest: {
    text: 'Comece a falar esta resposta assim que o áudio estiver pronto.',
    language: 'en',
    format: 'mp3',
    store: true,
  },
});

const contentType = result.headers['content-type']?.[0];
const languageCode = result.headers['x-language-code']?.[0];
const ttsId = result.headers['x-tts-id']?.[0];

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

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 = "Comece a falar esta resposta assim que o áudio estiver pronto.",
    Language = TextToSpeechStreamingRequestLanguage.En,
    Format = TextToSpeechStreamingRequestFormat.Mp3,
    Store = true,
});

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

result = sdk.llm.speech.speak_streaming(
    text="Comece a falar esta resposta assim que o áudio estiver pronto.",
    language="en",
    format="mp3",
    store=True,
)

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

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": "Comece a falar esta resposta assim que o áudio estiver pronto.",
    "language": "en",
    "format": "mp3",
    "store": true
  }' \
  --output speech.mp3

Próximas etapas

Consulte a referência de Transcrição de fala em texto para obter detalhes da solicitação e da resposta
Consulte a referência de Texto em fala para geração de WAV
Consulte a referência de Texto em fala por streaming para saída de baixa latência
Use o Modo de voz avançado para conversas em tempo real

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Escolha o endpoint certo

Transcreva áudio

Separe locutores em uma transcrição

Gere fala

Transmita fala para menor latência

Próximas etapas

​Escolha o endpoint certo

​Transcreva áudio

​Separe locutores em uma transcrição

​Gere fala

​Transmita fala para menor latência

​Próximas etapas

Escolha o endpoint certo

Transcreva áudio

Separe locutores em uma transcrição

Gere fala

Transmita fala para menor latência

Próximas etapas