v1.0.0

Referencia API

Integre a tradução e transcrição do Morlivo em sua aplicação com poucas linhas de código.

URL Base: https://api.morlivo.ai Autenticacao: Authorization: Bearer mrl_...

Autenticacao

Todas as solicitações de API requerem um token Bearer. Obtenha sua chave de API no painel em Configurações.

Cabeçalho
Authorization: Bearer mrl_your_api_key_here

As chaves API comecam com mrl_. Mantenha-as em segredo. Faça a rotação pelo painel se comprometidas.

POST

/v1/translate

Traduza texto de um idioma para outro. O idioma de origem é detectado automaticamente se omitido.

Corpo da solicitação JSON

CampoTipoObrigatorioDescricao
textstringsimTexto para traduzir
target_languagestringsimCódigo ISO 639-1 (ex. es, fr, de)
source_languagestringnaoDetectado automaticamente se omitido
project_idintegernaoAplicar glossário e estilo do projeto
formalitystringnaoRegister: formal, informal, or default

Resposta 200

CampoTipoDescricao
translated_textstringO texto traduzido
source_languagestringIdioma de origem detectado ou fornecido
target_languagestringCódigo do idioma de destino
confidencefloatPontuação de qualidade 0.0 - 1.0
validationobjectResultados da validação de qualidade

Exemplos

curl
curl -X POST https://api.morlivo.ai/api/v1/translate \
  -H "Authorization: Bearer mrl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "target_language": "es"
  }'
Python
import httpx

resp = httpx.post(
    "https://api.morlivo.ai/api/v1/translate",
    headers={"Authorization": "Bearer mrl_your_key"},
    json={
        "text": "Hello, world!",
        "target_language": "es",
    },
)
data = resp.json()
print(data["translated_text"])
# → "¡Hola, mundo!"
JavaScript
const resp = await fetch(
  "https://api.morlivo.ai/api/v1/translate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer mrl_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Hello, world!",
      target_language: "es",
    }),
  }
);
const data = await resp.json();
console.log(data.translated_text);
// → "¡Hola, mundo!"
Resposta
{
  "translated_text": "¡Hola, mundo!",
  "source_language": "en",
  "target_language": "es",
  "confidence": 0.98,
  "validation": {
    "length_ratio": 1.08,
    "language_match": true,
    "passed": true
  }
}
POST

/v1/transcribe

Transcreva um arquivo de áudio ou vídeo para texto. Suporta até 100 MB.

Corpo da solicitação multipart/form-data

CampoTipoObrigatorioDescricao
filefilesimArquivo de áudio/vídeo (mp3, wav, mp4, webm, etc.)
languagestringnaoCódigo ISO, detectado automaticamente se omitido
project_idintegernaoVincular a um projeto para rastreamento
response_formatstringnaoOutput format: json, verbose_json, text, srt, vtt
punctuatebooleannaoInclude punctuation (default true)

Resposta 200

CampoTipoDescricao
textstringTexto transcrito completo
languagestringIdioma detectado
duration_secondsfloatDuração do áudio
confidencefloatPontuação de qualidade 0.0 - 1.0
language_confidencefloatConfidence of auto-detected language (null if language was specified)
segmentsarraySegmentos com marcação de tempo
validationobjectVerificações de qualidade

Exemplos

curl
curl -X POST https://api.morlivo.ai/api/v1/transcribe \
  -H "Authorization: Bearer mrl_your_key" \
  -F "file=@meeting.mp3" \
  -F "language=en"
Python
import httpx

with open("meeting.mp3", "rb") as f:
    resp = httpx.post(
        "https://api.morlivo.ai/api/v1/transcribe",
        headers={"Authorization": "Bearer mrl_your_key"},
        files={"file": ("meeting.mp3", f, "audio/mpeg")},
        data={"language": "en"},
    )
data = resp.json()
print(data["text"])
Resposta
{
  "text": "Welcome everyone to today's meeting...",
  "language": "en",
  "duration_seconds": 342.5,
  "confidence": 0.95,
  "language_confidence": 0.95,
  "segments": [
    {"start": 0.0, "end": 3.2, "text": "Welcome everyone"},
    {"start": 3.2, "end": 6.8, "text": "to today's meeting."}
  ],
  "validation": {
    "words_per_minute": 148,
    "repetition_detected": false,
    "passed": true
  }
}
WebSocket

/v1/live/transcribe

Transmita áudio em tempo real e receba resultados de transcrição ao vivo.

Conexão

ParâmetroTipoObrigatorioDescricao
tokenstringsimChave de API como parâmetro de consulta
languagestringnaoDica de idioma de origem (ex.: en, fr). Detectado automaticamente se omitido.

Protocolo

Enviar

Quadros de áudio PCM binário (16-bit, 16kHz mono)

Receber

Mensagens JSON com campo type: transcript (texto parcial/final), status (eventos da sessão), error

Mensagens recebidas

CampoTipoDescricao
typestring"transcript" | "status" | "error"
textstringTexto transcrito (em mensagens de transcrição)
is_finalbooleanVerdadeiro quando o segmento estiver completo
languagestringCódigo do idioma detectado

Exemplos

JavaScript
const ws = new WebSocket(
  "wss://live.morlivo.ai/v1/live/transcribe?token=mrl_your_key&language=en"
);

navigator.mediaDevices.getUserMedia({ audio: true })
  .then(stream => {
    const ctx = new AudioContext({ sampleRate: 16000 });
    const source = ctx.createMediaStreamSource(stream);
    const processor = ctx.createScriptProcessor(4096, 1, 1);

    source.connect(processor);
    processor.connect(ctx.destination);
    processor.onaudioprocess = (e) => {
      const pcm = e.inputBuffer.getChannelData(0);
      const int16 = new Int16Array(pcm.length);
      for (let i = 0; i < pcm.length; i++)
        int16[i] = Math.max(-1, Math.min(1, pcm[i])) * 0x7FFF;
      ws.send(int16.buffer);
    };
  });

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "transcript") {
    console.log(msg.is_final ? "FINAL:" : "partial:", msg.text);
  }
};
Python
import asyncio, json, websockets

async def live_transcribe():
    uri = "wss://live.morlivo.ai/v1/live/transcribe?token=mrl_your_key"
    async with websockets.connect(uri) as ws:
        # Send audio chunks (PCM 16-bit 16kHz mono)
        with open("audio.pcm", "rb") as f:
            while chunk := f.read(4096):
                await ws.send(chunk)
                msg = json.loads(await ws.recv())
                if msg["type"] == "transcript":
                    print(msg["text"], end="\r" if not msg["is_final"] else "\n")

asyncio.run(live_transcribe())
Exemplos de mensagens
// Session started
{"type": "status", "message": "session_started"}

// Partial transcript (still speaking)
{"type": "transcript", "text": "Hello every", "is_final": false}

// Final transcript (segment complete)
{"type": "transcript", "text": "Hello everyone, welcome to the meeting.",
 "is_final": true, "language": "en"}

// Session ended
{"type": "status", "message": "session_ended",
 "duration_seconds": 45.2}
WebSocket

/v1/live/translate

Transmita áudio em um idioma e receba texto traduzido em outro idioma em tempo real. Suporta tradução de fala para texto com detecção automática de idioma.

Conexão

ParâmetroTipoObrigatorioDescricao
tokenstringsimChave de API como parâmetro de consulta
target_languagestringsimIdioma do texto de saída (ex.: en, es, fr)
source_languagestringnaoIdioma do áudio de origem. Detectado automaticamente se omitido.

Protocolo

Enviar

Quadros de áudio PCM binário (16-bit, 16kHz mono)

Receber

Mensagens JSON com texto traduzido em target_language. Inclui tanto a transcrição da fala original quanto a saída traduzida.

Mensagens recebidas

CampoTipoDescricao
typestring"transcript" | "status" | "error"
textstringTexto traduzido no idioma de destino
is_finalbooleanVerdadeiro quando o segmento estiver completo
source_languagestringIdioma de origem detectado
target_languagestringCódigo do idioma de destino

Exemplos

JavaScript
const ws = new WebSocket(
  "wss://live.morlivo.ai/v1/live/translate" +
  "?token=mrl_your_key&target_language=es&source_language=en"
);

// Stream microphone audio (same setup as live transcribe)
// ...

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "transcript" && msg.is_final) {
    console.log(`[${msg.source_language} → ${msg.target_language}]`);
    console.log(msg.text);
  }
};
Python
import asyncio, json, websockets

async def live_translate():
    uri = (
        "wss://live.morlivo.ai/v1/live/translate"
        "?token=mrl_your_key"
        "&source_language=fr&target_language=en"
    )
    async with websockets.connect(uri) as ws:
        with open("french_audio.pcm", "rb") as f:
            while chunk := f.read(4096):
                await ws.send(chunk)
                msg = json.loads(await ws.recv())
                if msg["type"] == "transcript" and msg["is_final"]:
                    print(f"Translation: {msg['text']}")

asyncio.run(live_translate())
Exemplos de mensagens
// Partial translation
{"type": "transcript", "text": "Hello every",
 "is_final": false, "source_language": "fr", "target_language": "en"}

// Final translated segment
{"type": "transcript",
 "text": "Hello everyone, welcome to the meeting.",
 "is_final": true,
 "source_language": "fr", "target_language": "en"}

// Session summary
{"type": "status", "message": "session_ended",
 "duration_seconds": 120.5}
POST

/v1/live/rooms

Create a multi-participant translation room. Each participant speaks their own language and receives translated text from other participants.

Corpo da solicitação JSON

CampoTipoObrigatorioDescricao
languagesobjectsimParticipant ID to language mapping
bridge_languagestringnaoHub language, default en
max_participantsintnaoMax participants 2-10, default 10
modestringnaointerpreter or inline

Resposta 200

CampoTipoDescricao
room_idstringUnique room identifier
statusstringRoom status
languagesobjectParticipant ID to language mapping
bridge_languagestringHub language used for translation
modestringTranslation mode
max_participantsintMaximum number of participants

Exemplos

curl
curl -X POST https://api.morlivo.ai/api/v1/live/rooms \
  -H "Authorization: Bearer mrl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {"alice": "en", "bob": "fr", "carlos": "es"},
    "bridge_language": "en",
    "mode": "interpreter"
  }'
Resposta
{
  "room_id": "room_abc123",
  "status": "active",
  "languages": {"alice": "en", "bob": "fr", "carlos": "es"},
  "bridge_language": "en",
  "mode": "interpreter",
  "max_participants": 10
}
WebSocket

/v1/live/speech/{room_id}

Connect a participant to a room for real-time speech translation.

Conexão

ParâmetroTipoObrigatorioDescricao
room_idstringsimRoom ID from create room response (path param)
participantstringsimParticipant ID (query param)
tokenstringsimChave de API como parâmetro de consulta

Exemplo

JavaScript
const ws = new WebSocket(
  "wss://live.morlivo.ai/v1/live/speech/room_abc123" +
  "?token=mrl_your_key&participant=alice"
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "transcript" && msg.is_final) {
    console.log(`[${msg.source_language} → ${msg.target_language}]`);
    console.log(msg.text);
  }
};
POST

/v1/live/rooms/{room_id}/participants

Add a participant to an existing room after creation.

Corpo da solicitação JSON

CampoTipoObrigatorioDescricao
participant_idstringsimUnique participant identifier
languagestringsimParticipant's language code

Exemplo

curl
curl -X POST https://api.morlivo.ai/api/v1/live/rooms/room_abc123/participants \
  -H "Authorization: Bearer mrl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "diana",
    "language": "de"
  }'
GET

/v1/languages

List all supported languages with locale, name, and availability status.

Resposta 200

CampoTipoDescricao
languagesarrayList of supported languages
languages[].localestringLocale code e.g. fr-CA
languages[].namestringEnglish name
languages[].native_namestringNative name
languages[].countrystringCountry/region
languages[].statusstringga or beta

Exemplo

curl
curl https://api.morlivo.ai/api/v1/languages \
  -H "Authorization: Bearer mrl_your_key"
Resposta
{
  "languages": [
    {"locale": "en-US", "name": "English", "native_name": "English", "country": "United States", "status": "ga"},
    {"locale": "fr-CA", "name": "French", "native_name": "Français", "country": "Canada", "status": "ga"},
    {"locale": "sw-KE", "name": "Swahili", "native_name": "Kiswahili", "country": "Kenya", "status": "beta"}
  ]
}
GET

/v1/health

Check API status and database health. No authentication required.

Resposta 200

CampoTipoDescricao
statusstringsaudável ou degradado

Exemplo

curl
curl https://api.morlivo.ai/api/v1/health
Resposta
{
  "status": "healthy"
}

Endpoints de Compatibilidade

Já usa outro provedor? Altere uma URL e mantenha seu código existente. Esses endpoints espelham os formatos de solicitação e resposta das principais APIs de tradução e transcrição.

DL

DeepL

Traducao
POST /api/compat/deepl/v2/translate

Substituição direta para api-free.deepl.com

G

Google Cloud Translation

Traducao
POST /api/compat/google/v3/projects/{"{p}"}/locations/{"{l}"}:translateText

Substituição direta para translation.googleapis.com

A

AWS Translate

Traducao
POST /api/compat/aws/translate

Substituição direta para translate.amazonaws.com

OA

OpenAI Whisper

Transcricao
POST /api/compat/openai/v1/audio/transcriptions

Substituição direta para api.openai.com

DG

Deepgram

Transcricao
POST /api/compat/deepgram/v1/listen

Substituição direta para api.deepgram.com

Os endpoints de compatibilidade aceitam o mesmo formato de solicitação e retornam a mesma estrutura de resposta do provedor original. Consulte a documentação de cada provedor para seus esquemas de solicitação/resposta.

Erros

Todos os erros retornam um objeto JSON com um campo detail.

CodigoSignificadoQuando acontece
400 Requisicao Invalida Campos obrigatórios ausentes, texto vazio, tipo de arquivo não suportado
401 Nao Autorizado Chave de API ausente ou inválida
403 Proibido Chave API valida mas permissoes insuficientes ou cota excedida
413 Carga Muito Grande O arquivo excede o limite de upload de 100 MB
429 Limite de Taxa Muitas solicitações. Tente novamente com backoff exponencial.
500 Erro Interno Erro inesperado do servidor. Contate o suporte se persistir.
503 Servico Indisponivel Modelo de IA temporariamente indisponível (circuit breaker aberto). Tente novamente em breve.
Formato de resposta de erro
{
  "detail": "Field 'text' must not be empty."
}
POST

Redação de PII

Adicione redação de PII a qualquer solicitação de tradução ou transcrição. Especifique quais tipos de entidade detectar e redigir.

POST /v1/translate POST /v1/transcribe

Corpo da solicitação JSON

CampoTipoObrigatorioDescricao
textstringsimTexto para traduzir
source_languagestringnaoDetectado automaticamente se omitido
target_languagestringsimCódigo ISO 639-1 (ex. es, fr, de)
redactstring[]naoTipos de entidade para redigir (ex.: email, telefone, nome)

Resposta 200

CampoTipoDescricao
translated_textstringTexto traduzido com PII redigido
source_languagestringIdioma de origem detectado ou fornecido
target_languagestringCódigo do idioma de destino
confidencefloatPontuação de qualidade 0.0 - 1.0
redactionsarrayLista de redações aplicadas (tipo e substituição)

Exemplos

curl
curl -X POST https://api.morlivo.ai/api/v1/translate \
  -H "Authorization: Bearer mrl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contact John Smith at john@example.com or 555-123-4567",
    "source_language": "en",
    "target_language": "fr",
    "redact": ["email", "phone", "name"]
  }'
Python
import httpx

resp = httpx.post(
    "https://api.morlivo.ai/api/v1/translate",
    headers={"Authorization": "Bearer mrl_your_key"},
    json={
        "text": "Contact John Smith at john@example.com or 555-123-4567",
        "source_language": "en",
        "target_language": "fr",
        "redact": ["email", "phone", "name"],
    },
)
data = resp.json()
print(data["translated_text"])
# → "Contactez [NAME_REDACTED] à [EMAIL_REDACTED] ou [PHONE_REDACTED]"
JavaScript
const resp = await fetch(
  "https://api.morlivo.ai/api/v1/translate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer mrl_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Contact John Smith at john@example.com or 555-123-4567",
      source_language: "en",
      target_language: "fr",
      redact: ["email", "phone", "name"],
    }),
  }
);
const data = await resp.json();
console.log(data.translated_text);
// → "Contactez [NAME_REDACTED] à [EMAIL_REDACTED] ou [PHONE_REDACTED]"
Resposta
{
  "translated_text": "Contactez [NAME_REDACTED] à [EMAIL_REDACTED] ou [PHONE_REDACTED]",
  "source_language": "en",
  "target_language": "fr",
  "confidence": 0.95,
  "redactions": [
    {"type": "name", "replacement": "[NAME_REDACTED]"},
    {"type": "email", "replacement": "[EMAIL_REDACTED]"},
    {"type": "phone", "replacement": "[PHONE_REDACTED]"}
  ]
}

Tipos de Entidade Suportados

EntidadeDescricaoDetecção
email Endereços de e-mail Baseado em padrão (incluso)
phone Números de telefone Baseado em padrão (incluso)
ssn Números de Seguro Social Baseado em padrão (incluso)
credit_card Números de cartão de crédito Baseado em padrão (incluso)
ip_address Endereços IP Baseado em padrão (incluso)
name Nomes de pessoas Com tecnologia de IA (custo adicional)
address Endereços físicos Com tecnologia de IA (custo adicional)
medical Informações médicas Com tecnologia de IA (custo adicional)

Entidades baseadas em formato (e-mail, telefone, SSN, cartão de crédito, IP) são detectadas usando correspondência de padrões sem custo adicional. Entidades contextuais (nome, endereço, médico) usam detecção com tecnologia de IA e geram uma pequena cobrança adicional por solicitação.

Pronto para integrar?

Crie uma conta gratuita para obter sua chave de API e começar a traduzir.