v1.0.0

Riferimento API

Integra traduzione e trascrizione di Morlivo nella tua applicazione con poche righe di codice.

URL base: https://api.morlivo.ai Autenticazione: Authorization: Bearer mrl_...

Autenticazione

Tutte le richieste API richiedono un token Bearer. Ottieni la tua chiave API dalla dashboard nelle Impostazioni.

Intestazione
Authorization: Bearer mrl_your_api_key_here

Le chiavi API iniziano con mrl_. Tienile segrete. Ruotale dalla dashboard se compromesse.

POST

/v1/translate

Traduci testo da una lingua a un'altra. La lingua sorgente viene rilevata automaticamente se omessa.

Corpo della richiesta JSON

CampoTipoObbligatorioDescrizione
textstringTesto da tradurre
target_languagestringCodice ISO 639-1 (es. es, fr, de)
source_languagestringnoRilevato automaticamente se omesso
project_idintegernoApplica glossario e stile del progetto
formalitystringnoRegister: formal, informal, or default

Risposta 200

CampoTipoDescrizione
translated_textstringIl testo tradotto
source_languagestringLingua di origine rilevata o fornita
target_languagestringCodice lingua di destinazione
confidencefloatPunteggio di qualità 0.0 - 1.0
validationobjectRisultati della validazione di qualità

Esempi

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!"
Risposta
{
  "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

Trascrivi un file audio o video in testo. Supporta fino a 100 MB.

Corpo della richiesta multipart/form-data

CampoTipoObbligatorioDescrizione
filefileFile audio/video (mp3, wav, mp4, webm, ecc.)
languagestringnoCodice ISO, rilevato automaticamente se omesso
project_idintegernoCollega a un progetto per il monitoraggio
response_formatstringnoOutput format: json, verbose_json, text, srt, vtt
punctuatebooleannoInclude punctuation (default true)

Risposta 200

CampoTipoDescrizione
textstringTesto trascritto completo
languagestringLingua rilevata
duration_secondsfloatDurata audio
confidencefloatPunteggio di qualità 0.0 - 1.0
language_confidencefloatConfidence of auto-detected language (null if language was specified)
segmentsarraySegmenti con marcatura temporale
validationobjectControlli di qualità

Esempi

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"])
Risposta
{
  "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

Trasmetti audio in tempo reale e ricevi risultati di trascrizione dal vivo.

Connessione

ParametroTipoObbligatorioDescrizione
tokenstringChiave API come parametro di query
languagestringnoSuggerimento lingua sorgente (es. en, fr). Rilevata automaticamente se omessa.

Protocollo

Invia

Frame audio PCM binari (16 bit, 16 kHz mono)

Ricevi

Messaggi JSON con campo type: transcript (testo parziale/finale), status (eventi di sessione), error

Messaggi ricevuti

CampoTipoDescrizione
typestring"transcript" | "status" | "error"
textstringTesto trascritto (nei messaggi di trascrizione)
is_finalbooleanVero quando il segmento è completo
languagestringCodice lingua rilevato

Esempi

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())
Esempi di messaggi
// 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

Trasmetti audio in una lingua e ricevi il testo tradotto in un'altra lingua in tempo reale. Supporta la traduzione vocale con rilevamento automatico della lingua.

Connessione

ParametroTipoObbligatorioDescrizione
tokenstringChiave API come parametro di query
target_languagestringLingua per il testo di output (es. en, es, fr)
source_languagestringnoLingua dell'audio sorgente. Rilevata automaticamente se omessa.

Protocollo

Invia

Frame audio PCM binari (16 bit, 16 kHz mono)

Ricevi

Messaggi JSON con testo tradotto nella lingua di destinazione. Include sia la trascrizione del discorso originale che l'output tradotto.

Messaggi ricevuti

CampoTipoDescrizione
typestring"transcript" | "status" | "error"
textstringTesto tradotto nella lingua di destinazione
is_finalbooleanVero quando il segmento è completo
source_languagestringLingua di origine rilevata
target_languagestringCodice lingua di destinazione

Esempi

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())
Esempi di messaggi
// 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 della richiesta JSON

CampoTipoObbligatorioDescrizione
languagesobjectParticipant ID to language mapping
bridge_languagestringnoHub language, default en
max_participantsintnoMax participants 2-10, default 10
modestringnointerpreter or inline

Risposta 200

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

Esempi

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"
  }'
Risposta
{
  "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.

Connessione

ParametroTipoObbligatorioDescrizione
room_idstringRoom ID from create room response (path param)
participantstringParticipant ID (query param)
tokenstringChiave API come parametro di query

Esempio

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 della richiesta JSON

CampoTipoObbligatorioDescrizione
participant_idstringUnique participant identifier
languagestringParticipant's language code

Esempio

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.

Risposta 200

CampoTipoDescrizione
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

Esempio

curl
curl https://api.morlivo.ai/api/v1/languages \
  -H "Authorization: Bearer mrl_your_key"
Risposta
{
  "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.

Risposta 200

CampoTipoDescrizione
statusstringintegro o degradato

Esempio

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

Endpoint di compatibilità

Utilizzi già un altro provider? Cambia un URL e mantieni il tuo codice esistente. Questi endpoint rispecchiano i formati di richiesta e risposta delle principali API di traduzione e trascrizione.

DL

DeepL

Traduzione
POST /api/compat/deepl/v2/translate

Sostituzione diretta per api-free.deepl.com

G

Google Cloud Translation

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

Sostituzione diretta per translation.googleapis.com

A

AWS Translate

Traduzione
POST /api/compat/aws/translate

Sostituzione diretta per translate.amazonaws.com

OA

OpenAI Whisper

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

Sostituzione diretta per api.openai.com

DG

Deepgram

Trascrizione
POST /api/compat/deepgram/v1/listen

Sostituzione diretta per api.deepgram.com

Gli endpoint di compatibilità accettano lo stesso formato di richiesta e restituiscono la stessa struttura di risposta del provider originale. Consulta la documentazione di ciascun provider per i relativi schemi di richiesta/risposta.

Errori

Tutti gli errori restituiscono un oggetto JSON con un campo detail.

CodiceSignificatoQuando accade
400 Richiesta non valida Campi obbligatori mancanti, testo vuoto, tipo di file non supportato
401 Non autorizzato Chiave API mancante o non valida
403 Vietato Chiave API valida ma permessi insufficienti o quota superata
413 Payload troppo grande Il file supera il limite di caricamento di 100 MB
429 Limite di frequenza raggiunto Troppe richieste. Riprova con backoff esponenziale.
500 Errore interno Errore del server imprevisto. Contatta il supporto se persiste.
503 Servizio non disponibile Modello IA temporaneamente non disponibile (circuit breaker aperto). Riprova tra poco.
Formato di risposta errore
{
  "detail": "Field 'text' must not be empty."
}
POST

Rimozione PII

Aggiungi la rimozione dei PII a qualsiasi richiesta di traduzione o trascrizione. Specifica quali tipi di entità rilevare e rimuovere.

POST /v1/translate POST /v1/transcribe

Corpo della richiesta JSON

CampoTipoObbligatorioDescrizione
textstringTesto da tradurre
source_languagestringnoRilevato automaticamente se omesso
target_languagestringCodice ISO 639-1 (es. es, fr, de)
redactstring[]noTipi di entità da rimuovere (es. email, telefono, nome)

Risposta 200

CampoTipoDescrizione
translated_textstringTesto tradotto con PII rimossi
source_languagestringLingua di origine rilevata o fornita
target_languagestringCodice lingua di destinazione
confidencefloatPunteggio di qualità 0.0 - 1.0
redactionsarrayElenco delle rimozioni applicate (tipo e sostituzione)

Esempi

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]"
Risposta
{
  "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]"}
  ]
}

Tipi di entità supportati

EntitàDescrizioneRilevamento
email Indirizzi email Basato su pattern (incluso)
phone Numeri di telefono Basato su pattern (incluso)
ssn Numeri di previdenza sociale Basato su pattern (incluso)
credit_card Numeri di carta di credito Basato su pattern (incluso)
ip_address Indirizzi IP Basato su pattern (incluso)
name Nomi di persona Basato sull'AI (costo aggiuntivo)
address Indirizzi fisici Basato sull'AI (costo aggiuntivo)
medical Informazioni mediche Basato sull'AI (costo aggiuntivo)

Le entità basate su formato (email, telefono, SSN, carta di credito, IP) vengono rilevate tramite corrispondenza di pattern senza costi aggiuntivi. Le entità contestuali (nome, indirizzo, informazioni mediche) utilizzano il rilevamento basato sull'AI e comportano un piccolo costo aggiuntivo per richiesta.

Pronto per l'integrazione?

Crea un account gratuito per ottenere la tua chiave API e iniziare a tradurre.