Python (SDK)

from mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.llm.speech.transcribe(file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    }, model="auto", language="en", include_speaker_data=True, prompt="This is a technical podcast about machine learning.", temperature=0.2)

    # Handle response
    print(res)

{
  "text": "Hello, this is a sample transcription of the audio file.",
  "language": "en",
  "confidence": 0.95,
  "speakers": [
    {
      "speaker": "Speaker-1",
      "text": "Hello, this is a sample transcription of the audio file.",
      "confidence": 0.95,
      "offset_ms": 0,
      "duration_ms": 2100
    }
  ]
}

Speech

Transcrição de fala para texto

Converta áudio em texto usando reconhecimento de fala avançado.

Upload de Arquivo Completo (Padrão)
Use Content-Type: multipart/form-data para enviar o arquivo de áudio completo em uma única solicitação. Tamanho máximo do arquivo: 25MB.

Exemplo:

curl -X POST "http://localhost:3000/api/v1/llm/speech/transcriptions?language=pt-BR" \
  -F "file=@audio.flac"

Upload em Fragmentos (Streaming)
Use o cabeçalho Transfer-Encoding: chunked para transmitir dados de áudio em fragmentos enquanto estão sendo gravados. Não é necessário saber o tamanho total do arquivo com antecedência. O servidor armazena os fragmentos até que estejam completos antes de processar. Tamanho total máximo: 25MB.

Exemplo:

curl -X POST "http://localhost:3000/api/v1/llm/speech/transcriptions?language=pt-BR" \
  -H "Transfer-Encoding: chunked" \
  -H "Content-Type: multipart/form-data" \
  --data-binary @audio.flac

Formatos Suportados: FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV, WebM

Parâmetros de Consulta:

model (opcional): Identificador do modelo de transcrição. Padrão é ‘auto’.
language (opcional): Código de idioma ISO-639-1 ou BCP-47 (por exemplo, “pt-BR”). Detecta automaticamente se não especificado.
prompt (opcional): Parâmetro de prompt legado mantido para compatibilidade retroativa.
temperature (opcional): Parâmetro de temperatura legado mantido para compatibilidade retroativa.
include_speaker_data (opcional): Quando true, inclui dados de diarização do orador e requer entrada WAV/PCM. Caso contrário, a transcrição utiliza o caminho de compatibilidade padrão.

Resposta: Retorna o texto transcrito em formato JSON.

POST

api

llm

speech

transcriptions

Python (SDK)

from mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.llm.speech.transcribe(file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    }, model="auto", language="en", include_speaker_data=True, prompt="This is a technical podcast about machine learning.", temperature=0.2)

    # Handle response
    print(res)

{
  "text": "Hello, this is a sample transcription of the audio file.",
  "language": "en",
  "confidence": 0.95,
  "speakers": [
    {
      "speaker": "Speaker-1",
      "text": "Hello, this is a sample transcription of the audio file.",
      "confidence": 0.95,
      "offset_ms": 0,
      "duration_ms": 2100
    }
  ]
}

Autorizações

Authorization

string

header

obrigatório

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Cabeçalhos

X-On-Behalf-Of

string

Optional external end-user identifier forwarded by the API gateway.

Parâmetros de consulta

model

string

padrão:auto

Identificador do modelo de transcrição. O padrão é 'auto', que seleciona o melhor modelo disponível. Ignorado quando a diarização de falantes é solicitada.

Exemplo:

"auto"

language

string

O idioma do áudio de entrada no formato ISO-639-1 ou BCP-47 (por exemplo, 'pt' ou 'pt-BR'). Se não for especificado, o serviço de transcrição detecta automaticamente o idioma.

Exemplo:

"en"

include_speaker_data

boolean

padrão:false

Se deve incluir dados de segmentos de falantes. O padrão é falso. Quando verdadeiro, a resposta inclui um array de falantes dividido por falante detectado.

Exemplo:

true

prompt

string

Parâmetro de prompt legado mantido para compatibilidade retroativa. Usado apenas pelo caminho de fallback para uploads que não são WAV.

Exemplo:

"This is a technical podcast about machine learning."

temperature

number

Parâmetro de temperatura legado mantido para compatibilidade com versões anteriores. Usado apenas pelo caminho de fallback para uploads não WAV.

Intervalo obrigatório: 0 <= x <= 1

Exemplo:

0.2

Corpo

multipart/form-data

file

obrigatório

Arquivo de áudio para transcrição.

Requisitos do Arquivo:

Tamanho máximo: 25MB
Formatos suportados: FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV, WebM
A diagramação de falantes atualmente requer entrada WAV / PCM

Opções de Upload:

Padrão: Carregar arquivo completo usando multipart/form-data
Em partes: Transmitir partes do arquivo usando o cabeçalho Transfer-Encoding: chunked (útil para gravação em tempo real)

Nota: Para uploads em partes, o servidor armazena em buffer todas as partes antes do processamento. A transcrição começa apenas após o recebimento do arquivo completo.

Resposta

200 - application/json

Resposta do endpoint de transcrição contendo o texto transcrito, idioma detectado, pontuação de confiança e segmentos de falantes opcionais.

text

string

obrigatório

O texto transcrito do arquivo de áudio

language

string

O código de idioma detectado ou especificado no formato ISO-639-1 (por exemplo, 'en', 'es', 'fr')

confidence

number

Pontuação de confiança de 0 a 1, onde 1 indica a maior confiança na precisão da transcrição.

speakers

object[]

Segmentos de diarização de falantes, retornados apenas quando include_speaker_data é verdadeiro.

Show child attributes

Listar habilidades pré-configuradas

Texto para fala

⌘I

Documentation Index

Autorizações

Cabeçalhos

Parâmetros de consulta

Corpo

Resposta