Saltar para o conteúdo principal
Use os endpoints de speech da MKA1 API quando precisar de speech-to-text baseado em arquivo ou de text-to-speech. Para sessões de voz bidirecionais em tempo real, use Advanced voice mode.

​
Escolha o endpoint certo

Caso de usoEndpointObservações
Transcrever um arquivo gravadoSpeech-to-text transcriptionEnvie o áudio com multipart/form-data
Gerar um arquivo WAV a partir de textoText-to-speechMelhor para geração completa de arquivo
Iniciar a reprodução assim que o áudio chegarStreaming text-to-speechMelhor para reprodução com baixa latência

​
Transcreva áudio

Envie um arquivo de áudio para o endpoint de transcrição quando quiser saída em texto a partir de um arquivo gravado. Se sua aplicação atuar em nome de um end user, envie também X-On-Behalf-Of. Formatos de áudio compatíveis: FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV, WebM, PCM. 
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);
A resposta inclui o texto transcrito, além do idioma detectado e do nível de confiança: 
{
  "text": "Hello! We're excited to show you our native speech capabilities.",
  "language": "en",
  "confidence": 0.8429018476208717
}

​
Separe falantes em uma única transcrição

Se você precisar de diarização, habilite os dados de falante na requisição de transcrição. Quando habilitada, a resposta pode incluir um array speakers com segmentos identificados por falante e metadados de tempo.
Para includeSpeakerData, envie áudio WAV ou PCM na transcrição não 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({
  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);
Exemplo de resposta com separação de falantes: 
{
  "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
    }
  ]
}
Use o campo text de nível superior quando precisar de uma única transcrição consolidada. Use speakers quando precisar de legendas, alternância de turnos ou análise de falantes em etapas posteriores.

​
Gere fala

Use o endpoint padrão de text-to-speech quando quiser um arquivo WAV completo. O corpo da resposta é áudio binário, e os cabeçalhos da resposta incluem X-Language-Code. 
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);

​
Faça streaming de fala para menor latência

Use streaming text-to-speech quando quiser iniciar a reprodução antes de o arquivo completo de áudio estar pronto. Escolha mp3 para payloads menores ou pcm para áudio sem compressão. 
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);

​
Próximos passos