API dokumentazioa

Integratu itzulpen indartsua zure aplikazioetan gure REST API sinplearekin.

Hasiera

TranslateAPIk REST interfaze sinple bat eskaintzen du testua 180 hizkuntza baino gehiagoren artean itzultzeko. API amaierako puntu guztiek JSON erantzunak itzultzen dituzte.

Oinarrizko URLa: https://api.translateapi.ai/api/v1/
Hasiera bizkorra

Egin zure lehen itzulpen-eskaera:

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!"
    }
}

Autentifikazioa

Autentifikatu zure eskaerak API gako bat erabiliz. API gakoak sortu ditzakezu zure kontrol-panela.

Goiburuaren autentifikazioa (gomendatua)
Authorization: Bearer ta_your_api_key_here
Kontsultaren parametroa
https://api.translateapi.ai/api/v1/translate/?api_key=ta_your_api_key_here
Mantendu zure API gakoak seguru! Ez erakutsi bezeroaren aldeko kodean edo biltegi publikoetan.

Testua itzuli

Itzuli testua helburuko hizkuntza bakar batera.

POST https://api.translateapi.ai/api/v1/translate/
Eskaeraren gorputza
Parametroak Mota Beharrezkoa Azalpena
text string Bai Itzultzeko testua (gehienez 50.000 karaktere)
target_language string Bai* Target language code (e.g., "es", "fr", "de")
source_language string Ez Source language code. Default: "auto" (auto-detect)

* Erabili target_language (katea) hizkuntza bakarreko edo target_languages (array) multiploarentzat. Ikusi Helburu anitzeko itzulpena.

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

Helburu anitzeko itzulpena

Itzul ezazu testua hainbat hizkuntzatara eskaera bakarrean. Itzulpen bakarreko amaierako puntu bera erabiltzen du.

Mota: 50 hizkuntza baino gehiagotara itzul dezakezu eskaera bakar batean.
POST https://api.translateapi.ai/api/v1/translate/
Eskaeraren gorputza
{
    "text": "Hello, world!",
    "target_languages": ["es", "fr", "de", "ja"],
    "source_language": "en"
}

Erabili target_languages (matrizea) honen ordez target_language (katea) helburu anitzetarako.

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

Batch itzulpena

Itzul itzazu testu anitz aldi berean prozesamendu asinkronoarekin. Bidali batch bat eta galdetu emaitzak.

Mugak: gehienez 500 testu batch bakoitzeko, gehienez 750 elementu guztira (testuak × helburuko hizkuntzak). Lanaren denbora- muga 30 minutukoa da prozesamendua hasi ondoren (ilara- denbora ez da zenbatzen).
Prozesamendu-denbora hizkuntzaren arabera aldatzen da: hizkuntza arruntek (gaztelania, frantsesa, alemana, etab.) modelo azkarrak erabiltzen dituzte (~0,1s testu bakoitzeko), eta hizkuntza arrunt gutxiagoek gure hizkuntza anitzeko modelo handia erabiltzen dute (~1-3s testu bakoitzeko). 100 testuko lote bat 10-30 segundotan osatzen da hizkuntza arrunten kasuan, edo 2-5 minututan gutxiago ohikoenetan. Emaitza onenak lortzeko, bidali helburuko hizkuntza bat lote-eskaera bakoitzeko eta mantendu lote-tamainak 50 testu baino txikiagoak.
POST https://api.translateapi.ai/api/v1/translate/batch/
1. urrats: Bidali batch- a
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"
}'
Erantzuna (HTTP 202 onartua)
{
    "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/"
}
2. urrats: emaitzen inkesta
GET https://api.translateapi.ai/api/v1/jobs/{job_id}/
Polling adibidea (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)
Erantzuna (zain — ilaran, GPUaren zain)
{
    "job_id": "67535b2b-...",
    "status": "pending",
    "processed_texts": 0,
    "total_texts": 3,
    "progress_percentage": 0.0,
    "queue_position": 3
}
Erantzuna (prozesatzen ari den bitartean)
{
    "job_id": "67535b2b-...",
    "status": "processing",
    "processed_texts": 1,
    "total_texts": 3,
    "progress_percentage": 33.33,
    "queue_position": null
}
Erantzuna (osatua)
{
    "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
    }
}
Denbora errealeko aurrerapenaren jarraipena

Inkesta-erantzun bakoitzak denbora errealeko aurrerapen-eremuak ditu, zure lotearekin zer gertatzen ari den zehatz-mehatz monitorizatu ahal izateko:

Eremua Azalpena
status Uneko lanaren egoera: pending (ilaran, GPU langile baten zain), processing (aktiboki itzultzen), completed, failed
processed_texts Orain arte osatutako itzulpen indibidualen kopurua. Testu bakoitza itzultzen den heinean denbora errealean eguneratzen da.
total_texts Batch honen itzulpen kopurua guztira (testuak × helburuko hizkuntzak).
progress_percentage Osatzeko ehunekoa (0-100). Prozesatutako_testuak / testu_guztiak erabiliz kalkulatzen da.
queue_position Zure posizioa ilaran egoera "zain" denean (1 = hurrengoa). Nula prozesatuta edo osatua denean. Erabili hau itxarote-denbora estimatzeko eta ilararen egoera erabiltzaileei erakusteko.
processing_time Prozesatzeko guztizko denbora segundotan (erabilgarri amaitzean).
Mota: Noiz status da "pending", GPUko langileak beste batch batzuetan lanpetuta daude. Egiaztatu queue_position zeure aurretik zenbat lan dauden ikusteko (1 = hurrengoa zara). Zure lana automatikoki hasiko da — ez da ekintzarik behar, galdeketa egiten jarraitu besterik ez duzu.
Lan-karga handietarako jardunbide onenak
  • Bidali helburuko hizkuntza bat batch eskaera bakoitzeko. Honek batch bakoitza azkar mantentzen du eta aurrerapena erraz jarraitzen da.
  • Mantendu loteak 50-100 testutan. Lote txikiagoak azkarrago osatzen dira eta aurrerapen-eguneratzeak maizago ematen dizkizute.
  • Exekutatu gehienez 2 batch lan aldi berean. GPUak 2 batch prozesatzen ditu paraleloki — lan gehigarriak ilaran jarriko dira eta ez dira azkarrago abiatuko.
  • Denbora-muga igarotzean, galdetu berriro job_id bera batch berri bat bidali ordez. Baliteke jatorrizko lana oraindik GPUan prozesatzen egotea.
  • Galdetu 3-5 segundoro. Galdeketa gehiago egiteak ez du prozesamendua bizkortzen.
Hizkuntza anitzeko batch

Itzuli testu anitz hizkuntza anitzetara aldi berean:

{
    "texts": ["Hello", "Goodbye"],
    "target_languages": ["es", "fr"],
    "source_language": "en"
}
Osaturiko emaitza_datuak
{
    "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
}
Eskaera parametroak
Parametroak Mota Beharrezkoa Azalpena
texts array Bai Itzultzeko kateen matrizea
target_language string Bai* Helburuko hizkuntzaren kodea hizkuntza bakar baterako
target_languages array Bai* Helburuko hizkuntzaren kodeen matrizea hizkuntza anitzentzat
source_language string Ez Source language code. Default: "auto"

* Eman edota target_language edo target_languages, ez biak.

Prozesamendu asinkronoa: Batch eskaerak berehala itzultzen dira job_id. Zuloa GET /api/v1/jobs/{job_id}/ harik eta status da "completed", gero irakurri result_data itzulpenetarako. Erabili progress_percentage aurrerapenaren jarraipena egiteko.

Dokumentuaren itzulpena

Itzul itzazu dokumentu osoak formateatzea mantenduz. Fitxategi-formatu anitzak onartzen ditu.

POST https://api.translateapi.ai/api/v1/translate/document/
Eskaera (zati-anitza/inprimaki-datuak)
Parametroak Mota Beharrezkoa Azalpena
file file Bai Itzultzeko dokumentua (gehienez 10MB)
target_language string Bai Target language code (e.g., "es", "fr", "de")
source_language string Ez Source language code. Default: "auto" (auto-detect)
Onartutako fitxategi motak
  • .txt - Testu arrunteko fitxategiak
  • .docx - Word dokumentuak
  • .pdf - PDF dokumentuak (eskaneatuak barne)
  • .json - JSON fitxategiak (kate-balioak itzultzen ditu)
  • .xml - XML fitxategiak
  • .srt - Azpitituluen fitxategiak
  • .po / .pot - Gettext itzulpen-fitxategiak
  • .jpg / .jpeg - JPEG irudiak (OCR)
  • .png - PNG irudiak (OCR)
  • .tiff / .tif - TIFF irudiak (OCR)
  • .bmp - BMP irudiak (OCR)
  • .webp - WebP irudiak (OCR)
OCR euskarria: Irudi-fitxategiak eta eskaneatutako PDFak karaktere-ezagutze optikoarekin (OCR) prozesatzen dira testua itzuli aurretik ateratzeko. Emaitza onenak lortzeko, erabili irudi garbiak eta bereizmen handikoak.
Adibidea (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"
Irudi-fitxategiak OCR-rekin prozesatzen dira itzuli aurretik testua ateratzeko. Itzultutako irteera fitxategi gisa itzultzen da. .txt fitxategia.
Erantzuna
{
    "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"
}
Egoeraren balioak
pending Fitxategia igo da, prozesatzeko zain
processing Itzulpena aurrera doa
completed Itzulpena osatua, deskargagarri
failed Itzulpenak huts egin du (check error_message)
GET https://api.translateapi.ai/api/v1/translate/document/{id}/

Egiaztatu dokumentu baten itzulpenaren egoera edo eskuratu deskargaren URLa.

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

Hizkuntzaren detekzioa

Hizkuntza-detekzioa itzulpen-eskaera guztietan txertatuta dago. Ezarri source_language to "auto" (edo ez idatzi) eta hautemandako hizkuntza itzuliko da erantzunean.

POST https://api.translateapi.ai/api/v1/translate/
Eskaeraren gorputza
{
    "text": "Bonjour, comment allez-vous?",
    "target_language": "en"
}
Erantzuna
{
    "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
}

The source_language Erantzuneko eremu honek detektatutako hizkuntza erakusten du autodetekzioa erabiltzen denean.

Onartutako hizkuntzak

Eskuratu onartutako hizkuntza guztien zerrenda.

GET https://api.translateapi.ai/api/v1/translate/languages/
Erantzuna
{
    "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"},
        ...
    ]
}

Itzulpen-ereduak

Kode irekiko itzulpen-eredu modernoak erabiltzen ditugu, gure GPU azpiegitura propioan exekutatzen direnak. Eredu guztiek lizentzia komertziala dute (Apache 2.0).

Modeloa Hizkuntzak Honako hauentzako onena
Helsinki-NLP/opus-mt 50+ hizkuntza bikote Hizkuntza arruntak (EN, ES, FR, DE, IT, PT, RU, ZH, JA, etab.)
Google MADLAD-400 400 hizkuntza baino gehiago Hizkuntza arraroak, estaldura osoa

APIak automatikoki hautatzen du zure hizkuntza-bikotearentzako modelorik onena. Aukerazkoa da eredu bat zehaztea engine parametroa:

Motorra Azalpena
"auto" Lehenetsia. HuggingFace saiatzen da lehenik, MADLAD-400-ra itzultzen da
"huggingface" Behartu HuggingFace/MarianMT (azkarrena, 50 hizkuntza baino gehiago)
"madlad" Force MADLAD-400 (400 hizkuntza baino gehiago)

Errore-kudeaketa

APIak HTTP egoera kode estandarrak erabiltzen ditu arrakasta edo huts egitea adierazteko.

Kodea Azalpena
200 Arrakasta
400 Eskaera okerra - Parametro baliogabeak
401 Baimenik gabea - API gako baliogabea edo falta da
402 Ordainketa behar da - eguneko karaktere-kuota gainditu da
429 Eskaera gehiegi - Muga gainditu da
503 Zerbitzua ez dago erabilgarri - Itzulpen motorra aldi baterako geldituta
Errore-erantzunaren formatua
{
    "error": "daily_limit_exceeded",
    "credits_remaining": 0,
    "daily_limit": 100000
}

Emari-mugak

Mugak planaren arabera aldatzen dira. Ikusi prezioa xehetasun gehiagorako:

Plana Karaktereak/hilabetea Prezioa
Libre 250,000 $0 Izena eman doan
Abiarazlea 2,500,000 $9/% 1 MB Harpidetu
Pro 10,000,000 $29/% 1 MB Harpidetu
Negozioak 40,000,000 $79/% 1 MB Harpidetu
Eskalatu 125,000,000 $199/% 1 MB Harpidetu

Zure muga gainditzen duzunean, mezu bat jasoko duzu. 429 Too Many Requests erantzunik ez da emango hurrengo hilabetera arte edo bertsio-berritzea egin arte.

Auto-eskalatzeko hodei azpiegitura

TranslateAPI NVIDIA A100 GPU instantzia dedikatuetan exekutatzen da eskalatze horizontal automatikoarekin. Eskaera handitzen denean, GPU instantzia gehigarriak minutu batzuetan abiarazten dira erantzun-denbora azkarrak mantentzeko. Horrek esan nahi du gure APIak eskaera aldi berean ia mugagabeak kudea ditzakeela degradaziorik gabe — eskaera bakar batetik minutuko milaka eskaeraraino.

Balioetsi orrialde hau
Eskerrik asko zure balorazioagatik!
/5 oinarrituta balorazioak