Documentazione API

Integra una traduzione potente nelle tue applicazioni con la nostra semplice API REST.

Per iniziare

La TranslateAPI fornisce una semplice interfaccia REST per la traduzione di testo tra 180+ lingue. Tutti gli endpoint API restituisce le risposte JSON.

URL base: https://api.translateapi.ai/api/v1/
Avvio rapido

Fai la tua prima richiesta di traduzione:

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

response = requests.post(
    "https://api.translateapi.ai/api/v1/translate/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "text": "Hello, world!",
        "target_language": "es"
    }
)

result = response.json()
print(result["translated_text"])  # "Hola, mundo!"
const response = await fetch("https://api.translateapi.ai/api/v1/translate/", {
    method: "POST",
    headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        text: "Hello, world!",
        target_language: "es"
    })
});

const result = await response.json();
console.log(result.translated_text);  // "Hola, mundo!"
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add(
            "Authorization", "Bearer YOUR_API_KEY"
        );

        var content = new StringContent(
            JsonConvert.SerializeObject(new {
                text = "Hello, world!",
                target_language = "es"
            }),
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync(
            "https://api.translateapi.ai/api/v1/translate/",
            content
        );

        var result = await response.Content.ReadAsStringAsync();
        var data = JsonConvert.DeserializeObject<dynamic>(result);
        Console.WriteLine(data.translated_text);  // "Hola, mundo!"
    }
}

Autenticazione

Autentica le tue richieste usando una chiave API. Puoi creare chiavi API dal tuo cruscotto.

Autenticazione dell'intestazione (Consigliato)
Authorization: Bearer ta_your_api_key_here
Parametro interrogazione
https://api.translateapi.ai/api/v1/translate/?api_key=ta_your_api_key_here
Tieni al sicuro le chiavi dell'API! Non esporli nel codice lato client o nei repository pubblici.

Traduci testo

Tradurre il testo in un'unica lingua di destinazione.

POST https://api.translateapi.ai/api/v1/translate/
Organo di richiesta
Parametro Tipo Richiesto Designazione delle merci
text string Sì Testo da tradurre (max 50.000 caratteri)
target_language string Sì Target language code (e.g., "es", "fr", "de")
source_language string No. Source language code. Default: "auto" (auto-detect)

* Uso target_language (stringa) per la lingua unica o target_languages (array) per multipli. Vedi Traduzione multi-target.

Risposta
{
    "translated_text": "Hola, mundo!",
    "source_language": "en",
    "target_language": "es",
    "translations": {
        "es": "Hola, mundo!"
    },
    "character_count": 13,
    "translation_time": 0.45
}

Traduzione multi-target

Tradurre il testo in più lingue in una singola richiesta. Usa lo stesso endpoint della traduzione singola.

Suggerimento: Puoi tradurre fino a 50 lingue in un'unica richiesta.
POST https://api.translateapi.ai/api/v1/translate/
Organo di richiesta
{
    "text": "Hello, world!",
    "target_languages": ["es", "fr", "de", "ja"],
    "source_language": "en"
}

Uso target_languages (array) invece di target_language Per bersagli multipli.

Risposta
{
    "source_language": "en",
    "translations": {
        "es": "Hola, mundo!",
        "fr": "Bonjour, monde!",
        "de": "Hallo, Welt!",
        "ja": "こんにちは、世界！"
    },
    "character_count": 52,
    "translation_time": 2.31
}

Traduzione in lotti

Tradurre più testi contemporaneamente con l'elaborazione dell'async. Inviare un batch e un sondaggio per i risultati.

Limiti: max 500 testi per lotto, max 750 elementi totali (testi × lingue di destinazione). Tempo di lavoro 30 minuti dopo l'inizio dell'elaborazione (il tempo di attesa non è contato).
Il tempo di elaborazione varia a seconda della lingua: le lingue comuni (spagnolo, francese, tedesco, ecc.) utilizzano modelli veloci (~0.1s per testo), mentre le lingue meno comuni utilizzano il nostro grande modello multilingue (~1-3s per testo). Un lotto di 100-text si completa tipicamente in 10-30 secondi per le lingue comuni, o 2-5 minuti per quelle meno comuni. Per i migliori risultati, inviare 1 lingua di destinazione per richiesta di lotto e mantenere le dimensioni dei lotti sotto 50 testi.
POST https://api.translateapi.ai/api/v1/translate/batch/
Fase 1: Inviare il lotto
curl -X POST https://api.translateapi.ai/api/v1/translate/batch/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Hello", "Goodbye", "Thank you"],
    "target_language": "es",
    "source_language": "en"
}'
Risposta (HTTP 202 accettata)
{
    "job_id": "67535b2b-c9e3-4f82-9499-e237edbc1dd8",
    "status": "pending",
    "total_texts": 3,
    "queue_position": 1,
    "source_language": "en",
    "target_languages": ["es"],
    "character_count": 22,
    "credits_remaining": -1,
    "poll_url": "https://api.translateapi.ai/api/v1/jobs/67535b2b-c9e3-4f82-9499-e237edbc1dd8/"
}
Fase 2: Sondaggio per i risultati
GET https://api.translateapi.ai/api/v1/jobs/{job_id}/
Esempio di campionamento (Python)
import time, requests

job_id = response.json()["job_id"]
total = response.json()["total_texts"]
headers = {"Authorization": "Bearer YOUR_API_KEY"}

print(f"Batch submitted: {total} texts (job {job_id})")

while True:
    result = requests.get(f"https://api.translateapi.ai/api/v1/jobs/{job_id}/", headers=headers).json()
    status = result["status"]
    processed = result.get("processed_texts", 0)
    progress = result.get("progress_percentage", 0)

    if status == "completed":
        print(f"Completed: {processed}/{total} texts in {result.get('processing_time', 0):.1f}s")
        translations = result["result_data"]["translations"]
        break
    elif status == "failed":
        print(f"Failed at {processed}/{total}: {result.get('error_message', 'unknown')}")
        raise Exception(result.get("error_message", "Translation failed"))
    elif status == "pending":
        queue_pos = result.get("queue_position", "?")
        print(f"Queued (position {queue_pos}) — waiting for GPU worker...")
    else:
        print(f"[{status}] {processed}/{total} ({progress:.0f}%)")

    time.sleep(3)
Risposta (in attesa di GPU)
{
    "job_id": "67535b2b-...",
    "status": "pending",
    "processed_texts": 0,
    "total_texts": 3,
    "progress_percentage": 0.0,
    "queue_position": 3
}
Risposta (durante l'elaborazione)
{
    "job_id": "67535b2b-...",
    "status": "processing",
    "processed_texts": 1,
    "total_texts": 3,
    "progress_percentage": 33.33,
    "queue_position": null
}
Risposta (completata)
{
    "job_id": "67535b2b-...",
    "status": "completed",
    "processed_texts": 3,
    "total_texts": 3,
    "progress_percentage": 100.0,
    "processing_time": 10.65,
    "result_data": {
        "translations": ["Hola", "Adiós", "Gracias"],
        "source_language": "en",
        "target_language": "es",
        "character_count": 22,
        "processing_time": 10.65
    }
}
Monitoraggio dei progressi in tempo reale

Ogni risposta dei sondaggi include campi di progresso in tempo reale in modo da poter monitorare esattamente quello che sta accadendo con il vostro batch:

Campo Designazione delle merci
status Stato attuale del lavoro: pending (chiuso, in attesa di un lavoratore della GPU), processing (traduzione attiva), completed, failed
processed_texts Numero di traduzioni singole completate finora. Aggiornamenti in tempo reale come ogni testo è tradotto.
total_texts Numero totale di traduzioni in questo lotto (testi × lingue di destinazione).
progress_percentage Percentuale di completamento (0-100). Calcolato da processati_testi / totali_testi.
queue_position La tua posizione nella coda quando lo stato è "in attesa" (1 = successivo). Annulla durante l'elaborazione o completato. Usa questo per stimare il tempo di attesa e mostrare lo stato della coda agli utenti.
processing_time Tempo totale di elaborazione in secondi (disponibile quando completato).
Suggerimento: Quando status è "pending", i lavoratori della GPU sono occupati con altri lotti. queue_position Per vedere quanti lavori sono davanti al tuo (1 = sei il prossimo). Il tuo lavoro inizierà automaticamente nessuna azione necessaria, basta tenere sondaggi.
Migliori pratiche per carichi di lavoro di grandi dimensioni
  • Invia 1 lingua di destinazione per richiesta batch. Questo mantiene ogni batch veloce e rende i progressi facili da tenere traccia.
  • Mantenete i lotti a 50-100 testi. I lotti più piccoli completano più velocemente e vi danno aggiornamenti di avanzamento più frequenti.
  • Eseguire al massimo 2 lavori batch simultanei. La GPU elabora 2 lotti in coda di lavoro aggiuntiva parallela e non inizierà più velocemente.
  • Al timeout, ri-poll lo stesso job_id invece di inviare un nuovo batch. Il lavoro originale può ancora essere l'elaborazione sulla GPU.
  • Sondaggio ogni 3-5 secondi. I sondaggi più frequenti non accelerano l'elaborazione.
Lotto di più lingue

Tradurre più testi in più lingue contemporaneamente:

{
    "texts": ["Hello", "Goodbye"],
    "target_languages": ["es", "fr"],
    "source_language": "en"
}
Dati_risultati completati
{
    "translations": [
        {"es": "Hola", "fr": "Bonjour"},
        {"es": "Adiós", "fr": "Au revoir"}
    ],
    "source_language": "en",
    "target_languages": ["es", "fr"],
    "character_count": 24,
    "processing_time": 2.45
}
Parametri di richiesta
Parametro Tipo Richiesto Designazione delle merci
texts array Sì Array di stringhe da tradurre
target_language string Sì Codice della lingua di destinazione per la lingua unica
target_languages array Sì Elenco dei codici linguistici di destinazione per più lingue
source_language string No. Source language code. Default: "auto"

* Fornire sia target_language oppure target_languages, non tutte e due.

Elaborazione asincrona: Le richieste di lotto ritornano immediatamente con una job_id. Sondaggio GET /api/v1/jobs/{job_id}/ fino a status è "completed", poi leggere result_data per traduzioni. Uso progress_percentage per rintracciare i progressi.

Traduzione del documento

Tradurre interi documenti durante la conservazione della formattazione. Supporta più formati di file.

POST https://api.translateapi.ai/api/v1/translate/document/
Richiesta (multipart/form-data)
Parametro Tipo Richiesto Designazione delle merci
file file Sì Il documento da tradurre (max 10MB)
target_language string Sì Target language code (e.g., "es", "fr", "de")
source_language string No. Source language code. Default: "auto" (auto-detect)
Tipi di file supportati
  • .txt - File di testo semplice
  • .docx - Documenti di testo
  • .pdf - Documenti PDF (tra cui scansionati)
  • .json - File JSON (traduce i valori delle stringhe)
  • .xml - File XML
  • .srt - File sottotitoli
  • .po / .pot - File di traduzione Gettext
  • .jpg / .jpeg - Immagini JPEG (OCR)
  • .png - Immagini PNG (OCR)
  • .tiff / .tif - Immagini TIFF (OCR)
  • .bmp - Immagini BMP (OCR)
  • .webp - Immagini WebP (OCR)
Supporto OCR: I file di immagini e i PDF scansionati vengono elaborati con riconoscimento ottico dei caratteri (OCR) per estrarre il testo prima della traduzione. Per ottenere i migliori risultati, utilizzare immagini chiare e ad alta risoluzione.
Esempio (cURL)
# Translate a Word document
curl -X POST https://api.translateapi.ai/api/v1/translate/document/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.docx" \
  -F "target_language=es" \
  -F "source_language=en"

# Translate text from an image (OCR)
curl -X POST https://api.translateapi.ai/api/v1/translate/document/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@scanned_page.jpg" \
  -F "target_language=es" \
  -F "source_language=en"
I file immagine vengono elaborati con OCR per estrarre il testo prima della traduzione. L'output tradotto viene restituito come un .txt File.
Risposta
{
    "id": 123,
    "original_filename": "document.docx",
    "file_type": "docx",
    "source_language": "en",
    "target_language": "es",
    "status": "completed",
    "character_count": 5420,
    "translated_file_url": "/media/translated/document_es.docx",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:05Z"
}
Valori di stato
pending File caricato, in attesa di essere elaborato
processing Traduzione in corso
completed Traduzione completa, scarica disponibile
failed Traduzione non riuscita (controlla error_message)
GET https://api.translateapi.ai/api/v1/translate/document/{id}/

Controlla lo stato di una traduzione di un documento o recupera l'URL di download.

Risposta
{
    "id": 123,
    "original_filename": "document.docx",
    "status": "completed",
    "translated_file_url": "/media/translated/document_es.docx",
    "character_count": 5420
}

Rilevamento lingua

Il rilevamento delle lingue è integrato in ogni richiesta di traduzione. source_language to "auto" (o ometterlo) e la lingua rilevata viene restituita nella risposta.

POST https://api.translateapi.ai/api/v1/translate/
Organo di richiesta
{
    "text": "Bonjour, comment allez-vous?",
    "target_language": "en"
}
Risposta
{
    "translated_text": "Hello, how are you?",
    "source_language": "fr",
    "target_language": "en",
    "translations": {
        "en": "Hello, how are you?"
    },
    "character_count": 28,
    "translation_time": 0.52
}

La source_language il campo nella risposta mostra la lingua rilevata quando viene usata la rilevazione automatica.

Lingue supportate

Ottieni la lista di tutte le lingue supportate.

GET https://api.translateapi.ai/api/v1/translate/languages/
Risposta
{
    "count": 186,
    "results": [
        {"iso": "en", "name": "English", "en_label": "English"},
        {"iso": "es", "name": "Español", "en_label": "Spanish"},
        {"iso": "fr", "name": "Français", "en_label": "French"},
        ...
    ]
}

Modelli di traduzione

Utilizziamo modelli di traduzione open source all'avanguardia in esecuzione sulla nostra infrastruttura GPU. Tutti i modelli sono in licenza commerciale (Apache 2.0).

Modello Lingue Meglio per
Helsinki-NLP/opus-mt 50+ coppie di lingue Lingue comuni (EN, ES, FR, DE, IT, PT, RU, ZH, JA, ecc.)
Google MADLAD-400 400+ lingue Lingue rare, copertura completa

L'API seleziona automaticamente il modello migliore per la coppia linguistica. È possibile specificare opzionalmente un engine parametro:

Motore Designazione delle merci
"auto" Predefinito. Prova prima HuggingFace, rientra in MADLAD-400
"huggingface" Forza HuggingFace/MarianMT (più veloce, 50+ lingue)
"madlad" Forza MADLAD-400 (400+ lingue)

Gestione degli errori

L'API utilizza codici di stato HTTP standard per indicare il successo o il fallimento.

Codice Designazione delle merci
200 Successo
400 Richiesta errata - Parametri non validi
401 Non autorizzato - Chiave API non valida o mancante
402 Pagamento richiesto - Quota giornaliera di carattere superata
429 Troppe richieste - Limite di frequenza superato
503 Servizio Non disponibile - Motore di traduzione temporaneamente inattivo
Formato di risposta dell'errore
{
    "error": "daily_limit_exceeded",
    "credits_remaining": 0,
    "daily_limit": 100000
}

Limiti di frequenza

I limiti variano a seconda del piano. determinazione dei prezzi per informazioni complete:

Piano Caratteri/Mese Prezzo
Libero 250,000 $0 Iscriviti gratis
Avviatore 2,500,000 $9/mo Sottoscrivi
Pro 10,000,000 $29/mo Sottoscrivi
Affari 40,000,000 $79/mo Sottoscrivi
Scala 125,000,000 $199/mo Sottoscrivi

Quando supererai il tuo limite, riceverai un 429 Too Many Requests risposta fino al mese successivo o si aggiorna.

Infrastruttura Cloud Auto-Scaling

TradurreAPI viene eseguito su istanze dedicate NVIDIA A100 GPU con scala orizzontale automatica. Quando la domanda aumenta, ulteriori istanze GPU vengono lanciati in pochi minuti per mantenere tempi di risposta rapidi. Ciò significa che la nostra API può gestire richieste contemporanee virtualmente illimitate senza degradazioni da una singola richiesta a migliaia al minuto.

Valuta questa pagina
Grazie per la tua valutazione!
/5 basato su rating