Riferimento API
Integra la traduzione e la trascrizione di Morlivo nella tua applicazione con poche righe di codice.
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.
Authorization: Bearer mrl_your_api_key_here
Le chiavi API iniziano con mrl_. Tienili segreti. Ruotali dalla dashboard se compromessi.
/v1/translate
Traduci il testo da una lingua all'altra. La lingua sorgente viene rilevata automaticamente se omessa.
Corpo della richiesta JSON
| Campo | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
text | string | sì | Testo da tradurre |
target_language | string | sì | Codice ISO 639-1 (es. es, fr, de) |
source_language | string | no | Rilevato automaticamente se omesso |
project_id | integer | no | Applica glossario e stile del progetto |
formality | string | no | Registro: formale, informale o predefinito |
Risposta 200
| Campo | Digita | Descrizione |
|---|---|---|
translated_text | string | Il testo tradotto |
source_language | string | Lingua di origine rilevata o fornita |
target_language | string | Codice lingua di destinazione |
confidence | float | Punteggio qualità 0.0 - 1.0 |
validation | object | Risultati della validazione della qualità |
Esempi
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"
}'
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!"
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!"
{
"translated_text": "¡Hola, mundo!",
"source_language": "en",
"target_language": "es",
"confidence": 0.98,
"validation": {
"length_ratio": 1.08,
"language_match": true,
"passed": true
}
}
/v1/transcribe
Trascrivi un file audio o video in testo. Supporta fino a 100 MB.
Corpo della richiesta multipart/form-data
| Campo | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
file | file | sì | File audio/video (mp3, wav, mp4, webm, ecc.) |
language | string | no | Codice ISO, rilevato automaticamente se omesso |
project_id | integer | no | Collega a un progetto per il tracciamento |
response_format | string | no | Formato di output: json, verbose_json, text, srt, vtt |
punctuate | boolean | no | Includi la punteggiatura (predefinito: true) |
Risposta 200
| Campo | Digita | Descrizione |
|---|---|---|
text | string | Testo trascritto completo |
language | string | Lingua rilevata |
duration_seconds | float | Durata audio |
confidence | float | Punteggio qualità 0.0 - 1.0 |
language_confidence | float | Confidenza della lingua rilevata automaticamente (null se la lingua è stata specificata) |
segments | array | Segmenti con timestamp |
validation | object | Controlli di qualità |
Esempi
curl -X POST https://api.morlivo.ai/api/v1/transcribe \
-H "Authorization: Bearer mrl_your_key" \
-F "file=@meeting.mp3" \
-F "language=en"
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"])
{
"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
}
}
/v1/live/transcribe
Trasmetti audio in tempo reale e ricevi risultati di trascrizione in diretta.
Connessione
| Parametro | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
token | string | sì | Chiave API come parametro di query |
language | string | no | Indicazione della lingua sorgente (es. en, fr). Rilevata automaticamente se omessa. |
Protocollo
Frame audio PCM binari (16-bit, 16kHz mono)
Messaggi JSON con campo type: transcript (testo parziale/finale), status (eventi di sessione), error
Messaggi ricevuti
| Campo | Digita | Descrizione |
|---|---|---|
type | string | "transcript" | "status" | "error" |
text | string | Testo trascritto (nei messaggi della trascrizione) |
is_final | boolean | Vero quando il segmento è completo |
language | string | Codice lingua rilevato |
Esempi
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);
}
};
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())
// 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}
/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
| Parametro | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
token | string | sì | Chiave API come parametro di query |
target_language | string | sì | Lingua per il testo in uscita (es. en, es, fr) |
source_language | string | no | Lingua audio sorgente. Rilevata automaticamente se omessa. |
Protocollo
Frame audio PCM binari (16-bit, 16kHz mono)
Messaggi JSON con testo tradotto in target_language. Include sia la trascrizione del discorso originale sia l'output tradotto.
Messaggi ricevuti
| Campo | Digita | Descrizione |
|---|---|---|
type | string | "transcript" | "status" | "error" |
text | string | Testo tradotto nella lingua di destinazione |
is_final | boolean | Vero quando il segmento è completo |
source_language | string | Lingua di origine rilevata |
target_language | string | Codice lingua di destinazione |
Esempi
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);
}
};
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())
// 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}
/v1/languages
Elenca tutte le lingue supportate con locale, nome e stato di disponibilità.
Risposta 200
| Campo | Digita | Descrizione |
|---|---|---|
languages | array | Elenco delle lingue supportate |
languages[].locale | string | Codice locale es. fr-CA |
languages[].name | string | Nome in inglese |
languages[].native_name | string | Nome nativo |
languages[].country | string | Paese/regione |
languages[].status | string | ga o beta |
Esempio
curl https://api.morlivo.ai/api/v1/languages \
-H "Authorization: Bearer mrl_your_key"
{
"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"}
]
}
/v1/health
Controlla lo stato delle API e la salute del database. Non è richiesta autenticazione.
Risposta 200
| Campo | Digita | Descrizione |
|---|---|---|
status | string | operativo o degradato |
Esempio
curl https://api.morlivo.ai/api/v1/health
{
"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.
DeepL
TraduzionePOST /api/compat/deepl/v2/translate
Sostituto drop-in per api-free.deepl.com
Google Cloud Translation
TraduzionePOST /api/compat/google/v3/projects/{p}/locations/{l}:translateText
Sostituto drop-in per translation.googleapis.com
AWS Translate
TraduzionePOST /api/compat/aws/translate
Sostituto drop-in per translate.amazonaws.com
OpenAI Whisper
TrascrizionePOST /api/compat/openai/v1/audio/transcriptions
Sostituto drop-in per api.openai.com
Deepgram
TrascrizionePOST /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.
| Codice | Significato | Quando 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. |
{
"detail": "Field 'text' must not be empty."
}
{
"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.
Rimozione PII
Aggiungi l'oscuramento PII a qualsiasi richiesta di traduzione o trascrizione. Specifica quali tipi di entità rilevare e oscurare.
Corpo della richiesta JSON
| Campo | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
text | string | sì | Testo da tradurre |
source_language | string | no | Rilevato automaticamente se omesso |
target_language | string | sì | Codice ISO 639-1 (es. es, fr, de) |
redact | string[] | no | Tipi di entità da oscurare (es. email, telefono, nome) |
Risposta 200
| Campo | Digita | Descrizione |
|---|---|---|
translated_text | string | Testo tradotto con PII oscurati |
source_language | string | Lingua di origine rilevata o fornita |
target_language | string | Codice lingua di destinazione |
confidence | float | Punteggio qualità 0.0 - 1.0 |
redactions | array | Elenco delle oscurazioni applicate (tipo e sostituzione) |
Esempi
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"]
}'
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]"
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]"
{
"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à | Descrizione | Rilevamento |
|---|---|---|
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.