Prossimamente Ricevi notifiche
v1.0.0

Riferimento API

Integra la traduzione e la 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 in Impostazioni.

Intestazione
Authorization: Bearer mrl_your_api_key_here

Le chiavi API iniziano con mrl_. Tienili segreti. Ruotali dalla dashboard se compromessi.

POST

/v1/translate

Traduci il testo da una lingua all'altra. La lingua sorgente viene rilevata automaticamente se omessa.

Corpo della richiesta JSON

CampoDigitaObbligatorioDescrizione
textstringTesto da tradurre
target_languagestringCodice ISO 639-1 (es. es, fr, de)
source_languagestringnoRilevato automaticamente se omesso
project_idintegernoApplica glossario e stile del progetto
formalitystringnoRegistro: formale, informale o predefinito

Risposta 200

CampoDigitaDescrizione
translated_textstringIl testo tradotto
source_languagestringLingua di origine rilevata o fornita
target_languagestringCodice lingua di destinazione
confidencefloatPunteggio qualità 0.0 - 1.0
validationobjectRisultati della validazione della 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

CampoDigitaObbligatorioDescrizione
filefileFile audio/video (mp3, wav, mp4, webm, ecc.)
languagestringnoCodice ISO, rilevato automaticamente se omesso
project_idintegernoCollega a un progetto per il tracciamento
response_formatstringnoFormato di output: json, verbose_json, text, srt, vtt
punctuatebooleannoIncludi la punteggiatura (predefinito: true)

Risposta 200

CampoDigitaDescrizione
textstringTesto trascritto completo
languagestringLingua rilevata
duration_secondsfloatDurata audio
confidencefloatPunteggio qualità 0.0 - 1.0
language_confidencefloatConfidenza della lingua rilevata automaticamente (null se la lingua è stata specificata)
segmentsarraySegmenti con timestamp
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 in diretta.

Connessione

ParametroDigitaObbligatorioDescrizione
tokenstringChiave API come parametro di query
languagestringnoIndicazione della lingua sorgente (es. en, fr). Rilevata automaticamente se omessa.

Protocollo

Invia

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

Ricevi

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

Messaggi ricevuti

CampoDigitaDescrizione
typestring"transcript" | "status" | "error"
textstringTesto trascritto (nei messaggi della 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 testo tradotto in un'altra lingua in tempo reale. Supporta la traduzione da parlato a testo con rilevamento automatico della lingua.

Connessione

ParametroDigitaObbligatorioDescrizione
tokenstringChiave API come parametro di query
target_languagestringLingua per il testo in uscita (es. en, es, fr)
source_languagestringnoLingua audio sorgente. Rilevata automaticamente se omessa.

Protocollo

Invia

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

Ricevi

Messaggi JSON con testo tradotto in target_language. Include sia la trascrizione del discorso originale sia l'output tradotto.

Messaggi ricevuti

CampoDigitaDescrizione
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

/api/v1/live/shared-device/token

Crea un token a vita breve per dispositivo condiviso, quindi apri l'URL WebSocket restituito. Non è necessario alcun pre-provisioning della stanza né routing persistente.

Corpo della richiesta JSON

CampoDigitaObbligatorioDescrizione
languagesobjectMappatura ID partecipante a lingua
max_participantsintnoPartecipanti massimi 2-10, predefinito 10
modestringnointerprete o in linea

Risposta 200

CampoDigitaDescrizione
tokenstringToken WebSocket firmato di breve durata
ws_urlstringURL WebSocket per dispositivo condiviso senza stanza
session_idstringIdentificatore di sessione effimero
participant_idstringID partecipante generato

Esempi

curl
curl -X POST https://api.morlivo.ai/api/v1/live/shared-device/token \
  -H "Authorization: Bearer mrl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "language_a": "en",
    "language_b": "es"
  }'
Risposta
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "ws_url": "wss://live.morlivo.ai/v1/live/shared-device/speech?token=...",
  "session_id": "shared_abc123",
  "participant_id": "shared-a1b2c3d4",
  "language_a": "en",
  "language_b": "es"
}
WebSocket

/v1/live/shared-device/speech

Connettiti con il token firmato, invia frame PCM mono a 16 kHz e ricevi audio tradotto oltre a eventi di trascrizione del parlante/interprete.

Connessione

ParametroDigitaObbligatorioDescrizione
tokenstringToken firmato restituito da /api/v1/live/shared-device/token

Esempio

JavaScript
const ws = new WebSocket(tokenResponse.ws_url);

ws.onmessage = (event) => {
  if (event.data instanceof Blob) {
    return playTranslatedAudio(event.data);
  }
  const msg = JSON.parse(event.data);
  if (msg.type === "transcript_input") renderSpeakerTranscript(msg);
  if (msg.type === "transcript_output") renderInterpreterTranscript(msg);
  if (msg.type === "interpreter_speaking") setInterpreterSpeaking(msg.active);
};
GET

/v1/languages

Elenca tutte le lingue supportate con locale, nome e stato di disponibilità.

Risposta 200

CampoDigitaDescrizione
languagesarrayElenco delle lingue supportate
languages[].localestringCodice locale es. fr-CA
languages[].namestringNome in inglese
languages[].native_namestringNome nativo
languages[].countrystringPaese/regione
languages[].statusstringga o 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

Controlla lo stato delle API e la salute del database. Non è richiesta autenticazione.

Risposta 200

CampoDigitaDescrizione
statusstringoperativo o degradato

Esempio

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

Endpoint di compatibilità

Usi già un altro fornitore? 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

Sostituto drop-in per api-free.deepl.com

G

Google Cloud Translation

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

Sostituto drop-in per translation.googleapis.com

A

AWS Translate

Traduzione
POST /api/compat/aws/translate

Sostituto drop-in per translate.amazonaws.com

OA

OpenAI Whisper

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

Sostituto drop-in per api.openai.com

DG

Deepgram

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

Sostituto drop-in per api.deepgram.com

Gli endpoint di compatibilità accettano lo stesso formato di richiesta e restituiscono la stessa struttura di risposta del provider originale. Fare riferimento alla documentazione di ciascun provider per gli 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 Proibito Chiave API valida ma manca l'ambito richiesto o il permesso del tenant
402 Pagamento richiesto Crediti insufficienti o verifica della carta richiesta. La risposta include billing_url e gli header X-Credits-* quando disponibili.
413 Payload troppo grande Il file supera il limite di caricamento di 100 MB
429 Limitato Troppe richieste. Riprova con backoff esponenziale.
500 Errore interno Errore imprevisto del server. Contatta il supporto se persiste.
503 Servizio non disponibile Modello IA temporaneamente non disponibile (circuit breaker aperto). Riprova a breve.
Formato della risposta di errore
{
  "detail": "Field 'text' must not be empty."
}
402Esaurimento crediti
{
  "error": "insufficient_credits",
  "detail": "Insufficient credits",
  "billing_url": "/app/billing"
}

Le risposte API riuscite includono gli header X-Credits-Spent e X-Credits-Remaining. Quando i crediti sono esauriti, i client devono smettere di riprovare e indirizzare l'utente a billing_url.

POST

Rimozione PII

Aggiungi l'oscuramento PII a qualsiasi richiesta di traduzione o trascrizione. Specifica quali tipi di entità rilevare e oscurare.

POST /v1/translate POST /v1/transcribe

Corpo della richiesta JSON

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

Risposta 200

CampoDigitaDescrizione
translated_textstringTesto tradotto con PII oscurati
source_languagestringLingua di origine rilevata o fornita
target_languagestringCodice lingua di destinazione
confidencefloatPunteggio qualità 0.0 - 1.0
redactionsarrayElenco delle oscurazioni 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 persone Potenziato dall'AI (costo aggiuntivo)
address Indirizzi fisici Potenziato dall'AI (costo aggiuntivo)
medical Informazioni mediche Potenziato dall'AI (costo aggiuntivo)

Le entità basate sul formato (email, telefono, SSN, carta di credito, IP) sono rilevate tramite pattern matching senza costi aggiuntivi. Le entità contestuali (nome, indirizzo, dati medici) utilizzano rilevamento basato su AI e comportano un piccolo costo aggiuntivo per richiesta.

Pronto per integrare?

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