Riferimento API Equalang e guida introduttiva

Quando integri Equalang nel tuo back-end gestionale o nei tuoi flussi di lavoro, puoi tradurre testi all'istante oppure elaborare interi file — documenti, audio e video — mantenendo, dove supportato, il layout originale.

Questa guida offre una procedura introduttiva per il flusso di traduzione dei file con cURL e Python, seguita dal riferimento completo di tutti i 10 endpoint pubblici dell'API.

Autenticazione e risposta standard

L'API Equalang è servita all'indirizzo https://equalang.com/v1. Autentica ogni richiesta fornendo la tua chiave API nell'intestazione HTTP Authorization:

Authorization: Bearer el_your_api_key_here

La tua chiave API deve disporre degli scope corretti (ad esempio translations:document per i job, translations:text per il testo, files:read per il download diretto dei file).

Struttura standard della risposta: tutte le risposte JSON riuscite usano una struttura di primo livello standard. Per brevità, gli esempi strutturali qui sotto omettono alcuni campi non essenziali ma restano oggetti JSON pienamente validi. Gli ID, gli URL e i numeri di saldo mostrati sono puramente illustrativi: usa i valori reali restituiti dalle tue risposte.

{
  "code": "OK",
  "message": "ok",
  "data": {},
  "request_id": "req_example_id"
}

Guida introduttiva: traduzione asincrona dei file

Elaborare un intero documento richiede un flusso asincrono: carica il file per avviare un job, interrogane lo stato e scarica il risultato. Puoi usare un tuo file oppure scaricare il nostro file di esempio supply-confirmation.zh-CN.docx per fare delle prove.

Metodo 1: con cURL

Per prima cosa esporta la tua chiave API (puoi crearne una su https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Carica il file e avvia il job

Invia il file direttamente. L'API riserva i crediti necessari e restituisce un job_id. Includi un Idempotency-Key univoco (ad esempio un UUID) per evitare job duplicati in caso di timeout. Riutilizza questa chiave se devi ritentare lo stesso invio e generane una nuova per nuove attività. (Assicurati di avere un file locale chiamato report.docx prima di eseguire il comando, oppure modifica il nome nel codice).

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Idempotency-Key: a-unique-uuid-here" \
  -F "file=@report.docx" \
  -F "target_language=en"

Estrai il job_id dall'oggetto data della risposta per usarlo nel passaggio successivo. Non copiare ID storici dagli esempi.

2. Interroga lo stato del job

Usa il tuo job_id per seguire l'avanzamento. Tra una richiesta e l'altra attendi la durata consigliata dall'intestazione Retry-After. Smetti di interrogare quando finished è true.

curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

3. Scarica il risultato

Quando lo stato è SUCCEEDED, la risposta include un download_url temporaneo. Questo URL usa un'autorizzazione con firma temporanea, quindi non devi (e non dovresti) inviare il tuo token Bearer dell'API quando scarichi da esso. Usa un flag come -f per uscire silenziosamente sugli errori HTTP, così non salvi una pagina di errore HTML al posto del tuo file.

curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"

Metodo 2: con Python (requests)

Nota: richiede la libreria requests (pip install requests).

import os
import time
import requests

API_KEY = os.environ.get("EQUALANG_API_KEY")
# Provide a stable key for the same request, change it for new tasks
IDEMPOTENCY_KEY = os.environ.get("IDEMPOTENCY_KEY", "your-unique-uuid-here")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": IDEMPOTENCY_KEY
}
BASE_URL = "https://equalang.com/v1"

# 1. Create Job
# Ensure you have a local file named report.docx before running
with open("report.docx", "rb") as f:
    files = {"file": f}
    data = {"target_language": "en"}
    response = requests.post(
        f"{BASE_URL}/jobs/translate",
        headers=HEADERS,
        files=files,
        data=data,
        timeout=30
    )
    response.raise_for_status()
    job_id = response.json()["data"]["job_id"]
    print(f"Job created: {job_id}")

# 2. Poll Job
while True:
    res = requests.get(f"{BASE_URL}/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
    res.raise_for_status()
    job_data = res.json()["data"]

    if job_data["finished"]:
        if job_data["status"] == "SUCCEEDED":
            download_url = job_data["download_url"]
            print(f"Success! Downloading result...")

            # 3. Download Result (No API key needed for the temporary URL)
            dl_res = requests.get(download_url, timeout=30)
            dl_res.raise_for_status()
            with open("report_translated.docx", "wb") as out:
                out.write(dl_res.content)
            print("Download complete.")
        else:
            print(f"Job ended with status: {job_data['status']}")
        break

    retry_after = int(res.headers.get("Retry-After", 5))
    time.sleep(retry_after)

Per i casi d'uso avanzati (ad esempio controllare prima il preventivo o recuperare stati di polling persi), puoi scaricare il nostro script avanzato translate_file.py.

---

Riferimento degli endpoint

Ecco i dettagli e gli esempi di struttura del payload per tutti i 10 endpoint pubblici.

Fai riferimento alle enumerazioni DocumentLanguage e TextLanguage nello schema OpenAPI oppure alla guida per sviluppatori per i codici esatti delle lingue supportate (ad esempio zh-CN, en). Il codice auto è riservato a source_language.

1. Traduci il testo

POST /v1/text/translate

Traduci stringhe di testo in modo sincrono. I testi vengono addebitati solo se tradotti con successo. detected_source_language è null se non è stata rilevata automaticamente una lingua specifica.

curl --fail-with-body -X POST "https://equalang.com/v1/text/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["您的订单已发货。"], "target_language": "en"}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "translations": [
      {
        "translated_text": "Your order has been shipped.",
        "detected_source_language": null,
        "error": null
      }
    ],
    "usage": {
      "credits_charged": 0.07
    }
  },
  "request_id": "dd0b35ce1b52474faad670a33a9fc62d"
}

2. Carica un file per il preventivo

POST /v1/files

Se devi mostrare il costo massimo potenziale prima di tradurre, carica qui il file. Restituisce un file_id e un quote (i crediti richiesti).

curl --fail-with-body -X POST "https://equalang.com/v1/files" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@report.docx"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6",
    "quote": {
      "translate": 0.59,
      "transcribe": null
    }
  },
  "request_id": "e81b9f386ace4a82b63dc292c9cff669"
}

3. Crea un job di traduzione del documento

POST /v1/jobs/translate

Crea un job di traduzione asincrono. Accetta file (multipart), file_url o file_id.

# Using a previously uploaded file_id
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6", "target_language": "en"}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "credits_reserved": 0.59
  },
  "request_id": "36c7dc43855b4e9eae553e7fd656788c"
}

4. Crea un job di trascrizione

POST /v1/jobs/transcribe

Estrae e restituisce il testo parlato di un file audio o video sotto forma di sottotitoli con i tempi, senza tradurlo.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/transcribe" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@interview.mp3" \
  -F 'options={"output_formats": ["srt", "txt"]}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "b1a23c45-1234-5678-90ab-cdef12345678",
    "status": "INIT",
    "credits_reserved": 1.848
  },
  "request_id": "req_12345"
}

5. Interroga lo stato del job

GET /v1/jobs/{job_id}

Recupera l'avanzamento e i link di download di un job attivo o completato. Sostituisci {job_id} nel percorso con il tuo UUID reale.

curl --fail-with-body "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "SUCCEEDED",
    "finished": true,
    "progress_percent": 100,
    "download_url": "https://example.com/download/download_url",
    "outputs": [
      {
        "kind": "translation",
        "format": "docx",
        "filename": "supply-terms.zh-cn-equalang-en.docx",
        "download_url": "https://example.com/download/download_url"
      }
    ]
  },
  "request_id": "7c7621312ab04f3da3492db98945e597"
}

6. Scarica i byte del file

GET /v1/files/{file_id}

A differenza del download_url temporaneo (che non richiede la chiave API), questo endpoint ti permette di scaricare direttamente i byte grezzi di qualsiasi file di origine o tradotto archiviato sul tuo account usando il suo file_id. Richiede una chiave API con lo scope files:read.

curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -o translated_result.docx

(Restituisce dati binari direttamente, senza envelope JSON)

7. Annulla un job

POST /v1/jobs/{job_id}/cancel

Annulla un job. Se il job è INIT o QUEUED, diventa immediatamente CANCELLED. Se è RUNNING, passa allo stato CANCELLING fino all'arresto completo.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/cancel" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "CANCELLED",
    "finished": true,
    "usage": {
      "credits_reserved": 0,
      "credits_charged": 0
    }
  },
  "request_id": "502c12dff71149f588620e96b07769fb"
}

8. Riprova un job

POST /v1/jobs/{job_id}/retry

Riprova un job. Puoi riprovare se un job è FAILED e il suo error.retryable è true, o se era CANCELLED. Riprovare riserva di nuovo i crediti. Nota che se il recapito del risultato è fallito (RESULT_DELIVERY_FAILED), ritentare proverà di nuovo il recapito ma non ti addebiterà una seconda volta la traduzione.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/retry" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "finished": false,
    "usage": {
      "credits_reserved": 0.59,
      "credits_charged": 0
    }
  },
  "request_id": "497c3794b0a4497e890f64cc8b7d6d27"
}

9. Elenca i job

GET /v1/jobs

Restituisce un elenco impaginato dei tuoi job di traduzione e trascrizione, a partire dal più recente. Passa limit e cursor (o offset) come parametri di query per impaginare.

curl --fail-with-body "https://equalang.com/v1/jobs?limit=10" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "items": [
      {
        "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
        "status": "SUCCEEDED",
        "task": "translate"
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 39,
    "next_cursor": "MjAyNi0xMC0wOVQxOD..."
  },
  "request_id": "e79cd556afe94424a558e12ca7c2aed8"
}

10. Controlla il saldo dei crediti

GET /v1/credits/balance

Restituisce i crediti disponibili e quelli congelati del tuo account.

curl --fail-with-body "https://equalang.com/v1/credits/balance" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "total_credits": 125.50,
    "frozen_credits": 1.50,
    "available_credits": 124.00
  },
  "request_id": "req_bal_123"
}

Gestione degli errori

Le richieste API non riuscite restituiscono stati di errore HTTP standard accompagnati da un payload di errore che indica il motivo e se l'operazione è retryable.

{
  "code": "INVALID_JOB_ID",
  "message": "Invalid job id",
  "data": null,
  "request_id": "9e97df047da640f7b60e10cfbc571711",
  "retryable": false
}

Fonti

• Documentazione completa dell'API Equalang
• Specifiche OpenAPI di Equalang
• Equalang per sviluppatori